Debian Codegraph @

django/contrib/gis/geoip2.py

raw ◀ ▶
1 Debian patch touch this file
1 """
2 This module houses the GeoIP2 object, a wrapper for the MaxMind GeoIP2(R)
3 Python API (https://geoip2.readthedocs.io/). This is an alternative to the
4 Python GeoIP2 interface provided by MaxMind.
5
6 GeoIP(R) is a registered trademark of MaxMind, Inc.
7
8 For IP-based geolocation, this module requires the GeoLite2 Country and City
9 datasets, in binary format (CSV will not work!). The datasets may be
10 downloaded from MaxMind at https://dev.maxmind.com/geoip/geoip2/geolite2/.
11 Grab GeoLite2-Country.mmdb.gz and GeoLite2-City.mmdb.gz, and unzip them in the
12 directory corresponding to settings.GEOIP_PATH.
13 """
14
15 import ipaddress
16 import socket
17 import warnings
18
19 from django.conf import settings
20 from django.core.exceptions import ValidationError
21 from django.core.validators import validate_ipv46_address
22 from django.utils._os import to_path
23 from django.utils.deprecation import RemovedInDjango60Warning
24 from django.utils.functional import cached_property
25
26 __all__ = ["HAS_GEOIP2"]
27
28 try:
29 import geoip2.database
30 except ImportError: # pragma: no cover
31 HAS_GEOIP2 = False
32 else:
33 HAS_GEOIP2 = True
34 __all__ += ["GeoIP2", "GeoIP2Exception"]
35
36
37 # These are the values stored in the `database_type` field of the metadata.
38 # See https://maxmind.github.io/MaxMind-DB/#database_type for details.
39 SUPPORTED_DATABASE_TYPES = {
40 "DBIP-City-Lite",
41 "DBIP-Country-Lite",
42 "GeoIP2-City",
43 "GeoIP2-Country",
44 "GeoLite2-City",
45 "GeoLite2-Country",
46 }
47
48
49 class GeoIP2Exception(Exception):
50 pass
51
52
53 class GeoIP2:
54 # The flags for GeoIP memory caching.
55 # Try MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that order.
56 MODE_AUTO = 0
57 # Use the C extension with memory map.
58 MODE_MMAP_EXT = 1
59 # Read from memory map. Pure Python.
60 MODE_MMAP = 2
61 # Read database as standard file. Pure Python.
62 MODE_FILE = 4
63 # Load database into memory. Pure Python.
64 MODE_MEMORY = 8
65 cache_options = frozenset(
66 (MODE_AUTO, MODE_MMAP_EXT, MODE_MMAP, MODE_FILE, MODE_MEMORY)
67 )
68
69 _path = None
70 _reader = None
71
72 def __init__(self, path=None, cache=0, country=None, city=None):
73 """
74 Initialize the GeoIP object. No parameters are required to use default
75 settings. Keyword arguments may be passed in to customize the locations
76 of the GeoIP datasets.
77
78 * path: Base directory to where GeoIP data is located or the full path
79 to where the city or country data files (*.mmdb) are located.
80 Assumes that both the city and country data sets are located in
81 this directory; overrides the GEOIP_PATH setting.
•82 If neither is set, defaults to '/usr/share/GeoIP'.
83
84 * cache: The cache settings when opening up the GeoIP datasets. May be
85 an integer in (0, 1, 2, 4, 8) corresponding to the MODE_AUTO,
86 MODE_MMAP_EXT, MODE_MMAP, MODE_FILE, and MODE_MEMORY,
87 `GeoIPOptions` C API settings, respectively. Defaults to 0,
88 meaning MODE_AUTO.
89
90 * country: The name of the GeoIP country data file. Defaults to
91 'GeoLite2-Country.mmdb'; overrides the GEOIP_COUNTRY setting.
92
93 * city: The name of the GeoIP city data file. Defaults to
94 'GeoLite2-City.mmdb'; overrides the GEOIP_CITY setting.
95 """
96 if cache not in self.cache_options:
97 raise GeoIP2Exception("Invalid GeoIP caching option: %s" % cache)
98
•99 path = path or getattr(settings, "GEOIP_PATH", "/usr/share/GeoIP")
100 city = city or getattr(settings, "GEOIP_CITY", "GeoLite2-City.mmdb")
101 country = country or getattr(settings, "GEOIP_COUNTRY", "GeoLite2-Country.mmdb")
102
103 if not path:
104 raise GeoIP2Exception(
105 "GeoIP path must be provided via parameter or the GEOIP_PATH setting."
106 )
107
108 path = to_path(path)
109
110 # Try the path first in case it is the full path to a database.
111 for path in (path, path / city, path / country):
112 if path.is_file():
113 self._path = path
114 self._reader = geoip2.database.Reader(path, mode=cache)
115 break
116 else:
117 raise GeoIP2Exception(
118 "Path must be a valid database or directory containing databases."
119 )
120
121 database_type = self._metadata.database_type
122 if database_type not in SUPPORTED_DATABASE_TYPES:
123 raise GeoIP2Exception(f"Unable to handle database edition: {database_type}")
124
125 def __del__(self):
126 # Cleanup any GeoIP file handles lying around.
127 if self._reader:
128 self._reader.close()
129
130 def __repr__(self):
131 m = self._metadata
132 version = f"v{m.binary_format_major_version}.{m.binary_format_minor_version}"
133 return f"<{self.__class__.__name__} [{version}] _path='{self._path}'>"
134
135 @cached_property
136 def _metadata(self):
137 return self._reader.metadata()
138
139 @cached_property
140 def is_city(self):
141 return "City" in self._metadata.database_type
142
143 @cached_property
144 def is_country(self):
145 return "Country" in self._metadata.database_type
146
147 def _query(self, query, *, require_city=False):
148 if not isinstance(query, (str, ipaddress.IPv4Address, ipaddress.IPv6Address)):
149 raise TypeError(
150 "GeoIP query must be a string or instance of IPv4Address or "
151 "IPv6Address, not type %s" % type(query).__name__,
152 )
153
154 if require_city and not self.is_city:
155 raise GeoIP2Exception(f"Invalid GeoIP city data file: {self._path}")
156
157 if isinstance(query, str):
158 try:
159 validate_ipv46_address(query)
160 except ValidationError:
161 # GeoIP2 only takes IP addresses, so try to resolve a hostname.
162 query = socket.gethostbyname(query)
163
164 function = self._reader.city if self.is_city else self._reader.country
165 return function(query)
166
167 def city(self, query):
168 """
169 Return a dictionary of city information for the given IP address or
170 Fully Qualified Domain Name (FQDN). Some information in the dictionary
171 may be undefined (None).
172 """
173 response = self._query(query, require_city=True)
174 region = response.subdivisions[0] if response.subdivisions else None
175 return {
176 "accuracy_radius": response.location.accuracy_radius,
177 "city": response.city.name,
178 "continent_code": response.continent.code,
179 "continent_name": response.continent.name,
180 "country_code": response.country.iso_code,
181 "country_name": response.country.name,
182 "is_in_european_union": response.country.is_in_european_union,
183 "latitude": response.location.latitude,
184 "longitude": response.location.longitude,
185 "metro_code": response.location.metro_code,
186 "postal_code": response.postal.code,
187 "region_code": region.iso_code if region else None,
188 "region_name": region.name if region else None,
189 "time_zone": response.location.time_zone,
190 # Kept for backward compatibility.
191 "dma_code": response.location.metro_code,
192 "region": region.iso_code if region else None,
193 }
194
195 def country_code(self, query):
196 "Return the country code for the given IP Address or FQDN."
197 return self.country(query)["country_code"]
198
199 def country_name(self, query):
200 "Return the country name for the given IP Address or FQDN."
201 return self.country(query)["country_name"]
202
203 def country(self, query):
204 """
205 Return a dictionary with the country code and name when given an
206 IP address or a Fully Qualified Domain Name (FQDN). For example, both
207 '24.124.1.80' and 'djangoproject.com' are valid parameters.
208 """
209 response = self._query(query, require_city=False)
210 return {
211 "continent_code": response.continent.code,
212 "continent_name": response.continent.name,
213 "country_code": response.country.iso_code,
214 "country_name": response.country.name,
215 "is_in_european_union": response.country.is_in_european_union,
216 }
217
218 def coords(self, query, ordering=("longitude", "latitude")):
219 warnings.warn(
220 "GeoIP2.coords() is deprecated. Use GeoIP2.lon_lat() instead.",
221 RemovedInDjango60Warning,
222 stacklevel=2,
223 )
224 data = self.city(query)
225 return tuple(data[o] for o in ordering)
226
227 def lon_lat(self, query):
228 "Return a tuple of the (longitude, latitude) for the given query."
229 data = self.city(query)
230 return data["longitude"], data["latitude"]
231
232 def lat_lon(self, query):
233 "Return a tuple of the (latitude, longitude) for the given query."
234 data = self.city(query)
235 return data["latitude"], data["longitude"]
236
237 def geos(self, query):
238 "Return a GEOS Point object for the given query."
239 # Allows importing and using GeoIP2() when GEOS is not installed.
240 from django.contrib.gis.geos import Point
241
242 return Point(self.lon_lat(query), srid=4326)
243
244 @classmethod
245 def open(cls, full_path, cache):
246 warnings.warn(
247 "GeoIP2.open() is deprecated. Use GeoIP2() instead.",
248 RemovedInDjango60Warning,
249 stacklevel=2,
250 )
251 return GeoIP2(full_path, cache)