Package Health Score

80 / 100

security
No known security issues
popularity
Popular
maintenance
Sustainable
community
Active

Explore Similar Packages

nepal
35

Popularity

Popular

GitHub Stars: 483
Forks: 70
Contributors: 20

Direct Usage Popularity

Based on project statistics from the GitHub repository for the PyPI package us, we found that it has been starred 483 times.

Security

No known security issues

Security and license risk for latest version

Release Date: Jul 22, 2024
Direct Vulnerabilities: 0
C
0
H
0
M
0
L
Indirect Vulnerabilities: 0
C
0
H
0
M
0
L
License Risk: 0
H
0
M
0
L

All security vulnerabilities belong to production dependencies of direct and indirect packages.

License

BSD-3-Clause

Security Policy

We found a way for you to contribute to the project! Looks like us is missing a security policy.

You can connect your project's repository to Snyk to stay up to date on security alerts and receive automatic fix pull requests.

Keep your project free of vulnerabilities with Snyk

Maintenance

Sustainable

Commit Frequency

Open Issues: 19
Open PR: 3
Last Release: 4 months ago
Last Commit: 4 months ago

Further analysis of the maintenance status of us based on released PyPI versions cadence, the repository activity, and other data points determined that its maintenance is Sustainable.

We found that us demonstrates a positive version release cadence with at least one new version released in the past 12 months.

As a healthy sign for on-going project maintenance, we found that the GitHub repository had at least 1 pull request or issue interacted with by the community.

Community

Active

Readme: Yes
Contributing.md: Yes
Code of Conduct: No
Contributors: 20
Funding: No

With more than 10 contributors for the us repository, this is possibly a sign for a growing and inviting community.

We found a way for you to contribute to the project! Looks like us is missing a Code of Conduct.

Embed Package Health Score Badge

Keep your project healthy

Check your requirements.txt

Ensure all the packages you're using are healthy and well-maintained

Snyk Vulnerability Scanner

Get health score & security insights directly in your IDE

Package

Python Versions Compatibility: >=3.8

Age: 12 years
Latest Release: 4 months ago
Dependencies: 1 Direct
Versions: 17
Maintainers: 1
Wheels: OS Independent

Readme

US: The Greatest Package in the World

A package for easily working with US and state metadata.

all US states and territories
postal abbreviations
Associated Press style abbreviations
FIPS codes
capitals
years of statehood
time zones
phonetic state name lookup
is contiguous or continental
URLs to shapefiles for state, census, congressional districts, counties, and census tracts

Installation

As per usual:

pip install us

Features

Easy access to state information:

&gt;&gt;&gt; import us
&gt;&gt;&gt; us.states.MD

&gt;&gt;&gt; us.states.MD.fips
'24'
&gt;&gt;&gt; us.states.MD.name
'Maryland'
&gt;&gt;&gt; us.states.MD.is_contiguous
True

Includes territories too:

&gt;&gt;&gt; us.states.VI.name
'Virgin Islands'
&gt;&gt;&gt; us.states.VI.is_territory
True
&gt;&gt;&gt; us.states.MD.is_territory
False

List of all (actual) states:

&gt;&gt;&gt; us.states.STATES
[, , , , ...
&gt;&gt;&gt; us.states.TERRITORIES
[, , , ...

And the whole shebang, if you want it:

&gt;&gt;&gt; us.states.STATES_AND_TERRITORIES
[, , , ...

For convenience, STATES, TERRITORIES, and STATES_AND_TERRITORIES can be accessed directly from the us module:

&gt;&gt;&gt; us.states.STATES
[, , , , ...
&gt;&gt;&gt; us.STATES
[, , , , ...

Some states like to be fancy and call themselves commonwealths:

&gt;&gt;&gt; us.states.COMMONWEALTHS
[, , , ]

There's also a list of obsolete territories:

&gt;&gt;&gt; us.states.OBSOLETE
[, , ]

The state lookup method allows matching by FIPS code, abbreviation, and name:

&gt;&gt;&gt; us.states.lookup('24')

&gt;&gt;&gt; us.states.lookup('MD')

&gt;&gt;&gt; us.states.lookup('md')

&gt;&gt;&gt; us.states.lookup('maryland')

Get useful information:

&gt;&gt;&gt; state = us.states.lookup('maryland')
&gt;&gt;&gt; state.abbr
'MD'

And for those days that you just can't remember how to spell Mississippi, we've got phonetic name matching too:

&gt;&gt;&gt; us.states.lookup('misisipi')

Shapefiles

You want shapefiles too? As long as you want 2010 shapefiles, we've gotcha covered.

&gt;&gt;&gt; urls = us.states.MD.shapefile_urls()
&gt;&gt;&gt; sorted(urls.keys())
['block', 'blockgroup', 'cd', 'county', 'state', 'tract', 'zcta']
&gt;&gt;&gt; urls['block']
'https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip'

The shapefile_urls() method on the State object generates shapefile URLs for the following regions:

block
blockgroup
census tract (tract)
congressional district (cd)
county
state
zcta

Mappings

Mappings between various state attributes are a common need. The mapping() method will generate a lookup between two specified fields.

&gt;&gt;&gt; us.states.mapping('fips', 'abbr')
{'01': 'AL', '02': 'AK', '04': 'AZ', '05': 'AR', '06': 'CA', ...
&gt;&gt;&gt; us.states.mapping('abbr', 'name')
{'AL': 'Alabama', 'AK': 'Alaska', 'AZ': 'Arizona', 'AR': 'Arkansas', ...

This method uses us.STATES_AND_TERRITORIES as the default list of states it will create a mapping for, but this can be overridden by passing an additional states argument:

&gt;&gt;&gt; us.states.mapping('fips', 'abbr', states=[us.states.DC])
{'11': 'DC'}

DC should be granted statehood

Washington, DC does not appear in us.STATES or any of the related state lists, but is often treated as a state in practice and should be granted statehood anyway. DC can be automatically included in these lists by setting a DC_STATEHOOD environment variable to any truthy value before importing this package.

DC_STATEHOOD=1

CLI

When you need to know state information RIGHT AWAY, there's the states script.

$ states md

*** The great state of Maryland (MD) ***

    FIPS code: 24

    other attributes:
      ap_abbr: Md.
      capital: Annapolis
      capital_tz: America/New_York
      is_contiguous: True
      is_continental: True
      is_obsolete: False
      name_metaphone: MRLNT
      statehood_year: 1788
      time_zones: America/New_York

    shapefiles:
      tract: https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_24_tract10.zip
      cd: https://www2.census.gov/geo/tiger/TIGER2010/CD/111/tl_2010_24_cd111.zip
      county: https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip
      state: https://www2.census.gov/geo/tiger/TIGER2010/STATE/2010/tl_2010_24_state10.zip
      zcta: https://www2.census.gov/geo/tiger/TIGER2010/ZCTA5/2010/tl_2010_24_zcta510.zip
      block: https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip
      blockgroup: https://www2.census.gov/geo/tiger/TIGER2010/BG/2010/tl_2010_24_bg10.zip

Running Tests

GitHub Actions are set up to automatically run unit tests against any new commits to the repo. To run these tests yourself:

pip install -e .[dev]
pytest .

Changelog

3.2.0

add support for Python 3.12
drop support for Python 3.6 and 3.7
add birthday attribute to unitedstatesofamerica
upgrade to jellyfish 1.x
thanks to Paul Hawk, David Gilman, Sergii Bondarenko, and Pedro Camargo

3.1.1

add support for Python 3.11
upgrade to jellyfish 0.11.2

3.0.0

upgrade to jellyfish 0.7.2
drop support for Python 2.7
add us.states.COMMONWEALTHS list of states that call themselves commonwealths 🎩
add DC to STATES, STATES_AND_TERRITORIES, STATES_CONTIGUOUS, or STATES_CONTINENTAL when DC_STATEHOOD environment variable is set
remove region parameter from shapefile_urls() method
mapping() no longer includes obsolete states
added type annotations

2.0.2

restore DC in lookup() and mapping()

2.0.1

fix Python 2.7 tests that ran with Python 3
revert to jellyfish 0.6.1 to support Python 2.7

2.0.0

add support for Python 3.7 and 3.8
remove support for Python 3.4 and 3.5
remove pickled objects and database in favor of pure Python code
upgrade jellyfish to 0.7.2 to fix metaphone bug
fixes for IN, KY, ND, and NM timezones
set AZ timezone to America/Phoenix
obsolete entries are no longer included in STATES_AND_TERRITORIES
DC is no longer included in STATES, STATES_AND_TERRITORIES, STATES_CONTIGUOUS, or STATES_CONTINENTAL

1.0.0

full Python 3.6 support
use pytest

0.10.0

upgrade jellyfish to 0.5.3 to fix metaphone bug

0.9.0

add information on whether a state is contiguous and/or continental, thanks to chebee7i

0.8.0

add obsolete territories, thanks to Ben Chartoff
fix packaging error, thanks to Alexander Kulakov

0.7.1

upgrade to jellyfish 0.5.1 to fix metaphone case bug

0.7

add time zones, thanks to Paul Tagliamonte
Python 2.6 and 3.2 compatibility

0.6

add AP-style state abbreviations
use jellyfish instead of Metaphone package
update to requests v1.0.4 for tests
Python 3.3 compatibility

0.5

fix state abbreviation for Nebraska

0.4

add state capitals
add years of statehood

0.3

add mapping method to generate dicts of arbitrary fields

0.2

add command line script for quick access to state data

0.1

initial release
state names and abbreviations
FIPS codes
lookup() method
shapefile URLs for various regions

us dependencies

jellyfish

FAQs

What is us?

US state meta information and other fun stuff. Visit Snyk Advisor to see a full health score report for us, including popularity, security, maintenance & community analysis.

Is us popular?

The python package us receives a total of 104,910 weekly downloads. As such, us popularity was classified as a popular. Visit the popularity section on Snyk Advisor to see the full health analysis.

Is us well maintained?

We found indications that us maintenance is sustainable demonstrating some project activity. We saw a total of 20 open source contributors collaborating on the project. See the full package health analysis to learn more about the package maintenance status.

Is us safe to use?

The python package us was scanned for known vulnerabilities and missing license, and no issues were found. Thus the package was deemed as safe to use. See the full health analysis review.

Last updated on 23 November-2024, at 07:39 (UTC).

Build a secure application checklist

Select a recommended open source package

Minimize your risk by selecting secure & well maintained open source packages

DONE

Scan your app for vulnerabilities

Scan your application to find vulnerabilities in your: source code, open source dependencies, containers and configuration files

SCAN NOW

Fix identified vulnerabilities

Easily fix your code by leveraging automatically generated PRs

AUTO FIX

Monitor for new issues

New vulnerabilities are discovered every day. Get notified if your application is affected

MONITOR APP