Skip to content

P
pygeoip
Commit 42c6bf8d by William Tisäter
Options

Setup Sphinx pages and re-use our README as index

parent ac10b6a9
Showing with 182 additions and 226 deletions
README.rst
Pure Python GeoIP API Pure Python GeoIP API
===================== =====================
This library is based on `Maxmind's GeoIP C This library is based on `Maxmind's GeoIP C API <https://github.com/maxmind/geoip-api-c>`__.
API <https://github.com/maxmind/geoip-api-c>`__.
Tested with Python version 2.6, 2.7, 3.2 and 3.3. Tested with Python version 2.6, 2.7, 3.2 and 3.3.
...@@ -26,132 +25,21 @@ contribute you can always `create a pull ...@@ -26,132 +25,21 @@ contribute you can always `create a pull
request <https://github.com/appliedsec/pygeoip/pulls>`__ for discussion request <https://github.com/appliedsec/pygeoip/pulls>`__ for discussion
and code submission. and code submission.
Getting Started Documentation
--------------- -------------
Create your GeoIP instance with appropriate access flag. ``STANDARD`` .. toctree::
reads data from disk when needed, ``MEMORY_CACHE`` loads database into :maxdepth: 1
memory on instantiation and ``MMAP_CACHE`` loads database into memory
using mmap.
.. code:: python getting-started
supported-databases
api-reference
>>> import pygeoip For more information, `check out the documentation <http://pygeoip.readthedocs.org/>`__ over at Read the Docs.
>>> gi = pygeoip.GeoIP('/path/to/GeoIP.dat')
>>> gi.country_name_by_addr('64.233.161.99')
'United States'
Country Lookup
~~~~~~~~~~~~~~
.. code:: python
>>> gi = pygeoip.GeoIP('/path/to/GeoIP.dat')
>>> gi.country_code_by_name('google.com')
'US'
>>> gi.country_code_by_addr('64.233.161.99')
'US'
>>> gi.country_name_by_addr('64.233.161.99')
'United States'
.. code:: python
>>> gi = pygeoip.GeoIP('/path/to/GeoIPv6.dat')
>>> gi.country_code_by_name('google.com')
'IE'
>>> gi.country_code_by_addr('2001:7fd::1')
'EU'
>>> gi.country_name_by_addr('2001:7fd::1')
'Europe'
Region Lookup
~~~~~~~~~~~~~
.. code:: python
>>> gi = pygeoip.GeoIP('/path/to/GeoIPRegion.dat')
>>> gi.region_by_name('apple.com')
{'region_code': 'CA', 'country_code': 'US'}
City Lookup
~~~~~~~~~~~
.. code:: python
>>> gi = pygeoip.GeoIP('/path/to/GeoIPCity.dat')
>>> gi.record_by_addr('64.233.161.99')
{
'city': u'Mountain View',
'region_code': u'CA',
'area_code': 650,
'time_zone': 'America/Los_Angeles',
'dma_code': 807,
'metro_code': 'San Francisco, CA',
'country_code3': 'USA',
'latitude': 37.41919999999999,
'postal_code': u'94043',
'longitude': -122.0574,
'country_code': 'US',
'country_name': 'United States',
'continent': 'NA'
}
>>> gi.time_zone_by_addr('64.233.161.99')
'America/Los_Angeles'
Organization Lookup
~~~~~~~~~~~~~~~~~~~
.. code:: python
>>> gi = pygeoip.GeoIP('/path/to/GeoIPOrg.dat')
>>> gi.org_by_name('dell.com')
'Dell Computer Corporation'
ISP Lookup
~~~~~~~~~~
.. code:: python
>>> gi = pygeoip.GeoIP('/path/to/GeoIPISP.dat')
>>> gi.isp_by_name('cnn.com')
'Turner Broadcasting System'
ASN Lookup
~~~~~~~~~~
.. code:: python
>>> gi = pygeoip.GeoIP('/path/to/GeoIPASNum.dat')
>>> gi.asn_by_name('cnn.com')
'AS5662 Turner Broadcasting'
For more information, `check out the full API
documentation <http://packages.python.org/pygeoip>`__.
Supported Databases
-------------------
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Type | IPv4 | IPv6 | Details |
+================+========+========+===================================================================================+
| Country | ✓ | ✓ | `MaxMind Country product page <http://www.maxmind.com/en/country>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| City | ✓ | ✓ | `MaxMind City product page <http://www.maxmind.com/en/city>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Organization | ✓ | | `MaxMind Organization product page <http://www.maxmind.com/en/organization>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| ISP | ✓ | | `MaxMind ISP product page <http://www.maxmind.com/en/isp>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Region | ✓ | | `MaxMind Region product page <http://www.maxmind.com/en/geolocation_landing>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| ASN | ✓ | ✓ | `MaxMind ASN product page <http://dev.maxmind.com/geoip/legacy/geolite>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Netspeed | ✓ | | `MaxMind Netspeed product page <http://www.maxmind.com/en/netspeed>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
.. |Build Status| image:: https://api.travis-ci.org/appliedsec/pygeoip.png?branch=master .. |Build Status| image:: https://api.travis-ci.org/appliedsec/pygeoip.png?branch=master
:target: https://travis-ci.org/appliedsec/pygeoip :target: https://travis-ci.org/appliedsec/pygeoip
.. |Coverage Status| image:: https://coveralls.io/repos/appliedsec/pygeoip/badge.png .. |Coverage Status| image:: https://coveralls.io/repos/appliedsec/pygeoip/badge.png
:target: https://coveralls.io/r/appliedsec/pygeoip :target: https://coveralls.io/r/appliedsec/pygeoip
.. |Downloads| image:: https://pypip.in/d/pygeoip/badge.png .. |Downloads| image:: https://pypip.in/d/pygeoip/badge.png
:target: https://crate.io/packages/pygeoip :target: https://crate.io/packages/pygeoip
docs/api-reference.rst 0 → 100644
API Reference
=============
.. currentmodule:: pygeoip
GeoIP
-----
.. autoclass:: GeoIP
:members: __init__, country_code_by_addr, country_code_by_name, country_name_by_addr, country_name_by_name, org_by_addr, org_by_name, record_by_addr, record_by_name, region_by_addr, region_by_name, time_zone_by_addr, time_zone_by_name, netspeed_by_addr, netspeed_by_name, id_by_addr, last_netmask
GeoIPError
----------
.. autoexception:: GeoIPError
docs/getting-started.rst 0 → 100644
Getting Started
===============
Create your GeoIP instance with appropriate access flag. ``STANDARD``
reads data from disk when needed, ``MEMORY_CACHE`` loads database into
memory on instantiation and ``MMAP_CACHE`` loads database into memory
using mmap.
.. code:: python
>>> import pygeoip
>>> gi = pygeoip.GeoIP('GeoIP.dat')
>>> gi.country_name_by_addr('64.233.161.99')
'United States'
Country Lookup
--------------
.. code:: python
>>> gi = pygeoip.GeoIP('GeoIP.dat')
>>> gi.country_code_by_name('google.com')
'US'
>>> gi.country_code_by_addr('64.233.161.99')
'US'
>>> gi.country_name_by_addr('64.233.161.99')
'United States'
.. code:: python
>>> gi = pygeoip.GeoIP('GeoIPv6.dat')
>>> gi.country_code_by_addr('2a00:1450:400f:802::1006')
'IE'
Region Lookup
-------------
.. code:: python
>>> gi = pygeoip.GeoIP('GeoIPRegion.dat')
>>> gi.region_by_name('apple.com')
{'region_code': 'CA', 'country_code': 'US'}
City Lookup
-----------
.. code:: python
>>> gi = pygeoip.GeoIP('GeoIPCity.dat')
>>> gi.record_by_addr('64.233.161.99')
{
'city': u'Mountain View',
'region_code': u'CA',
'area_code': 650,
'time_zone': 'America/Los_Angeles',
'dma_code': 807,
'metro_code': 'San Francisco, CA',
'country_code3': 'USA',
'latitude': 37.41919999999999,
'postal_code': u'94043',
'longitude': -122.0574,
'country_code': 'US',
'country_name': 'United States',
'continent': 'NA'
}
>>> gi.time_zone_by_addr('64.233.161.99')
'America/Los_Angeles'
Organization Lookup
-------------------
.. code:: python
>>> gi = pygeoip.GeoIP('GeoIPOrg.dat')
>>> gi.org_by_name('dell.com')
'Dell Computer Corporation'
ISP Lookup
----------
.. code:: python
>>> gi = pygeoip.GeoIP('GeoIPISP.dat')
>>> gi.isp_by_name('cnn.com')
'Turner Broadcasting System'
ASN Lookup
----------
.. code:: python
>>> gi = pygeoip.GeoIP('GeoIPASNum.dat')
>>> gi.asn_by_name('cnn.com')
'AS5662 Turner Broadcasting'
docs/index.rst deleted 100644 → 0
====================================================
Pure Python API for Maxmind's binary GeoIP databases
====================================================
.. currentmodule:: pygeoip
Work in progress!
:class:`GeoIP` methods
----------------------
.. automethod:: GeoIP.__init__
Country lookup
''''''''''''''
.. automethod:: GeoIP.country_code_by_addr
.. automethod:: GeoIP.country_code_by_name
.. toctree
\ No newline at end of file
docs/index.rst 0 → 120000
../README.rst
\ No newline at end of file
docs/supported-databases.rst 0 → 100644
Supported Databases
===================
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Type | IPv4 | IPv6 | Details |
+================+========+========+===================================================================================+
| Country | ✓ | ✓ | `MaxMind Country product page <http://www.maxmind.com/en/country>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| City | ✓ | ✓ | `MaxMind City product page <http://www.maxmind.com/en/city>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Organization | ✓ | | `MaxMind Organization product page <http://www.maxmind.com/en/organization>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| ISP | ✓ | | `MaxMind ISP product page <http://www.maxmind.com/en/isp>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Region | ✓ | | `MaxMind Region product page <http://www.maxmind.com/en/geolocation_landing>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| ASN | ✓ | ✓ | `MaxMind ASN product page <http://dev.maxmind.com/geoip/legacy/geolite>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
| Netspeed | ✓ | | `MaxMind Netspeed product page <http://www.maxmind.com/en/netspeed>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
\ No newline at end of file
pygeoip/__init__.py
...@@ -47,6 +47,10 @@ ENCODING = const.ENCODING ...@@ -47,6 +47,10 @@ ENCODING = const.ENCODING
class GeoIPError(Exception): class GeoIPError(Exception):
"""
Thin wrapper of `Exception`, will be thrown in case of an
unrecoverable error.
"""
pass pass
...@@ -82,7 +86,7 @@ class _GeoIPMetaclass(type): ...@@ -82,7 +86,7 @@ class _GeoIPMetaclass(type):
class GeoIP(object): class GeoIP(object):
__metaclass__ = _GeoIPMetaclass __metaclass__ = _GeoIPMetaclass
def __init__(self, filename, flags=0, cache=True): def __init__(self, filename, flags=STANDARD, cache=True):
""" """
Create and return an GeoIP instance. Create and return an GeoIP instance.
...@@ -404,9 +408,9 @@ class GeoIP(object): ...@@ -404,9 +408,9 @@ class GeoIP(object):
def id_by_addr(self, addr): def id_by_addr(self, addr):
""" """
Returns the database ID for specified address. Returns the database ID for specified address.
The id might be useful as array index. 0 is unknown. The ID might be useful as array index. 0 is unknown.
:arg addr: IPv4 or IPv6 address (eg. 127.0.0.1) :arg addr: IPv4 or IPv6 address (eg. 203.0.113.30)
""" """
ipv = 6 if addr.find(':') >= 0 else 4 ipv = 6 if addr.find(':') >= 0 else 4
if ipv == 4 and self._databaseType not in (const.COUNTRY_EDITION, const.NETSPEED_EDITION): if ipv == 4 and self._databaseType not in (const.COUNTRY_EDITION, const.NETSPEED_EDITION):
...@@ -419,16 +423,15 @@ class GeoIP(object): ...@@ -419,16 +423,15 @@ class GeoIP(object):
def last_netmask(self): def last_netmask(self):
""" """
Return the netmask depth of the last lookup. Returns the netmask depth of the last lookup.
""" """
return self._netmask return self._netmask
def country_code_by_addr(self, addr): def country_code_by_addr(self, addr):
""" """
Returns 2-letter country code (e.g. 'US') for specified IP address. Returns 2-letter country code (e.g. US) from IP address.
Use this method if you have a Country, Region, or City database.
:arg addr: IP address (eg. 127.0.0.1) :arg addr: IP address (e.g. 203.0.113.30)
""" """
VALID_EDITIONS = (const.COUNTRY_EDITION, const.COUNTRY_EDITION_V6) VALID_EDITIONS = (const.COUNTRY_EDITION, const.COUNTRY_EDITION_V6)
if self._databaseType in VALID_EDITIONS: if self._databaseType in VALID_EDITIONS:
...@@ -441,10 +444,9 @@ class GeoIP(object): ...@@ -441,10 +444,9 @@ class GeoIP(object):
def country_code_by_name(self, hostname): def country_code_by_name(self, hostname):
""" """
Returns 2-letter country code (e.g. 'US') for specified hostname. Returns 2-letter country code (e.g. US) from hostname.
Use this method if you have a Country, Region, or City database.
:arg hostname: Hostname (eg. example.com) :arg hostname: Hostname (e.g. example.com)
""" """
addr = self._gethostbyname(hostname) addr = self._gethostbyname(hostname)
return self.country_code_by_addr(addr) return self.country_code_by_addr(addr)
...@@ -453,21 +455,16 @@ class GeoIP(object): ...@@ -453,21 +455,16 @@ class GeoIP(object):
""" """
Returns NetSpeed name from address. Returns NetSpeed name from address.
@param hostname: IP address :arg addr: IP address (e.g. 203.0.113.30)
@type hostname: str
@return: netspeed name
@rtype: str
""" """
return const.NETSPEED_NAMES[self.id_by_addr(addr)] return const.NETSPEED_NAMES[self.id_by_addr(addr)]
def netspeed_by_name(self, hostname): def netspeed_by_name(self, hostname):
""" """
Returns NetSpeed name from hostname. Returns NetSpeed name from hostname. Can be Unknown, Dial-up,
Cable, or Corporate.
@param hostname: Hostname :arg hostname: Hostname (e.g. example.com)
@type hostname: str
@return: netspeed name
@rtype: str
""" """
addr = self._gethostbyname(hostname) addr = self._gethostbyname(hostname)
return self.netspeed_by_addr(addr) return self.netspeed_by_addr(addr)
...@@ -475,12 +472,8 @@ class GeoIP(object): ...@@ -475,12 +472,8 @@ class GeoIP(object):
def country_name_by_addr(self, addr): def country_name_by_addr(self, addr):
""" """
Returns full country name for specified IP address. Returns full country name for specified IP address.
Use this method if you have a Country or City database.
@param addr: IP address :arg addr: IP address (e.g. 203.0.113.30)
@type addr: str
@return: country name
@rtype: str
""" """
VALID_EDITIONS = (const.COUNTRY_EDITION, const.COUNTRY_EDITION_V6) VALID_EDITIONS = (const.COUNTRY_EDITION, const.COUNTRY_EDITION_V6)
if self._databaseType in VALID_EDITIONS: if self._databaseType in VALID_EDITIONS:
...@@ -495,25 +488,17 @@ class GeoIP(object): ...@@ -495,25 +488,17 @@ class GeoIP(object):
def country_name_by_name(self, hostname): def country_name_by_name(self, hostname):
""" """
Returns full country name for specified hostname. Returns full country name for specified hostname.
Use this method if you have a Country database.
@param hostname: Hostname :arg hostname: Hostname (e.g. example.com)
@type hostname: str
@return: country name
@rtype: str
""" """
addr = self._gethostbyname(hostname) addr = self._gethostbyname(hostname)
return self.country_name_by_addr(addr) return self.country_name_by_addr(addr)
def org_by_addr(self, addr): def org_by_addr(self, addr):
""" """
Lookup Organization, ISP or ASNum for given IP address. Returns Organization, ISP, or ASNum name for given IP address.
Use this method if you have an Organization, ISP or ASNum database.
@param addr: IP address :arg addr: IP address (e.g. 203.0.113.30)
@type addr: str
@return: organization or ISP name
@rtype: str
""" """
valid = (const.ORG_EDITION, const.ISP_EDITION, const.ASNUM_EDITION, const.ASNUM_EDITION_V6) valid = (const.ORG_EDITION, const.ISP_EDITION, const.ASNUM_EDITION, const.ASNUM_EDITION_V6)
if self._databaseType not in valid: if self._databaseType not in valid:
...@@ -525,13 +510,9 @@ class GeoIP(object): ...@@ -525,13 +510,9 @@ class GeoIP(object):
def org_by_name(self, hostname): def org_by_name(self, hostname):
""" """
Lookup the organization (or ISP) for hostname. Returns Organization, ISP, or ASNum name for given hostname.
Use this method if you have an Organization/ISP database.
@param hostname: Hostname :arg hostname: Hostname (e.g. example.com)
@type hostname: str
@return: Organization or ISP name
@rtype: str
""" """
addr = self._gethostbyname(hostname) addr = self._gethostbyname(hostname)
return self.org_by_addr(addr) return self.org_by_addr(addr)
...@@ -543,15 +524,11 @@ class GeoIP(object): ...@@ -543,15 +524,11 @@ class GeoIP(object):
def record_by_addr(self, addr): def record_by_addr(self, addr):
""" """
Look up the record for a given IP address. Returns dictionary with city data containing `country_code`, `country_name`,
Use this method if you have a City database. `region`, `city`, `postal_code`, `latitude`, `longitude`, `dma_code`,
`metro_code`, `area_code`, `region_code` and `time_zone`.
@param addr: IP address :arg addr: IP address (e.g. 203.0.113.30)
@type addr: str
@return: Dictionary with country_code, country_code3, country_name,
region, city, postal_code, latitude, longitude, dma_code,
metro_code, area_code, region_code, time_zone
@rtype: dict
""" """
if self._databaseType not in const.CITY_EDITIONS: if self._databaseType not in const.CITY_EDITIONS:
message = 'Invalid database type, expected City' message = 'Invalid database type, expected City'
...@@ -566,28 +543,20 @@ class GeoIP(object): ...@@ -566,28 +543,20 @@ class GeoIP(object):
def record_by_name(self, hostname): def record_by_name(self, hostname):
""" """
Look up the record for a given hostname. Returns dictionary with city data containing `country_code`, `country_name`,
Use this method if you have a City database. `region`, `city`, `postal_code`, `latitude`, `longitude`, `dma_code`,
`metro_code`, `area_code`, `region_code` and `time_zone`.
@param hostname: Hostname :arg hostname: Hostname (e.g. example.com)
@type hostname: str
@return: Dictionary with country_code, country_code3, country_name,
region, city, postal_code, latitude, longitude, dma_code,
metro_code, area_code, region_code, time_zone
@rtype: dict
""" """
addr = self._gethostbyname(hostname) addr = self._gethostbyname(hostname)
return self.record_by_addr(addr) return self.record_by_addr(addr)
def region_by_addr(self, addr): def region_by_addr(self, addr):
""" """
Lookup the region for given IP address. Returns dictionary containing `country_code` and `region_code`.
Use this method if you have a Region database.
@param addr: IP address :arg addr: IP address (e.g. 203.0.113.30)
@type addr: str
@return: Dictionary containing country_code and region_code
@rtype: dict
""" """
if self._databaseType not in const.REGION_CITY_EDITIONS: if self._databaseType not in const.REGION_CITY_EDITIONS:
message = 'Invalid database type, expected Region or City' message = 'Invalid database type, expected Region or City'
...@@ -598,26 +567,18 @@ class GeoIP(object): ...@@ -598,26 +567,18 @@ class GeoIP(object):
def region_by_name(self, hostname): def region_by_name(self, hostname):
""" """
Lookup the region for given hostname. Returns dictionary containing `country_code` and `region_code`.
Use this method if you have a Region database.
@param hostname: Hostname :arg hostname: Hostname (e.g. example.com)
@type hostname: str
@return: Dictionary containing country_code, region_code and region
@rtype: dict
""" """
addr = self._gethostbyname(hostname) addr = self._gethostbyname(hostname)
return self.region_by_addr(addr) return self.region_by_addr(addr)
def time_zone_by_addr(self, addr): def time_zone_by_addr(self, addr):
""" """
Look up the time zone for a given IP address. Returns timezone in tzdata format (e.g. America/New_York or Europe/Paris)
Use this method if you have a Region or City database.
@param addr: IP address :arg addr: IP address (e.g. 203.0.113.30)
@type addr: str
@return: Time zone
@rtype: str
""" """
if self._databaseType not in const.CITY_EDITIONS: if self._databaseType not in const.CITY_EDITIONS:
message = 'Invalid database type, expected City' message = 'Invalid database type, expected City'
...@@ -628,13 +589,9 @@ class GeoIP(object): ...@@ -628,13 +589,9 @@ class GeoIP(object):
def time_zone_by_name(self, hostname): def time_zone_by_name(self, hostname):
""" """
Look up the time zone for a given hostname. Returns timezone in tzdata format (e.g. America/New_York or Europe/Paris)
Use this method if you have a Region or City database.
@param hostname: Hostname :arg hostname: Hostname (e.g. example.com)
@type hostname: str
@return: Time zone
@rtype: str
""" """
addr = self._gethostbyname(hostname) addr = self._gethostbyname(hostname)
return self.time_zone_by_addr(addr) return self.time_zone_by_addr(addr)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment