| 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) |