Repository navigation
Add a vintage argument to shapefile_urls(), with the default staying 2010 until 5.0 - #105
Open
nickeubank wants to merge 1 commit into
Open
nickeubank wants to merge 1 commit into
nickeubank wants to merge 1 commit into
Conversation
Member
|
@nickeubank this is a great change, thanks for working through it! Since it is a breaking change I'd want to wait until a 5.0 release and since we just did 4.0 I'm hesitant to jump up to that yet. If the default still pulled from the 2010 files and 2020 could be passed as vintage that would keep existing behavior and I could push this out as a 4.1 release. What do you think? |
Author
|
makes sense to me! Let me put together an update. |
Author
|
Updating and adding a depreciation warning. How would you feel about adding a condition to up the default vintage to 2020 when the version passes 5.0? |
nickeubank
changed the title
`shapefile_urls()` has been pinned to the 2010 TIGER/Line files since it was written. Add a `vintage` argument so callers can ask for the 2020 vintage instead; an unsupported vintage raises ValueError, and states without a FIPS code still return None. The default stays 2010, since changing it outright would break existing callers. Calling without a `vintage` raises a DeprecationWarning saying the default becomes 2020 in us 5.0; passing either vintage explicitly opts out of the warning. The states CLI passes the default explicitly so it tracks the library default without warning its own users. The 2020 vintage isn't a drop-in path swap: the Census Bureau only publishes nationwide files for the cd, county, state and zcta layers, so those URLs are the same for every state. 2020 census blocks live in TABBLOCK20 (TIGER2020/TABBLOCK holds reissued 2010 blocks) and 2020 ZCTAs in ZCTA520; cd is the 116th Congress, the only one in this vintage. Replace the permanently skipped test_head with offline tests covering the default vintage, the deprecation warning, the exact URLs for both vintages, and all 56 states and territories, plus `network`-marked tests that HEAD every generated URL against the Census Bureau. Those use urllib rather than requests, so no new dependency, and are deselected by default since they make a few hundred requests. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
nickeubank
force-pushed
the
shapefiles-2020
branch
from
October 8, 2026 00:12
a13eafd to
59ec707
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
shapefile_urls()has been pinned to the 2010 TIGER/Line files since it was written. This adds avintageargument so callers can ask for the 2020 vintage, without changing what existing callers get back:An unsupported vintage raises
ValueError. States without a FIPS code still returnNone.The default stays 2010 for now
This PR originally flipped the default to 2020. That's a breaking change, so the default stays at 2010 and the switch is only announced. Calling
shapefile_urls()with novintagereturns the 2010 URLs exactly as before, and raises aDeprecationWarning:Passing either vintage explicitly opts out of the warning. The warning uses
stacklevel=2so it's attributed to the caller, matching the existingus.versiondeprecation. Flipping the default in 5.0 is then a two-line change:DEFAULT_SHAPEFILE_VINTAGE = 2020and dropping the warning.The
statesCLI passesvintage=DEFAULT_SHAPEFILE_VINTAGEexplicitly, so it prints 2010 URLs today, picks up the new default automatically in 5.0, and never shows a warning its users can't act on.The 2020 layout isn't a drop-in path swap
Two things changed on the Census side that are worth a look, since they affect what
vintage=2020callers get back:Several layers are nationwide-only in 2020.
https://www2.census.gov/geo/tiger/TIGER2020/has exactly one zip each inCD/,COUNTY/,STATE/andZCTA520/— there are no per-state files any more. Rather than drop those keys and change the dict shape between vintages, they point at the nationwide file, which is identical for every state. Per-state files remain fortract,blockgroupandblock(56 each, matching this package's 50 states + DC + 5 territories exactly).TABBLOCKvsTABBLOCK20.TIGER2020/TABBLOCK/still holds 2010 census blocks reissued in the 2020 vintage; the 2020 blocks live inTABBLOCK20/.blockusesTABBLOCK20. LikewisezctausesZCTA520(2020 ZCTAs) rather thanZCTA5(2010 ZCTAs).cdis the 116th Congress, the only one published in this vintage.Resulting
vintage=2020URLs for MD:TIGER2020/TRACT/tl_2020_24_tract.zipTIGER2020/BG/tl_2020_24_bg.zipTIGER2020/TABBLOCK20/tl_2020_24_tabblock20.zipTIGER2020/CD/tl_2020_us_cd116.zipTIGER2020/COUNTY/tl_2020_us_county.zipTIGER2020/STATE/tl_2020_us_state.zipTIGER2020/ZCTA520/tl_2020_us_zcta520.zipHappy to change the nationwide-layer handling if you'd rather those keys were omitted for 2020 — it seemed better to keep the dict shape stable, but it does mean
us.states.MD.shapefile_urls(vintage=2020)['county'] == us.states.TX.shapefile_urls(vintage=2020)['county'].Tests
The permanently skipped
test_headis replaced with:vintage=2010; the no-argument call raises exactly oneDeprecationWarningwhose message names both vintages, the 5.0 release and bothvintage=spellings, and which is attributed to the calling file (so thestacklevelis right); passing a vintage explicitly raises nothing undersimplefilter("error", DeprecationWarning); exact URLs for both vintages; key coverage across all 56 states and territories;Nonefor FIPS-less obsolete states;ValueErroron a bad vintage.network-marked tests: HEAD every generated URL against the Census Bureau for both vintages. These useurllibfrom the stdlib, so no new dependency —requestsstays undeclared.The network tests are deselected by default via
addopts = "-m 'not network'", since they need network access and make a few hundred requests. Run them with:I ran them while preparing this: all 172 distinct 2020 URLs and all 392 distinct 2010 URLs return 200. Verified on Python 3.8 and 3.14;
ruff check,ruff format --checkandty checkare clean.README and CHANGELOG are updated to match.
🤖 Generated with Claude Code