Welcome to pygeons’s documentation!

Contents:

pygeons

https://img.shields.io/pypi/v/pygeons.svg https://img.shields.io/travis/mpenkov/pygeons.svg Documentation Status Updates

Geographical queries made simple.

Some examples:

>>> from pygeons.api import Country, find_cities
>>> Country('ivory coast')
Country('Ivory Coast')
>>> Country('côte d’ivoire')
Country('Ivory Coast')
>>> Country('civ')
Country('Ivory Coast')
>>> _.iso
'CI'
>>> Country('ivory coast').capital.name
'Yamoussoukro'
>>> Country('ivory coast').neighbors
[Country('Liberia'), Country('Ghana'), Country('Guinea'), Country('Burkina Faso'), Country('Mali')]
>>>
>>> Country('us').cities['moscow']
City.gid(5601538, 'Moscow', 'US')
>>> Country('us').cities['moscow'].admin2
State.gid(5598264, 'ADM2', 'Latah County', 'US')
>>> Country('us').cities['moscow'].admin1
State.gid(5596512, 'ADM1', 'Idaho', 'US')
>>> Country('us').cities['moscow'].distance_to(Country('ru').cities['moscow'])
8375.215117486288
>>>
>>> find_cities("oslo")[:2]
[City.gid(3143244, 'Oslo', 'NO'), City.gid(5040425, 'Oslo', 'US')]

Features

  • Determine if a (city, state and country) combination corresponds to an existing place name
  • Scrub (city, state, country) combinations
  • Normalize city, state and country names to their canonical representations
  • Frame queries in English as well as languages native to each particular country

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

Installation

Stable release

To install pygeons, run this command in your terminal:

$ pip install pygeons

This is the preferred method to install pygeons, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for pygeons can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/mpenkov/pygeons

Or download the tarball:

$ curl  -OL https://github.com/mpenkov/pygeons/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Populating the Database

Pygeons requires data from GeoNames.org. This data is free for sharing and adaptations as long as you abide by the GeoNames license.

Pygeons includes scripts that download and import the data into a local sqlite3 DB. To download the data, run:

python -m pygeons.initialize

This will download approx. 500MB of data from geonames.org. Once the data is imported, the database will live under .pygeons in your home directory. Use the PYGEONS_HOME environment variable to modify this behavior. The data takes several GB, so make sure you have enough space.

Usage

To use pygeons in a project:

import pygeons

pygeons package

Module contents

Top-level package for pygeons.

Implements low-level database structures and functions.

Expects you to call connect() before you do anything with the DB.

Expects the database to be initialized. If it is not, see pygeons.initialize.

By default, the database lives under $HOME/.pygeons. You can modify this behavior using the PYGEONS_HOME environment variable. You can also specify the subdirectory explicitly when you call connect().

class pygeons.db.CountryInfo(iso, iso3, iso_numeric, fips, country, capital, area, population, continent, tld, currency_code, currency_name, phone, postal_code_format, postal_code_regex, languages, geonameid, neighbors, equivalent_fips_code)

Bases: tuple

area

Alias for field number 6

capital

Alias for field number 5

continent

Alias for field number 8

country

Alias for field number 4

currency_code

Alias for field number 10

currency_name

Alias for field number 11

equivalent_fips_code

Alias for field number 18

fips

Alias for field number 3

geonameid

Alias for field number 16

iso

Alias for field number 0

iso3

Alias for field number 1

iso_numeric

Alias for field number 2

languages

Alias for field number 15

neighbors

Alias for field number 17

phone

Alias for field number 12

population

Alias for field number 7

postal_code_format

Alias for field number 13

postal_code_regex

Alias for field number 14

tld

Alias for field number 9

class pygeons.db.Geoname(geonameid, name, asciiname, alternatenames, latitude, longitude, feature_class, feature_code, country_code, cc2, admin1_code, admin2_code, admin3_code, admin4_code, population, elevation, dem, timezone, modification_date)

Bases: tuple

admin1_code

Alias for field number 10

admin2_code

Alias for field number 11

admin3_code

Alias for field number 12

admin4_code

Alias for field number 13

alternatenames

Alias for field number 3

asciiname

Alias for field number 2

cc2

Alias for field number 9

country_code

Alias for field number 8

dem

Alias for field number 16

elevation

Alias for field number 15

feature_class

Alias for field number 6

feature_code

Alias for field number 7

geonameid

Alias for field number 0

latitude

Alias for field number 4

longitude

Alias for field number 5

modification_date

Alias for field number 18

name

Alias for field number 1

population

Alias for field number 14

timezone

Alias for field number 17

pygeons.db.connect(subdir: str = '/home/docs/.pygeons') → None[source]
pygeons.db.country_info(name: str) → pygeons.db.CountryInfo[source]
>>> connect()
>>> i = country_info('ru')
>>> (i.country, i.population, i.currency_name)
('Russia', 144478050, 'Ruble')
pygeons.db.get_alternatenames(geonameid: str) → List[Tuple[str, str]][source]
pygeons.db.select_geonames(subcommand: str, params: Iterable[Any]) → List[pygeons.db.Geoname][source]
pygeons.db.select_geonames_ids(ids: Iterable[int], country_code: Optional[str] = None) → List[pygeons.db.Geoname][source]
pygeons.db.select_geonames_name(name: str) → List[pygeons.db.Geoname][source]

Initialize data structures.

Downloads approx. 500MB of data from geonames.org.

pygeons.initialize.build_trie(db_path: str, marisa_path: str) → None[source]
pygeons.initialize.init_alternatename(db_path: str, fin: IO[str]) → None[source]
pygeons.initialize.init_countryinfo(db_path: str) → None[source]
pygeons.initialize.init_geoname(db_path: str, fin: IO[str]) → None[source]
pygeons.initialize.init_postcode(db_path: str, fin: IO[str]) → None[source]
pygeons.initialize.main()[source]

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/mpenkov/pygeons/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

pygeons could always use more documentation, whether as part of the official pygeons docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/mpenkov/pygeons/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up pygeons for local development.

  1. Fork the pygeons repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/pygeons.git

  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv pygeons
$ cd pygeons/
$ python setup.py develop

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 pygeons tests
$ python setup.py test or py.test
$ tox

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for the relevant versions of Python. Check https://travis-ci.org/mpenkov/pygeons/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ py.test tests.test_pygeons

To run documentation tests:

$ python -m doctest pygeons/*.py

Credits

Development Lead

Contributors

None yet. Why not be the first?

History

0.9.1 (2020-09-17)

  • Added top-level G` collection to pygeons.api
  • Implemented handling for alternative place names

0.9.0 (2020-09-11)

  • Added new API
  • Switched database backend from MongoDB to sqlite3
  • Implemented import scripts in Python

0.1.1 (2017-12-03)

  • First working release. Includes import scripts and source code.

0.1.0 (2017-11-26)

  • First release on PyPI.

Indices and tables