django-user-agents


Namedjango-user-agents JSON
Version 0.4.0 PyPI version JSON
download
home_pagehttps://github.com/selwin/django-user_agents
SummaryA django package that allows easy identification of visitors' browser, operating system and device information (mobile phone, tablet or has touch capabilities).
upload_time2019-06-22 13:33:50
maintainer
docs_urlNone
authorSelwin Ong
requires_python
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI
coveralls test coverage No coveralls. 
            Django User Agents
==================

A django package that allows easy identification of visitor's browser, OS and device information,
including whether the visitor uses a mobile phone, tablet or a touch capable device. Under the hood,
it uses `user-agents <https://github.com/selwin/python-user-agents>`_.


Installation
============

1. Install ``django-user-agents``, you'll have to make sure that `user-agents`_ is installed first::

    pip install pyyaml ua-parser user-agents
    pip install django-user-agents

2. Configure ``settings.py``:

   .. code-block:: python

    INSTALLED_APPS = (
        # Other apps...
        'django_user_agents',
    )

    # Cache backend is optional, but recommended to speed up user agent parsing
    CACHES = {
        'default': {
            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
            'LOCATION': '127.0.0.1:11211',
        }
    }

    # Name of cache backend to cache user agents. If it not specified default
    # cache alias will be used. Set to `None` to disable caching.
    USER_AGENTS_CACHE = 'default'

Usage
=====

Middleware
----------

Add ``UserAgentMiddleware`` in ``settings.py``:

.. code-block:: python

    MIDDLEWARE_CLASSES = (
        # other middlewares...
        'django_user_agents.middleware.UserAgentMiddleware',
    )

A ``user_agent`` attribute will now be added to ``request``, which you can use
in ``views.py``:

.. code-block:: python

    def my_view(request):

        # Let's assume that the visitor uses an iPhone...
        request.user_agent.is_mobile # returns True
        request.user_agent.is_tablet # returns False
        request.user_agent.is_touch_capable # returns True
        request.user_agent.is_pc # returns False
        request.user_agent.is_bot # returns False

        # Accessing user agent's browser attributes
        request.user_agent.browser  # returns Browser(family=u'Mobile Safari', version=(5, 1), version_string='5.1')
        request.user_agent.browser.family  # returns 'Mobile Safari'
        request.user_agent.browser.version  # returns (5, 1)
        request.user_agent.browser.version_string   # returns '5.1'

        # Operating System properties
        request.user_agent.os  # returns OperatingSystem(family=u'iOS', version=(5, 1), version_string='5.1')
        request.user_agent.os.family  # returns 'iOS'
        request.user_agent.os.version  # returns (5, 1)
        request.user_agent.os.version_string  # returns '5.1'

        # Device properties
        request.user_agent.device  # returns Device(family='iPhone')
        request.user_agent.device.family  # returns 'iPhone'

If you have ``django.core.context_processors.request`` enabled, ``user_agent``
will also be available in template through ``request``:

.. code-block:: html+django

    {% if request.user_agent.is_mobile %}
        Do stuff here...
    {% endif %}


View Usage
----------

``django-user_agents`` comes with ``get_user_agent`` which takes a single
``request`` argument and returns a ``UserAgent`` instance. Example usage:

.. code-block:: python

    from django_user_agents.utils import get_user_agent

    def my_view(request):
        user_agent = get_user_agent(request)
        if user_agent.is_mobile:
            # Do stuff here...
        elif user_agent.is_tablet:
            # Do other stuff...


Template Usage
--------------

``django-user_agents`` comes with a few template filters:

* ``is_mobile``
* ``is_tablet``
* ``is_touch_capable``
* ``is_pc``
* ``is_bot``

You can use all of these like any other django template filters:

.. code-block:: html+django

    {% load user_agents %}

    {% if request|is_mobile %}
        Mobile device stuff...
    {% endif %}

    {% if request|is_tablet %}
        Tablet stuff...
    {% endif %}

    {% if request|is_pc %}
        PC stuff...
    {% endif %}

    {% if request|is_touch_capable %}
        Touch capable device stuff...
    {% endif %}

    {% if request|is_bot %}
        Bot stuff...
    {% endif %}


You can find out more about user agent attributes at `here <https://github.com/selwin/python-user-agents>`_.


Running Tests
=============

.. code-block:: console

    `which django-admin.py` test django_user_agents --settings=django_user_agents.tests.settings --pythonpath=.


Changelog
=========

0.4.0
-----
* Add support for Django 2.0 to 2.2. Thanks @adamchainz and @joehybird!

0.3.1
-----
* Fixed a bug when request have no META attribute

0.3.0
-----
* Python 3, thanks to @hwkns!

0.2.2
-----
* Fixed a bug that causes cache set/read to fail when user agent is longer than 250 characters

0.2.1
-----
* Fixed packaging

0.2.0
-----
* Added template filters
* Added ``get_user_agent`` function in utils.py

0.1.1
-----
* Fixed a ``KeyError`` exception in the case of empty ``HTTP_USER_AGENT``

0.1
---
* Initial release

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/selwin/django-user_agents",
    "name": "django-user-agents",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Selwin Ong",
    "author_email": "selwin.ong@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/37/f2/dd96cc880d7549cc9f67c8b1ad8e6695f9731658fdf8aa476f0bcb9c89c7/django-user_agents-0.4.0.tar.gz",
    "platform": "",
    "description": "Django User Agents\n==================\n\nA django package that allows easy identification of visitor's browser, OS and device information,\nincluding whether the visitor uses a mobile phone, tablet or a touch capable device. Under the hood,\nit uses `user-agents <https://github.com/selwin/python-user-agents>`_.\n\n\nInstallation\n============\n\n1. Install ``django-user-agents``, you'll have to make sure that `user-agents`_ is installed first::\n\n    pip install pyyaml ua-parser user-agents\n    pip install django-user-agents\n\n2. Configure ``settings.py``:\n\n   .. code-block:: python\n\n    INSTALLED_APPS = (\n        # Other apps...\n        'django_user_agents',\n    )\n\n    # Cache backend is optional, but recommended to speed up user agent parsing\n    CACHES = {\n        'default': {\n            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',\n            'LOCATION': '127.0.0.1:11211',\n        }\n    }\n\n    # Name of cache backend to cache user agents. If it not specified default\n    # cache alias will be used. Set to `None` to disable caching.\n    USER_AGENTS_CACHE = 'default'\n\nUsage\n=====\n\nMiddleware\n----------\n\nAdd ``UserAgentMiddleware`` in ``settings.py``:\n\n.. code-block:: python\n\n    MIDDLEWARE_CLASSES = (\n        # other middlewares...\n        'django_user_agents.middleware.UserAgentMiddleware',\n    )\n\nA ``user_agent`` attribute will now be added to ``request``, which you can use\nin ``views.py``:\n\n.. code-block:: python\n\n    def my_view(request):\n\n        # Let's assume that the visitor uses an iPhone...\n        request.user_agent.is_mobile # returns True\n        request.user_agent.is_tablet # returns False\n        request.user_agent.is_touch_capable # returns True\n        request.user_agent.is_pc # returns False\n        request.user_agent.is_bot # returns False\n\n        # Accessing user agent's browser attributes\n        request.user_agent.browser  # returns Browser(family=u'Mobile Safari', version=(5, 1), version_string='5.1')\n        request.user_agent.browser.family  # returns 'Mobile Safari'\n        request.user_agent.browser.version  # returns (5, 1)\n        request.user_agent.browser.version_string   # returns '5.1'\n\n        # Operating System properties\n        request.user_agent.os  # returns OperatingSystem(family=u'iOS', version=(5, 1), version_string='5.1')\n        request.user_agent.os.family  # returns 'iOS'\n        request.user_agent.os.version  # returns (5, 1)\n        request.user_agent.os.version_string  # returns '5.1'\n\n        # Device properties\n        request.user_agent.device  # returns Device(family='iPhone')\n        request.user_agent.device.family  # returns 'iPhone'\n\nIf you have ``django.core.context_processors.request`` enabled, ``user_agent``\nwill also be available in template through ``request``:\n\n.. code-block:: html+django\n\n    {% if request.user_agent.is_mobile %}\n        Do stuff here...\n    {% endif %}\n\n\nView Usage\n----------\n\n``django-user_agents`` comes with ``get_user_agent`` which takes a single\n``request`` argument and returns a ``UserAgent`` instance. Example usage:\n\n.. code-block:: python\n\n    from django_user_agents.utils import get_user_agent\n\n    def my_view(request):\n        user_agent = get_user_agent(request)\n        if user_agent.is_mobile:\n            # Do stuff here...\n        elif user_agent.is_tablet:\n            # Do other stuff...\n\n\nTemplate Usage\n--------------\n\n``django-user_agents`` comes with a few template filters:\n\n* ``is_mobile``\n* ``is_tablet``\n* ``is_touch_capable``\n* ``is_pc``\n* ``is_bot``\n\nYou can use all of these like any other django template filters:\n\n.. code-block:: html+django\n\n    {% load user_agents %}\n\n    {% if request|is_mobile %}\n        Mobile device stuff...\n    {% endif %}\n\n    {% if request|is_tablet %}\n        Tablet stuff...\n    {% endif %}\n\n    {% if request|is_pc %}\n        PC stuff...\n    {% endif %}\n\n    {% if request|is_touch_capable %}\n        Touch capable device stuff...\n    {% endif %}\n\n    {% if request|is_bot %}\n        Bot stuff...\n    {% endif %}\n\n\nYou can find out more about user agent attributes at `here <https://github.com/selwin/python-user-agents>`_.\n\n\nRunning Tests\n=============\n\n.. code-block:: console\n\n    `which django-admin.py` test django_user_agents --settings=django_user_agents.tests.settings --pythonpath=.\n\n\nChangelog\n=========\n\n0.4.0\n-----\n* Add support for Django 2.0 to 2.2. Thanks @adamchainz and @joehybird!\n\n0.3.1\n-----\n* Fixed a bug when request have no META attribute\n\n0.3.0\n-----\n* Python 3, thanks to @hwkns!\n\n0.2.2\n-----\n* Fixed a bug that causes cache set/read to fail when user agent is longer than 250 characters\n\n0.2.1\n-----\n* Fixed packaging\n\n0.2.0\n-----\n* Added template filters\n* Added ``get_user_agent`` function in utils.py\n\n0.1.1\n-----\n* Fixed a ``KeyError`` exception in the case of empty ``HTTP_USER_AGENT``\n\n0.1\n---\n* Initial release\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A django package that allows easy identification of visitors' browser, operating system and device information (mobile phone, tablet or has touch capabilities).",
    "version": "0.4.0",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "545c77925ad1542437392957ac50d7ce",
                "sha256": "cd9d9f7158b23c5237b2dacb0bc4fffdf77fefe1d2633b5814d3874288ebdb5d"
            },
            "downloads": -1,
            "filename": "django_user_agents-0.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "545c77925ad1542437392957ac50d7ce",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 8616,
            "upload_time": "2019-06-22T13:33:48",
            "upload_time_iso_8601": "2019-06-22T13:33:48.259911Z",
            "url": "https://files.pythonhosted.org/packages/6c/a3/31b2728702f13328cc65d6c8ed652ad8125a9a71489e445c11f188b39f79/django_user_agents-0.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "36fa2bb89131533ec4bd82c948fd30a6",
                "sha256": "cda8ae2146cee30e6867a07943f56ecc570b4391d725ab5309901a8b3e4a3514"
            },
            "downloads": -1,
            "filename": "django-user_agents-0.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "36fa2bb89131533ec4bd82c948fd30a6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 8501,
            "upload_time": "2019-06-22T13:33:50",
            "upload_time_iso_8601": "2019-06-22T13:33:50.372832Z",
            "url": "https://files.pythonhosted.org/packages/37/f2/dd96cc880d7549cc9f67c8b1ad8e6695f9731658fdf8aa476f0bcb9c89c7/django-user_agents-0.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2019-06-22 13:33:50",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "selwin",
    "github_project": "django-user_agents",
    "travis_ci": true,
    "coveralls": false,
    "github_actions": false,
    "tox": true,
    "lcname": "django-user-agents"
}
Selwin Ong
Elapsed time: 0.01465s