Skip to content

Commit

Permalink
Port docstrings to Sphinx syntax
Browse files Browse the repository at this point in the history
  • Loading branch information
@tiwilliam
tiwilliam committed Feb 2, 2014
1 parent 1e08687 commit ac10b6a
Showing 1 changed file with 26 additions and 65 deletions.
91 changes: 26 additions & 65 deletions pygeoip/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@ class _GeoIPMetaclass(type):
_instance_lock = Lock()

def __call__(cls, *args, **kwargs):
""" Singleton method to gets an instance without reparsing
"""
Singleton method to gets an instance without reparsing
the database, the filename is being used as cache key.
"""
if len(args) > 0:
Expand Down Expand Up @@ -83,17 +84,14 @@ class GeoIP(object):

def __init__(self, filename, flags=0, cache=True):
"""
Initialize the class.
Create and return an GeoIP instance.
@param filename: Path to a geoip database.
@type filename: str
@param flags: Flags that affect how the database is processed.
Currently supported flags are STANDARD (the default),
:arg filename: File path to a GeoIP database
:arg flags: Flags that affect how the database is processed.
Currently supported flags are STANDARD (default),
MEMORY_CACHE (preload the whole file into memory) and
MMAP_CACHE (access the file via mmap).
@type flags: int
@param cache: Used in tests to skip instance caching
@type cache: bool
MMAP_CACHE (access the file via mmap)
:arg cache: Used in tests to skip instance caching
"""
self._lock = Lock()
self._flags = flags
Expand Down Expand Up @@ -131,22 +129,6 @@ def _setup_segments(self):
Parses the database file to determine what kind of database is
being used and setup segment sizes and start points that will
be used by the seek*() methods later.
Supported databases:
* COUNTRY_EDITION
* COUNTRY_EDITION_V6
* REGION_EDITION_REV0
* REGION_EDITION_REV1
* CITY_EDITION_REV0
* CITY_EDITION_REV1
* CITY_EDITION_REV1_V6
* ORG_EDITION
* ISP_EDITION
* ASNUM_EDITION
* ASNUM_EDITION_V6
* NETSPEED_EDITION
"""
self._databaseType = const.COUNTRY_EDITION
self._recordLength = const.STANDARD_RECORD_LENGTH
Expand Down Expand Up @@ -210,11 +192,9 @@ def _seek_country(self, ipnum):
"""
Using the record length and appropriate start points, seek to the
country that corresponds to the converted IP address integer.
Return offset of record.
@param ipnum: result of ip2long conversion
@type ipnum: int
@return: offset of start of record
@rtype: int
:arg ipnum: Result of ip2long conversion
"""
try:
offset = 0
Expand Down Expand Up @@ -261,10 +241,9 @@ def _seek_country(self, ipnum):
def _get_org(self, ipnum):
"""
Seek and return organization or ISP name for ipnum.
@param ipnum: Converted IP address
@type ipnum: int
@return: org/isp name
@rtype: str
Return org/isp name.
:arg ipnum: Result of ip2long conversion
"""
seek_org = self._seek_country(ipnum)
if seek_org == self._databaseSegments:
Expand All @@ -286,11 +265,9 @@ def _get_org(self, ipnum):
def _get_region(self, ipnum):
"""
Seek and return the region information.
Returns dict containing country_code and region_code.
@param ipnum: Converted IP address
@type ipnum: int
@return: dict containing country_code and region_code
@rtype: dict
:arg ipnum: Result of ip2long conversion
"""
region_code = None
country_code = None
Expand Down Expand Up @@ -332,13 +309,9 @@ def get_region_code(offset):
def _get_record(self, ipnum):
"""
Populate location dict for converted IP.
Returns dict with numerous location properties.
@param ipnum: Converted IP address
@type ipnum: int
@return: dict with city, region_code, area_code, time_zone,
dma_code, metro_code, country_code3, latitude, postal_code,
longitude, country_code, country_name, continent
@rtype: dict
:arg ipnum: Result of ip2long conversion
"""
seek_country = self._seek_country(ipnum)
if seek_country == self._databaseSegments:
Expand Down Expand Up @@ -407,6 +380,9 @@ def read_data(buf, pos):
return record

def _gethostbyname(self, hostname):
"""
Hostname lookup method, supports both IPv4 and IPv6.
"""
if self._databaseType in const.IPV6_EDITIONS:
response = socket.getaddrinfo(hostname, 0, socket.AF_INET6)
family, socktype, proto, canonname, sockaddr = response[0]
Expand All @@ -417,26 +393,20 @@ def _gethostbyname(self, hostname):

def id_by_name(self, hostname):
"""
Returns the database id for specified hostname.
Returns the database ID for specified hostname.
The id might be useful as array index. 0 is unknown.
@param hostname: Hostname
@type hostname: str
@return: network byte order 32-bit integer
@rtype: int
:arg hostname: Hostname to get ID from.
"""
addr = self._gethostbyname(hostname)
return self.id_by_addr(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.
@param addr: IPv4 or IPv6 address
@type addr: str
@return: network byte order 32-bit integer
@rtype: int
:arg addr: IPv4 or IPv6 address (eg. 127.0.0.1)
"""
ipv = 6 if addr.find(':') >= 0 else 4
if ipv == 4 and self._databaseType not in (const.COUNTRY_EDITION, const.NETSPEED_EDITION):
Expand All @@ -450,9 +420,6 @@ def id_by_addr(self, addr):
def last_netmask(self):
"""
Return the netmask depth of the last lookup.
@return: network depth
@rtype: int
"""
return self._netmask

Expand All @@ -461,10 +428,7 @@ 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.
@param addr: IP address
@type addr: str
@return: 2-letter country code
@rtype: str
:arg addr: IP address (eg. 127.0.0.1)
"""
VALID_EDITIONS = (const.COUNTRY_EDITION, const.COUNTRY_EDITION_V6)
if self._databaseType in VALID_EDITIONS:
Expand All @@ -480,10 +444,7 @@ 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.
@param hostname: Hostname
@type hostname: str
@return: 2-letter country code
@rtype: str
:arg hostname: Hostname (eg. example.com)
"""
addr = self._gethostbyname(hostname)
return self.country_code_by_addr(addr)
Expand Down

0 comments on commit ac10b6a

Please sign in to comment.