Package: django-geoip2-extras
# Django GeoIP2 ExtrasUseful extras based on the `django.contrib.gis.geoip2` module, usingthe [MaxMind GeoIP2 Lite](http://dev.maxmind.com/geoip/geoip2/geolite2/) database.The first feature in this package is a Django middleware class that canbe used to add city, country level information to inbound requests.### Version supportThe current version of the this app support **Python 3.8+** and **Django 3.2+**## Requirements1) This package wraps the existing Django functionality, and as a resultrelies on the same underlying requirements:In order to perform IP-based geolocation, the GeoIP2 object requiresthe geoip2 Python library and the GeoIP Country and/or City datasetsin binary format (the CSV files will not work!). Grab theGeoLite2-Country.mmdb.gz and GeoLite2-City.mmdb.gz files and unzipthem in a directory corresponding to the GEOIP_PATH setting.NB: The MaxMind database is not included with this package. It is yourresponsiblity to download this and include it as part of your project.2) This package requires the usage of a Django cache configuration tomaintain adaquate performance.## InstallationThis package can be installed from PyPI as `django-geoip2-extras`:```$ pip install django-geoip2-extras```If you want to add the country-level information to incoming requests,add the middleware to your project settings.```python# settings.pyMIDDLEWARE = (...,'geoip2_extras.middleware.GeoIP2Middleware',)```The middleware will not be active unless you add a setting for thedefault `GEOIP_PATH` - this is the default Django GeoIP2 behaviour:```python# settings.pyGEOIP_PATH = os.path.dirname(__file__)```You must also configure a cache to use  via `GEOIP2_EXTRAS_CACHE_NAME`.The value should match the name of the Django cache configuration youwish to use for caching.```python# settings.py# Django cache configuration settingCACHES = {"default": { ... },"some-other-cache": { ... },  # <-- it would use this one....}# Set this to specific configuration name from CACHESGEOIP2_EXTRAS_CACHE_NAME = "some-other-cache"```Tip: see `/demo/settings.py` for a full working example.### SettingsThe following settings can be overridden via your Django settings:* `GEOIP2_EXTRAS_CACHE_NAME`The Django cache configuration to use for cacheing.* `GEOIP2_EXTRAS_CACHE_TIMEOUT`Time to cache IP <> address data in seconds - default to 1hr (3600s)* `GEOIP2_EXTRAS_ADD_RESPONSE_HEADERS`Set to True to write out the GeoIP data to the response headers. Defaults to usethe `DEBUG` value. This value can be overridden on a per-request basis by addingthe `X-GeoIP2-Debug` request header, or adding `geoip2=1` to the requestquerystring. This is useful for debugging in a production environment where youmay not be adding the response headers by default.## UsageOnce the middleware is added, you will be able to access City and / orCountry level information on the request object via the `geo_data` dict:```python>>> request.geo_data{"city": """continent-code": "NA""continent-name": "North America""country-code": "US""country-name": "United States""dma-code": """is-in-european-union": False"latitude": 37.751"longitude": -97.822"postal-code": """region": """time-zone": "America/Chicago""remote-addr": "142.250.180.3"}```The same information will be added to the HttpResponse headers if`GEOIP2_EXTRAS_ADD_RESPONSE_HEADERS` is True. Values are set using the`X-GeoIP2-` prefix.NB blank (`""`) values are **not** added to the response:```shell# use the google.co.uk IP$ curl -I -H "x-forwarded-for: 142.250.180.3" localhost:8000HTTP/1.1 200 OKDate: Sun, 29 Aug 2021 15:47:22 GMTServer: WSGIServer/0.2 CPython/3.9.4Content-Type: text/htmlX-GeoIP2-Continent-Code: NAX-GeoIP2-Continent-Name: North AmericaX-GeoIP2-Country-Code: USX-GeoIP2-Country-Name: United StatesX-GeoIP2-Is-In-European-Union: FalseX-GeoIP2-Latitude: 37.751X-GeoIP2-Longitude: -97.822X-GeoIP2-Time-Zone: America/ChicagoX-GeoIP2-Remote-Addr: 142.250.180.3Content-Length: 10697```If the IP address cannot be found (e.g. '127.0.0.1'), then a default'unknown' country is used, with a code of 'XX'.```shell$ curl -I -H "x-forwarded-for: 127.0.0.1" localhost:8000HTTP/1.1 200 OKDate: Sun, 29 Aug 2021 15:47:22 GMTServer: WSGIServer/0.2 CPython/3.9.4Content-Type: text/htmlX-GeoIP2-Country-Code: XXX-GeoIP2-Country-Name: unknownX-GeoIP2-Remote-Addr: 127.0.0.1Content-Length: 10697```## TestsThe project tests are run through `pytest`.