Skip to content

Commit e306bdb

Browse files
oschwaldoschwald
committed
More work on the docs
1 parent a0154f5 commit e306bdb

File tree

6 files changed

+421
-43
lines changed

6 files changed

+421
-43
lines changed

‎docs/index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,21 @@
66
MaxMind GeoIP2 Python API
77
=========================
88

9+
.. automodule:: geoip2
10+
:members:
11+
912
.. automodule:: geoip2.webservices
1013
:members:
1114

15+
.. automodule:: geoip2.models
16+
:members:
17+
18+
.. automodule:: geoip2.records
19+
:members:
20+
21+
.. automodule:: geoip2.errors
22+
:members:
23+
1224
Indices and tables
1325
==================
1426

‎geoip2/__init__.py‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
"""
2+
Python API for MaxMind's GeoIP Precision web services and GeoIP2 databases
3+
========================================================================
4+
5+
Description
6+
-----------
7+
8+
Currently, this distribution provides an API for the GeoIP2 Precision web
9+
services (as documented at http://dev.maxmind.com/geoip/precision).
10+
11+
In the future, this distribution will also provide the same API for the GeoIP2
12+
downloadable databases. These databases have not yet been released as a
13+
downloadable product.
14+
15+
See geoip2.webservices.Client for details on the web service client API.
16+
17+
Integration with GeoNames
18+
-------------------------
19+
20+
GeoNames (http://www.geonames.org/) offers web services and downloadable
21+
databases with data on geographical features around the world, including
22+
populated places. They offer both free and paid premium data. Each feature is
23+
unique identified by a ``geoname_id``, which is an integer.
24+
25+
Many of the records returned by the GeoIP web services and databases include a
26+
``geoname_id`` field. This is the ID of a geographical feature (city, region,
27+
country, etc.) in the GeoNames database.
28+
29+
Some of the data that MaxMind provides is also sourced from GeoNames. We
30+
source things like place names, ISO codes, and other similar data from the
31+
GeoNames premium data set.
32+
33+
Reporting Data Problems
34+
-----------------------
35+
36+
If the problem you find is that an IP address is incorrectly mapped, please
37+
submit your correction to MaxMind at http://www.maxmind.com/en/correction.
38+
39+
If you find some other sort of mistake, like an incorrect spelling, please
40+
check the GeoNames site (http://www.geonames.org/) first. Once you've searched
41+
for a place and found it on the GeoNames map view, there are a number of links
42+
you can use to correct data ("move", "edit", "alternate names", etc.). Once
43+
the correction is part of the GeoNames data set, it will be automatically
44+
incorporated into future MaxMind releases.
45+
46+
If you are a paying MaxMind customer and you're not sure where to submit a
47+
correction, please contact MaxMind support at
48+
http://www.maxmind.com/en/support for help.
49+
50+
Python version support
51+
----------------------
52+
53+
This code requires Python 2.6+ or 3.0+. Older versions are not supported.
54+
55+
Support
56+
-------
57+
58+
Please report all issues with this code using the GitHub issue tracker at
59+
https://github.com/maxmind/GeoIP2-python/issues
60+
61+
If you are having an issue with a MaxMind service that is not specific to the
62+
client API please see http://www.maxmind.com/en/support for details.
63+
64+
"""

‎geoip2/errors.py‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,43 @@
1+
"""
2+
Errors
3+
======
4+
5+
"""
6+
7+
18
class GeoIP2Error(RuntimeError):
2-
"""There was a generic error in GeoIP2."""
9+
"""There was a generic error in GeoIP2.
10+
11+
This class represents a generic error. It extends ``RuntimeError``
12+
and does not add any additional attributes.
13+
14+
"""
315

416

517
class GeoIP2HTTPError(GeoIP2Error):
6-
"""There was an error when making your HTTP request."""
18+
"""There was an error when making your HTTP request.
19+
20+
This class represents an HTTP transport error. It extends
21+
``GeoIP2Error`` and adds attributes of its own.
22+
23+
:ivar http_status: The HTTP status code returned
24+
:ivar uri: The URI queried
25+
"""
726
def __init__(self, message, http_status=None, uri=None):
827
super(GeoIP2HTTPError, self).__init__(message)
928
self.http_status = http_status
1029
self.uri = uri
1130

1231

1332
class GeoIP2WebServiceError(GeoIP2HTTPError):
14-
"""The GeoIP2 web service returned an error."""
33+
"""The GeoIP2 web service returned an error.
34+
35+
This class represents an error returned by MaxMind's GeoIP2 Precision
36+
web service. It extends ``GeoIP2HTTPError``.
37+
38+
:ivar http_status: The HTTP status code returned
39+
:ivar uri: The URI queried
40+
"""
1541
def __init__(self, message, code=None, http_status=None, uri=None):
1642
super(GeoIP2WebServiceError, self).__init__(message, http_status, uri)
1743
self.code = code

‎geoip2/models.py‎

Lines changed: 93 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,37 @@
1+
"""
2+
Models
3+
======
4+
5+
These classes provide models for the data returned by the GeoIP2
6+
Precision City end point.
7+
8+
The only difference between the City, City/ISP/Org, and Omni model classes is
9+
which fields in each record may be populated. See
10+
http://dev.maxmind.com/geoip/precision for more details.
11+
12+
"""
113
import geoip2.records
214

315

416
class Country(object):
17+
"""Model class for the GeoIP2 Precision Country end point
18+
19+
This class provides the following methods, each of which returns a record
20+
object.
21+
22+
:ivar continent: Returns a ``geoip2.records.Continent`` object
23+
representing continent data for the requested IP address.
24+
:ivar country: Returns a ``geoip2.recordsCountry`` object representing
25+
country data for the requested IP address. This record represents the
26+
country where MaxMind believes the IP is located in.
27+
:ivar registered_country: Returns a ``geoip2.recordsCountry`` object
28+
representing the registered country data for the requested IP address.
29+
This record represents the country where the ISP has registered a given
30+
IP block in and may differ from the user's country.
31+
:ivar traits: Returns ``a geoip2.records.Traits`` object representing
32+
the traits for the request IP address.
33+
34+
"""
535
def __init__(self, raw_response, languages=None):
636
if languages is None:
737
languages = ['en']
@@ -20,6 +50,27 @@ def __init__(self, raw_response, languages=None):
2050

2151

2252
class City(Country):
53+
"""Model class for the GeoIP2 Precision City end point
54+
55+
:ivar city: Returns a ``geoip2.records.City`` object representing
56+
country data for the requested IP address.
57+
:ivar continent: Returns a ``geoip2.records.Continent`` object
58+
representing continent data for the requested IP address.
59+
:ivar country: Returns a ``geoip2.recordsCountry`` object representing
60+
country data for the requested IP address. This record represents the
61+
country where MaxMind believes the IP is located in.
62+
:ivar location: Returns a ``geoip2.records.Location`` object
63+
representing country data for the requested IP address.
64+
:ivar region: Returns a ``geoip2.records.Region`` object representing
65+
country data for the requested IP address.
66+
:ivar registered_country: Returns a ``geoip2.recordsCountry`` object
67+
representing the registered country data for the requested IP address.
68+
This record represents the country where the ISP has registered a given
69+
IP block in and may differ from the user's country.
70+
:ivar traits: Returns ``a geoip2.records.Traits`` object representing
71+
the traits for the request IP address.
72+
73+
"""
2374
def __init__(self, raw_response, languages=None):
2475
super(City, self).__init__(raw_response, languages)
2576
self.city = \
@@ -32,8 +83,48 @@ def __init__(self, raw_response, languages=None):
3283

3384

3485
class CityISPOrg(City):
35-
pass
86+
"""Model class for the GeoIP2 Precision City/ISP/Org end point
87+
88+
:ivar city: Returns a ``geoip2.records.City`` object representing
89+
country data for the requested IP address.
90+
:ivar continent: Returns a ``geoip2.records.Continent`` object
91+
representing continent data for the requested IP address.
92+
:ivar country: Returns a ``geoip2.recordsCountry`` object representing
93+
country data for the requested IP address. This record represents the
94+
country where MaxMind believes the IP is located in.
95+
:ivar location: Returns a ``geoip2.records.Location`` object
96+
representing country data for the requested IP address.
97+
:ivar region: Returns a ``geoip2.records.Region`` object representing
98+
country data for the requested IP address.
99+
:ivar registered_country: Returns a ``geoip2.recordsCountry`` object
100+
representing the registered country data for the requested IP address.
101+
This record represents the country where the ISP has registered a given
102+
IP block in and may differ from the user's country.
103+
:ivar traits: Returns ``a geoip2.records.Traits`` object representing
104+
the traits for the request IP address.
105+
106+
"""
36107

37108

38109
class Omni(CityISPOrg):
39-
pass
110+
"""Model class for the GeoIP2 Precision Omni end point
111+
112+
:ivar city: Returns a ``geoip2.records.City`` object representing
113+
country data for the requested IP address.
114+
:ivar continent: Returns a ``geoip2.records.Continent`` object
115+
representing continent data for the requested IP address.
116+
:ivar country: Returns a ``geoip2.recordsCountry`` object representing
117+
country data for the requested IP address. This record represents the
118+
country where MaxMind believes the IP is located in.
119+
:ivar location: Returns a ``geoip2.records.Location`` object
120+
representing country data for the requested IP address.
121+
:ivar region: Returns a ``geoip2.records.Region`` object representing
122+
country data for the requested IP address.
123+
:ivar registered_country: Returns a ``geoip2.recordsCountry`` object
124+
representing the registered country data for the requested IP address.
125+
This record represents the country where the ISP has registered a given
126+
IP block in and may differ from the user's country.
127+
:ivar traits: Returns ``a geoip2.records.Traits`` object representing
128+
the traits for the request IP address.
129+
130+
"""

0 commit comments

Comments
 (0)