Metadata-Version: 2.1
Name: easy-geoparsing
Version: 1.2.3
Summary: Easy-to-use module for streamlined parsing of countries from locations
Home-page: UNKNOWN
Author: PaddyAlton
Author-email: paddy.alton@apolitical.co
License: UNKNOWN
Download-URL: https://github.com/apolitical/easy-geoparsing/archive/v1.2.3.tar.gz
Description: easy-geoparsing
        ---
        
        Easy-to-use module for streamlined parsing of countries from plaintext locations and top-level domains, plus manipulation of country names and ISO 2 & 3 character codes.
        
        Implementation relies on:
        
        - the [RESTcountries](https://restcountries.eu/) API
        - the [geotext](https://pypi.org/project/geotext/) module
        
        ## installation
        
        To install from the command line via [pip](https://pip.pypa.io/en/stable/), do:
        
        `pip install easy-geoparsing`
        
        To upgrade to the latest version via `pip` do:
        
        `pip install easy-geoparsing --upgrade`
        
        To use via [pipenv](https://docs.pipenv.org/en/latest/) put the following in your Pipfile:
        
        ```
        [packages]
        easy-geoparsing = ">=1.0.0"
        ```
        
        ## development
        
        If you've cloned the repository, the best way to make it work is using `pipenv`
        
        If you don't yet have `pipenv`, you can use `pip` to install it from the command line:
        
        `pip install pipenv --upgrade`
        
        Then, in the top level directory of this repository, `easy-geoparsing`, do:
        
        `pipenv install --dev`
        
        This will create the virtual environment and install the requirements (viewable in the Pipfile). The `--dev` flag will install packages needed for testing etc.
        
        ## usage
        
        ### GETTING STARTED
        
        Do the following to get the parser utilities, noting that creating an instance of `EasyCountryParser` will automatically download the country data payload from RESTcountries and set up all the resources. Speed will therefore depend on your internet connection, but the payload is not large.
        
        ```
        from easy_geoparsing import EasyCountryParser
        
        ez_parser = EasyCountryParser()
        ```
        
        or, if you don't want to use our alternative names for some of the countries (i.e. you want to exactly follow the RESTcountries standard)
        
        `ez_parser = EasyCountryParser(altnames=False)`
        
        The `EasyCountryParser` class provides utilities, based on the data from the RESTcountries API and the GeoText natural-language parser library, for easily extracting and handling country names and codes.
        
        ### PARSER RESOURCES
        
        The parser is initialised with the following resources:
        
          - `.data`       - pandas DataFrame containing RESTcountries data
          - `.tld_to_a2c` - python dict, maps TLDs to 2-character ISO codes
          - `.tld_to_a3c` - python dict, maps TLDs to 3-character ISO codes
          - `.iso2to3`    - python dict, maps 2-character ISO codes to 3
          - `.iso3to2`    - python dict, maps 3-character ISO codes to 2
          - `.a2c_map`    - python dict, maps 2-char ISO codes to full names
          - `.a3c_map`    - python dict, maps 3-char ISO codes to full names
        
        ### PARSER METHODS
        
        The parser has the following methods for handling locations data:
        
          - `.retrieve_country` - parses plaintext for extractable 2-character ISO codes for countries (which can then be manipulated using the mappers above)
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
