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
=====================
This library is based on `Maxmind's GeoIP C
API <https://github.com/maxmind/geoip-api-c>`__.
This library is based on `Maxmind's GeoIP C API <https://github.com/maxmind/geoip-api-c>`__.
Tested with Python version 2.6, 2.7, 3.2 and 3.3.
......@@ -26,132 +25,21 @@ contribute you can always `create a pull
request <https://github.com/appliedsec/pygeoip/pulls>`__ for discussion
and code submission.
Getting Started
---------------
Documentation
-------------
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.
.. toctree::
:maxdepth: 1
.. code:: python
getting-started
supported-databases
api-reference
>>> import pygeoip
>>> 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>`__ |
+----------------+--------+--------+-----------------------------------------------------------------------------------+
For more information, `check out the documentation <http://pygeoip.readthedocs.org/>`__ over at Read the Docs.
.. |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
:target: https://coveralls.io/r/appliedsec/pygeoip
:target: https://coveralls.io/r/appliedsec/pygeoip
.. |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
class GeoIPError(Exception):
"""
Thin wrapper of `Exception`, will be thrown in case of an
unrecoverable error.
"""
pass
......@@ -82,7 +86,7 @@ class _GeoIPMetaclass(type):
class GeoIP(object):
__metaclass__ = _GeoIPMetaclass
def __init__(self, filename, flags=0, cache=True):
def __init__(self, filename, flags=STANDARD, cache=True):
"""
Create and return an GeoIP instance.
......@@ -404,9 +408,9 @@ class GeoIP(object):
def id_by_addr(self, addr):
"""
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
if ipv == 4 and self._databaseType not in (const.COUNTRY_EDITION, const.NETSPEED_EDITION):
......@@ -419,16 +423,15 @@ class GeoIP(object):
def last_netmask(self):
"""
Return the netmask depth of the last lookup.
Returns the netmask depth of the last lookup.
"""
return self._netmask
def country_code_by_addr(self, addr):
"""
Returns 2-letter country code (e.g. 'US') for specified IP address.
Use this method if you have a Country, Region, or City database.
Returns 2-letter country code (e.g. US) from IP address.
: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)
if self._databaseType in VALID_EDITIONS:
......@@ -441,10 +444,9 @@ class GeoIP(object):
def country_code_by_name(self, hostname):
"""
Returns 2-letter country code (e.g. 'US') for specified hostname.
Use this method if you have a Country, Region, or City database.
Returns 2-letter country code (e.g. US) from hostname.
:arg hostname: Hostname (eg. example.com)
:arg hostname: Hostname (e.g. example.com)
"""
addr = self._gethostbyname(hostname)
return self.country_code_by_addr(addr)
......@@ -453,21 +455,16 @@ class GeoIP(object):
"""
Returns NetSpeed name from address.
@param hostname: IP address
@type hostname: str
@return: netspeed name
@rtype: str
:arg addr: IP address (e.g. 203.0.113.30)
"""
return const.NETSPEED_NAMES[self.id_by_addr(addr)]
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
@type hostname: str
@return: netspeed name
@rtype: str
:arg hostname: Hostname (e.g. example.com)
"""
addr = self._gethostbyname(hostname)
return self.netspeed_by_addr(addr)
......@@ -475,12 +472,8 @@ class GeoIP(object):
def country_name_by_addr(self, addr):
"""
Returns full country name for specified IP address.
Use this method if you have a Country or City database.
@param addr: IP address
@type addr: str
@return: country name
@rtype: str
:arg addr: IP address (e.g. 203.0.113.30)
"""
VALID_EDITIONS = (const.COUNTRY_EDITION, const.COUNTRY_EDITION_V6)
if self._databaseType in VALID_EDITIONS:
......@@ -495,25 +488,17 @@ class GeoIP(object):
def country_name_by_name(self, hostname):
"""
Returns full country name for specified hostname.
Use this method if you have a Country database.
@param hostname: Hostname
@type hostname: str
@return: country name
@rtype: str
:arg hostname: Hostname (e.g. example.com)
"""
addr = self._gethostbyname(hostname)
return self.country_name_by_addr(addr)
def org_by_addr(self, addr):
"""
Lookup Organization, ISP or ASNum for given IP address.
Use this method if you have an Organization, ISP or ASNum database.
Returns Organization, ISP, or ASNum name for given IP address.
@param addr: IP address
@type addr: str
@return: organization or ISP name
@rtype: str
:arg addr: IP address (e.g. 203.0.113.30)
"""
valid = (const.ORG_EDITION, const.ISP_EDITION, const.ASNUM_EDITION, const.ASNUM_EDITION_V6)
if self._databaseType not in valid:
......@@ -525,13 +510,9 @@ class GeoIP(object):
def org_by_name(self, hostname):
"""
Lookup the organization (or ISP) for hostname.
Use this method if you have an Organization/ISP database.
Returns Organization, ISP, or ASNum name for given hostname.
@param hostname: Hostname
@type hostname: str
@return: Organization or ISP name
@rtype: str
:arg hostname: Hostname (e.g. example.com)
"""
addr = self._gethostbyname(hostname)
return self.org_by_addr(addr)
......@@ -543,15 +524,11 @@ class GeoIP(object):
def record_by_addr(self, addr):
"""
Look up the record for a given IP address.
Use this method if you have a City database.
Returns dictionary with city data containing `country_code`, `country_name`,
`region`, `city`, `postal_code`, `latitude`, `longitude`, `dma_code`,
`metro_code`, `area_code`, `region_code` and `time_zone`.
@param addr: IP address
@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
:arg addr: IP address (e.g. 203.0.113.30)
"""
if self._databaseType not in const.CITY_EDITIONS:
message = 'Invalid database type, expected City'
......@@ -566,28 +543,20 @@ class GeoIP(object):
def record_by_name(self, hostname):
"""
Look up the record for a given hostname.
Use this method if you have a City database.
Returns dictionary with city data containing `country_code`, `country_name`,
`region`, `city`, `postal_code`, `latitude`, `longitude`, `dma_code`,
`metro_code`, `area_code`, `region_code` and `time_zone`.
@param hostname: Hostname
@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
:arg hostname: Hostname (e.g. example.com)
"""
addr = self._gethostbyname(hostname)
return self.record_by_addr(addr)
def region_by_addr(self, addr):
"""
Lookup the region for given IP address.
Use this method if you have a Region database.
Returns dictionary containing `country_code` and `region_code`.
@param addr: IP address
@type addr: str
@return: Dictionary containing country_code and region_code
@rtype: dict
:arg addr: IP address (e.g. 203.0.113.30)
"""
if self._databaseType not in const.REGION_CITY_EDITIONS:
message = 'Invalid database type, expected Region or City'
......@@ -598,26 +567,18 @@ class GeoIP(object):
def region_by_name(self, hostname):
"""
Lookup the region for given hostname.
Use this method if you have a Region database.
Returns dictionary containing `country_code` and `region_code`.
@param hostname: Hostname
@type hostname: str
@return: Dictionary containing country_code, region_code and region
@rtype: dict
:arg hostname: Hostname (e.g. example.com)
"""
addr = self._gethostbyname(hostname)
return self.region_by_addr(addr)
def time_zone_by_addr(self, addr):
"""
Look up the time zone for a given IP address.
Use this method if you have a Region or City database.
Returns timezone in tzdata format (e.g. America/New_York or Europe/Paris)
@param addr: IP address
@type addr: str
@return: Time zone
@rtype: str
:arg addr: IP address (e.g. 203.0.113.30)
"""
if self._databaseType not in const.CITY_EDITIONS:
message = 'Invalid database type, expected City'
......@@ -628,13 +589,9 @@ class GeoIP(object):
def time_zone_by_name(self, hostname):
"""
Look up the time zone for a given hostname.
Use this method if you have a Region or City database.
Returns timezone in tzdata format (e.g. America/New_York or Europe/Paris)
@param hostname: Hostname
@type hostname: str
@return: Time zone
@rtype: str
:arg hostname: Hostname (e.g. example.com)
"""
addr = self._gethostbyname(hostname)
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