Metadata-Version: 1.1
Name: django-geoip2-extras
Version: 0.1.2
Summary: Additional functionality using the GeoIP2 database.
Home-page: https://github.com/yunojuno/django-geoip2-extras
Author: YunoJuno
Author-email: code@yunojuno.com
License: MIT
Description: .. image:: https://badge.fury.io/py/django-geoip2-extras.svg
            :target: https://badge.fury.io/py/django-geoip2-extras
        
        .. image:: https://travis-ci.org/yunojuno/django-geoip2-extras.svg
            :target: https://travis-ci.org/yunojuno/django-geoip2-extras
        
        Django GeoIP2 Extras
        --------------------
        
        Useful extras based on the ``django.contrib.gis.geoip2`` module, using
        the `MaxMind GeoIP2 Lite <http://dev.maxmind.com/geoip/geoip2/geolite2/>`_ database.
        
        The first feature in this package is a Django middleware class that can
        be used to add country level information to inbound requests.
        
        Requirements
        ============
        
        This package wraps the existing Django functionality, and as a result
        relies on the same underlying requirements:
        
            *In order to perform IP-based geolocation, the GeoIP2 object requires the geoip2 Python library and the GeoIP Country and/or City datasets in binary format (the CSV files will not work!). Grab the GeoLite2-Country.mmdb.gz and GeoLite2-City.mmdb.gz files and unzip them in a directory corresponding to the GEOIP_PATH setting.*
        
        In addition, the middleware follows the 'new' middleware pattern, and therefore
        does **not** support Django 1.9 or below. This is a 1.10 and above package.
        
        Installation
        ============
        
        This package can be installed from PyPI as ``django-geoip2-extras``:
        
        .. code:: shell
        
            $ pip install django-geoip2-extras
        
        If you want to add the country-level information to incoming requests, add the
        middleware to your project settings. NB The ``GeoIP2Middleware`` relies on the ``SessionMiddleware``, and must come after it:
        
        .. code:: python
        
            MIDDLEWARE = (
                ...,
                'django.contrib.sessions.middleware.SessionMiddleware',
                'geoip2_extras.middleware.GeoIP2Middleware',
                ...
            )
        
        The middleware will not be active unless you add a setting for
        the default ``GEOIP_PATH`` - this is the default Django GeoIP2 behaviour:
        
        .. code:: python
        
            # settings.py
            GEOIP_PATH = os.path.dirname(__file__)
        
        NB Loading this package does *not* install the `MaxMind database <http://dev.maxmind.com/geoip/geoip2/geolite2/>`_
        . That is
        your responsibility. The Country database is 2.7MB, and could be added
        to most project comfortably, but it is updated regularly, and keeping that
        up-to-date is out of scope for this project.
        
        Usage
        =====
        
        Once the middleware is added, you will be able to access Country level
        information on the request object:
        
        .. code:: python
        
            >>> request.country
            {
                'ip_address': '1.2.3.4',
                'country_code': 'GB',
                'country_name': 'United Kingdom'
            }
        
        If the IP address cannot be found (e.g. localhost), then a default 'unknown'
        country dict is used.
        
        .. code:: python
        
            >>> request.country
            {
                'ip_address': '127.0.0.1',
                'country_code': 'XX',
                'country_name': 'unknown'
            }
        
        This prevents the middleware from re-requesting the address on each request -
        it effectively marks the IP as a bad address.
        
        Tests
        =====
        
        The project tests are run through ``tox``.
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.10
Classifier: Framework :: Django :: 1.11
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
