Python User Agents
==================
`user_agents` is a Python library that provides an easy way to identify/detect devices like mobile phones, tablets and their capabilities by parsing (browser/HTTP) user agent strings. The goal is to reliably detect whether:
* User agent is a mobile, tablet or PC based device
* User agent has touch capabilities (has touch screen)
`user_agents` relies on the excellent [ua-parser](https://github.com/ua-parser/uap-python) to do the actual parsing of the raw user agent string.
Installation
------------
`user-agents` is hosted on [PyPI](http://pypi.python.org/pypi/user-agents/) and can be installed as such:
pip install pyyaml ua-parser user-agents
Alternatively, you can also get the latest source code from [Github](https://github.com/selwin/python-user-agents) and install it manually.
Usage
-----
Various basic information that can help you identify visitors can be accessed `browser`, `device` and `os` attributes. For example:
```python
from user_agents import parse
# iPhone's user agent string
ua_string = 'Mozilla/5.0 (iPhone; CPU iPhone OS 5_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B179 Safari/7534.48.3'
user_agent = parse(ua_string)
# Accessing user agent's browser attributes
user_agent.browser # returns Browser(family=u'Mobile Safari', version=(5, 1), version_string='5.1')
user_agent.browser.family # returns 'Mobile Safari'
user_agent.browser.version # returns (5, 1)
user_agent.browser.version_string # returns '5.1'
# Accessing user agent's operating system properties
user_agent.os # returns OperatingSystem(family=u'iOS', version=(5, 1), version_string='5.1')
user_agent.os.family # returns 'iOS'
user_agent.os.version # returns (5, 1)
user_agent.os.version_string # returns '5.1'
# Accessing user agent's device properties
user_agent.device # returns Device(family=u'iPhone', brand=u'Apple', model=u'iPhone')
user_agent.device.family # returns 'iPhone'
user_agent.device.brand # returns 'Apple'
user_agent.device.model # returns 'iPhone'
# Viewing a pretty string version
str(user_agent) # returns "iPhone / iOS 5.1 / Mobile Safari 5.1"
```
`user_agents` also expose a few other more "sophisticated" attributes that are derived from one or more basic attributes defined above. As for now, these attributes should correctly identify popular platforms/devices, pull requests to support smaller ones are always welcome.
Currently these attributes are supported:
* `is_mobile`: whether user agent is identified as a mobile phone (iPhone, Android phones, Blackberry, Windows Phone devices etc)
* `is_tablet`: whether user agent is identified as a tablet device (iPad, Kindle Fire, Nexus 7 etc)
* `is_pc`: whether user agent is identified to be running a traditional "desktop" OS (Windows, OS X, Linux)
* `is_touch_capable`: whether user agent has touch capabilities
* `is_bot`: whether user agent is a search engine crawler/spider
For example:
```python
from user_agents import parse
# Let's start from an old, non touch Blackberry device
ua_string = 'BlackBerry9700/5.0.0.862 Profile/MIDP-2.1 Configuration/CLDC-1.1 VendorID/331 UNTRUSTED/1.0 3gpp-gba'
user_agent = parse(ua_string)
user_agent.is_mobile # returns True
user_agent.is_tablet # returns False
user_agent.is_touch_capable # returns False
user_agent.is_pc # returns False
user_agent.is_bot # returns False
str(user_agent) # returns "BlackBerry 9700 / BlackBerry OS 5 / BlackBerry 9700"
# Now a Samsung Galaxy S3
ua_string = 'Mozilla/5.0 (Linux; U; Android 4.0.4; en-gb; GT-I9300 Build/IMM76D) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30'
user_agent = parse(ua_string)
user_agent.is_mobile # returns True
user_agent.is_tablet # returns False
user_agent.is_touch_capable # returns True
user_agent.is_pc # returns False
user_agent.is_bot # returns False
str(user_agent) # returns "Samsung GT-I9300 / Android 4.0.4 / Android 4.0.4"
# iPad's user agent string
ua_string = 'Mozilla/5.0(iPad; U; CPU iPhone OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Version/4.0.4 Mobile/7B314 Safari/531.21.10'
user_agent = parse(ua_string)
user_agent.is_mobile # returns False
user_agent.is_tablet # returns True
user_agent.is_touch_capable # returns True
user_agent.is_pc # returns False
user_agent.is_bot # returns False
str(user_agent) # returns "iPad / iOS 3.2 / Mobile Safari 4.0.4"
# Kindle Fire's user agent string
ua_string = 'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_3; en-us; Silk/1.1.0-80) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16 Silk-Accelerated=true'
user_agent = parse(ua_string)
user_agent.is_mobile # returns False
user_agent.is_tablet # returns True
user_agent.is_touch_capable # returns True
user_agent.is_pc # returns False
user_agent.is_bot # returns False
str(user_agent) # returns "Kindle / Android / Amazon Silk 1.1.0-80"
# Touch capable Windows 8 device
ua_string = 'Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Trident/6.0; Touch)'
user_agent = parse(ua_string)
user_agent.is_mobile # returns False
user_agent.is_tablet # returns False
user_agent.is_touch_capable # returns True
user_agent.is_pc # returns True
user_agent.is_bot # returns False
str(user_agent) # returns "PC / Windows 8 / IE 10"
```
Running Tests
-------------
python -m unittest discover
Changelog
---------
### Version 2.2.0 (2020-08-23)
* `ua-parser` >= 0.10.0 is required. Thanks @jnozsc!
* Added `get_device()`, `get_os()` and `get_browser()` instance methods
to `UserAgent`. Thanks @rodrigondec!
### Version 2.1 (2020-02-08)
* `python-user-agents` now require `ua-parser>=0.9.0`. Thanks @jnozsc!
* Properly detect Chrome Mobile browser families. Thanks @jnozsc!
### Version 2.0 (2019-04-07)
* `python-user-agents` now require `ua-parser>=0.8.0`. Thanks @IMDagger!
### Version 1.1
* Fixes packaging issue
### Version 1.0
* Adds compatibility with `ua-parser` 0.4.0
* Access to more device information in `user_agent.device.brand` and `user_agent.device.model`
### Version 0.3.2
* Better mobile detection
* Better PC detection
### Version 0.3.1
* user\_agent.is\_mobile returns True when mobile spider is detected
### Version 0.3.0
* Added **str**/**unicode** methods for convenience of pretty string
### Version 0.2.0
* Fixed errors when running against newer versions if ua-parser
* Support for Python 3
### Version 0.1.1
* Added `is_bot` property
* Symbian OS devices are now detected as a mobile device
### Version 0.1
* Initial release
Developed by the cool guys at [Stamps](http://stamps.co.id).
Raw data
{
"_id": null,
"home_page": "https://github.com/selwin/python-user-agents",
"name": "user-agents-parsers",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Selwin Ong",
"author_email": "selwin.ong@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2e/54/a211cbf5f735d98ca00a312483b182854327d349c75b228a1f176ccbc1bd/user-agents-parsers-2.2.1.tar.gz",
"platform": null,
"description": "Python User Agents\n==================\n\n`user_agents` is a Python library that provides an easy way to identify/detect devices like mobile phones, tablets and their capabilities by parsing (browser/HTTP) user agent strings. The goal is to reliably detect whether:\n\n* User agent is a mobile, tablet or PC based device\n* User agent has touch capabilities (has touch screen)\n\n`user_agents` relies on the excellent [ua-parser](https://github.com/ua-parser/uap-python) to do the actual parsing of the raw user agent string.\n\nInstallation\n------------\n\n\n\n`user-agents` is hosted on [PyPI](http://pypi.python.org/pypi/user-agents/) and can be installed as such:\n\n pip install pyyaml ua-parser user-agents\n\nAlternatively, you can also get the latest source code from [Github](https://github.com/selwin/python-user-agents) and install it manually.\n\nUsage\n-----\n\nVarious basic information that can help you identify visitors can be accessed `browser`, `device` and `os` attributes. For example:\n\n```python\nfrom user_agents import parse\n\n# iPhone's user agent string\nua_string = 'Mozilla/5.0 (iPhone; CPU iPhone OS 5_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B179 Safari/7534.48.3'\nuser_agent = parse(ua_string)\n\n# Accessing user agent's browser attributes\nuser_agent.browser # returns Browser(family=u'Mobile Safari', version=(5, 1), version_string='5.1')\nuser_agent.browser.family # returns 'Mobile Safari'\nuser_agent.browser.version # returns (5, 1)\nuser_agent.browser.version_string # returns '5.1'\n\n# Accessing user agent's operating system properties\nuser_agent.os # returns OperatingSystem(family=u'iOS', version=(5, 1), version_string='5.1')\nuser_agent.os.family # returns 'iOS'\nuser_agent.os.version # returns (5, 1)\nuser_agent.os.version_string # returns '5.1'\n\n# Accessing user agent's device properties\nuser_agent.device # returns Device(family=u'iPhone', brand=u'Apple', model=u'iPhone')\nuser_agent.device.family # returns 'iPhone'\nuser_agent.device.brand # returns 'Apple'\nuser_agent.device.model # returns 'iPhone'\n\n# Viewing a pretty string version\nstr(user_agent) # returns \"iPhone / iOS 5.1 / Mobile Safari 5.1\"\n```\n\n`user_agents` also expose a few other more \"sophisticated\" attributes that are derived from one or more basic attributes defined above. As for now, these attributes should correctly identify popular platforms/devices, pull requests to support smaller ones are always welcome.\n\nCurrently these attributes are supported:\n\n* `is_mobile`: whether user agent is identified as a mobile phone (iPhone, Android phones, Blackberry, Windows Phone devices etc)\n* `is_tablet`: whether user agent is identified as a tablet device (iPad, Kindle Fire, Nexus 7 etc)\n* `is_pc`: whether user agent is identified to be running a traditional \"desktop\" OS (Windows, OS X, Linux)\n* `is_touch_capable`: whether user agent has touch capabilities\n* `is_bot`: whether user agent is a search engine crawler/spider\n\nFor example:\n\n```python\nfrom user_agents import parse\n\n# Let's start from an old, non touch Blackberry device\nua_string = 'BlackBerry9700/5.0.0.862 Profile/MIDP-2.1 Configuration/CLDC-1.1 VendorID/331 UNTRUSTED/1.0 3gpp-gba'\nuser_agent = parse(ua_string)\nuser_agent.is_mobile # returns True\nuser_agent.is_tablet # returns False\nuser_agent.is_touch_capable # returns False\nuser_agent.is_pc # returns False\nuser_agent.is_bot # returns False\nstr(user_agent) # returns \"BlackBerry 9700 / BlackBerry OS 5 / BlackBerry 9700\"\n\n# Now a Samsung Galaxy S3\nua_string = 'Mozilla/5.0 (Linux; U; Android 4.0.4; en-gb; GT-I9300 Build/IMM76D) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30'\nuser_agent = parse(ua_string)\nuser_agent.is_mobile # returns True\nuser_agent.is_tablet # returns False\nuser_agent.is_touch_capable # returns True\nuser_agent.is_pc # returns False\nuser_agent.is_bot # returns False\nstr(user_agent) # returns \"Samsung GT-I9300 / Android 4.0.4 / Android 4.0.4\"\n\n# iPad's user agent string\nua_string = 'Mozilla/5.0(iPad; U; CPU iPhone OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Version/4.0.4 Mobile/7B314 Safari/531.21.10'\nuser_agent = parse(ua_string)\nuser_agent.is_mobile # returns False\nuser_agent.is_tablet # returns True\nuser_agent.is_touch_capable # returns True\nuser_agent.is_pc # returns False\nuser_agent.is_bot # returns False\nstr(user_agent) # returns \"iPad / iOS 3.2 / Mobile Safari 4.0.4\"\n\n# Kindle Fire's user agent string\nua_string = 'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_3; en-us; Silk/1.1.0-80) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16 Silk-Accelerated=true'\nuser_agent = parse(ua_string)\nuser_agent.is_mobile # returns False\nuser_agent.is_tablet # returns True\nuser_agent.is_touch_capable # returns True\nuser_agent.is_pc # returns False\nuser_agent.is_bot # returns False\nstr(user_agent) # returns \"Kindle / Android / Amazon Silk 1.1.0-80\"\n\n# Touch capable Windows 8 device\nua_string = 'Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Trident/6.0; Touch)'\nuser_agent = parse(ua_string)\nuser_agent.is_mobile # returns False\nuser_agent.is_tablet # returns False\nuser_agent.is_touch_capable # returns True\nuser_agent.is_pc # returns True\nuser_agent.is_bot # returns False\nstr(user_agent) # returns \"PC / Windows 8 / IE 10\"\n```\n\nRunning Tests\n-------------\n\n python -m unittest discover\n\nChangelog\n---------\n### Version 2.2.0 (2020-08-23)\n* `ua-parser` >= 0.10.0 is required. Thanks @jnozsc!\n* Added `get_device()`, `get_os()` and `get_browser()` instance methods\nto `UserAgent`. Thanks @rodrigondec!\n\n### Version 2.1 (2020-02-08)\n\n* `python-user-agents` now require `ua-parser>=0.9.0`. Thanks @jnozsc!\n* Properly detect Chrome Mobile browser families. Thanks @jnozsc!\n\n### Version 2.0 (2019-04-07)\n\n* `python-user-agents` now require `ua-parser>=0.8.0`. Thanks @IMDagger!\n\n### Version 1.1\n\n* Fixes packaging issue\n\n### Version 1.0\n\n* Adds compatibility with `ua-parser` 0.4.0\n* Access to more device information in `user_agent.device.brand` and `user_agent.device.model`\n\n### Version 0.3.2\n\n* Better mobile detection\n* Better PC detection\n\n### Version 0.3.1\n\n* user\\_agent.is\\_mobile returns True when mobile spider is detected\n\n### Version 0.3.0\n\n* Added **str**/**unicode** methods for convenience of pretty string\n\n### Version 0.2.0\n\n* Fixed errors when running against newer versions if ua-parser\n* Support for Python 3\n\n### Version 0.1.1\n\n* Added `is_bot` property\n* Symbian OS devices are now detected as a mobile device\n\n### Version 0.1\n\n* Initial release\n\nDeveloped by the cool guys at [Stamps](http://stamps.co.id).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library to identify devices (phones, tablets) and their capabilities by parsing browser user agent strings.",
"version": "2.2.1",
"project_urls": {
"Homepage": "https://github.com/selwin/python-user-agents"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e54a211cbf5f735d98ca00a312483b182854327d349c75b228a1f176ccbc1bd",
"md5": "317fbdea954f5aecca546504f76a1b4b",
"sha256": "5e545868cef894249b734752ccad44c6cb5a28e0f286718f6ffc507f2e515df4"
},
"downloads": -1,
"filename": "user-agents-parsers-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "317fbdea954f5aecca546504f76a1b4b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11878,
"upload_time": "2024-04-04T17:15:20",
"upload_time_iso_8601": "2024-04-04T17:15:20.280675Z",
"url": "https://files.pythonhosted.org/packages/2e/54/a211cbf5f735d98ca00a312483b182854327d349c75b228a1f176ccbc1bd/user-agents-parsers-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 17:15:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "selwin",
"github_project": "python-user-agents",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "user-agents-parsers"
}
JSON
