Metadata-Version: 1.0
Name: us
Version: 0.2
Summary: UNKNOWN
Home-page: https://github.com/sunlightlabs/python-us
Author: Jeremy Carbaugh
Author-email: jcarbaugh@sunlightfoundation.com
License: BSD
Description: US: The Greatest Package in the World
        =====================================
        
        A package for easily working with US and state metadata.
        
        * all US states and territories
        * abbreviations
        * FIPS codes
        * phonetic state name lookup
        * URLs to shapefiles for state, census, congressional districts,
          counties, and census tracts
        
        Congratulations, DC. As far as this package is concerned, you've got statehood.
        
        
        Installation
        ------------
        
        As per usual: ::
        
            pip install us
        
        
        Features
        --------
        
        Easy access to state information: ::
        
            >>> import us
            >>> us.states.MD
            <State:Maryland>
            >>> us.states.MD.fips
            u'24'
            >>> us.states.MD.name
            u'Maryland'
        
        Includes territories too: ::
        
            >>> us.states.VI.name
            u'Virgin Islands'
            >>> us.states.VI.is_territory
            True
            >>> us.states.MD.is_territory
            False
        
        List of all (proper) states: ::
        
            >>> us.states.STATES
            [<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>,...
            >>> us.states.TERRITORIES
            [<State:American Samoa>, <State:Guam>, <State:Northern Mariana Islands>,...
        
        And the whole shebang, if you want it: ::
        
            >>> us.states.STATES_AND_TERRITORIES
            [<State:Alabama>, <State:Alaska>, <State:American Samoa>,...
        
        For convenience, `STATES`, `TERRITORIES`, and `STATES_AND_TERRITORIES` can be
        access directly from the `us` module: ::
        
            >>> us.states.STATES
            [<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>,...
            >>> us.STATES
            [<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>,...
        
        The state lookup method allows matching by FIPS code, abbreviation, and name: ::
        
            >>> us.states.lookup('24')
            <State:Maryland>
            >>> us.states.lookup('MD')
            <State:Maryland>
            >>> us.states.lookup('md')
            <State:Maryland>
            >>> us.states.lookup('maryland')
            <State:Maryland>
        
        And for those days that you just can't remember how to spell Mississippi,
        we've got phonetic name matching too: ::
        
            >>> us.states.lookup('misisipi')
            <State:Mississippi>
        
        
        Shapefiles
        ----------
        
        You want shapefiles too? Gotcha covered.
        
        ::
        
            >>> shpurls = us.states.MD.shapefile_urls()
            >>> for region, url in shpurls.items():
            ...   print "%s: %s" % (region, url)
            ...
            county: http://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip
            state: http://www2.census.gov/geo/tiger/TIGER2010/STATE/2010/tl_2010_24_state10.zip
            cd: http://www2.census.gov/geo/tiger/TIGER2010/CD/111/tl_2010_24_cd111.zip
            zcta: http://www2.census.gov/geo/tiger/TIGER2010/ZCTA5/2010/tl_2010_24_zcta510.zip
            tract: http://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_24_tract10.zip
        
        The `shapefile_urls()` method on the State object generates shapefile URLs for
        the following regions:
        
        * state
        * county
        * congressional district
        * zcta
        * census tract
        
        If you know what region you want, you can explicitly request it: ::
        
            >>> us.states.MD.shapefile_urls('county')
            u'http://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip'
        
Platform: any
