Â
-
Up-to-date: No fake or outdated user agents.
Only real world data
, refreshed every 24 hours. - Wide Support: User Agents for Windows, macOS, Linux, Android and iOS devices: Google Chrome, Firefox, Safari, Edge, Opera, Whale and QQ browsers.
- Lightweight: Caches user agents locally to consume minimal system resources.
- Simple: Easy to use and understand with a clean and simple API.
-
Compatible: Supports
Python 3.8 and above
. Runs on Windows, macOS and Linux. - Tested: Has 99% test coverage and is continuously tested.
- Privacy: Protects the user by not collecting or sending any personal data.
- Open Source: Provides transparency and allows community contributions for continuous development.
Â
Just install the package from PyPi using pip:
pip install simple-useragent
Â
Just import the package and use the convenience functions. For more advanced usage, you can initialize the class to set custom settings.
import simple_useragent as sua
sua.get(num=2, mobile=True) # List of the 2 most common mobile user agents (attributes explained below).
# [UserAgent('Mozilla/5.0 (Android ...'), UserAgent('Mozilla/5.0 (iPhone; ...')]
sua.get_list(shuffle=True, force_cached=True) # Random list of available desktop user agents strings.
# ['Mozilla/5.0 ...', 'Mozilla/5.0 (iPhone ...', 'Mozilla/5.0 (iPhone ...', ...]
sua.get_dict() # Dictionary with all desktop and mobile user agents.
# {'desktop': ['Mozilla/5.0 ...', ...] 'mobile': ['Mozilla/5.0 (iPhone ...', ...]}
Â
Import the package and initialize the UserAgents class to set custom settings (optional, see Settings and Parameters for details).
import simple_useragent as sua
simple_ua = sua.UserAgents(max_retries=3, timeout=5, cache_duration=86400, cache_location='example/path/to/folder')
Â
Fetching User Agents.
# Fetch a specified number of random mobile user agent instances (with settings from the class above).
simple_ua.get(num=2, shuffle=True, mobile=True)
# [UserAgent('Mozilla/5.0 (iPhone ...'), UserAgent('Mozilla/5.0 (iPhone; ...')]
Â
You can also use the convenience functions to get user agents without initializing the class.
sua.get(num=2, mobile=True) # List of the 2 most common mobile user agent (attributes explained below).
# [UserAgent('Mozilla/5.0 (Android ...'), UserAgent('Mozilla/5.0 (iPhone; ...')]
sua.get_list(force_cached=True) # List of all available desktop user agents as strings.
# ['Mozilla/5.0 ...', 'Mozilla/5.0 (iPhone ...', 'Mozilla/5.0 (iPhone ...', ...]
sua.get_dict() # Dictionary with all desktop and mobile user agents.
# {'desktop': ['Mozilla/5.0 ...', ...] 'mobile': ['Mozilla/5.0 (iPhone ...', ...]}
Â
The instance offers attributes for the user agent properties.
# Parse a custom string directly to the UserAgent class and access its attributes.
obj = sua.parse('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36')
obj.string # 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit ...'
obj.browser # 'Chrome', 'Firefox', 'Safari', 'Edge', 'IE', 'Opera', 'Whale', 'QQ Browser', 'Samsung Browser', 'Other'
obj.browser_version # '110', '109', '537', ...
obj.browser_version_minor # '0', '1', '36', ...
# You can also access the attributes with square brackets.
obj = sua.get(num=1, shuffle=True)[0]
obj['os'] # 'Windows', 'macOS', 'Linux', 'Android', 'iOS', 'Other'
obj['os_version'] # '10', '7', '11', '14', ...
obj['os_version_minor'] # '0', '1', '2', ...
obj['mobile'] # True / False
Â
The functions can take the following parameters:
- num: The number of user agents to fetch (default: None = gets you all user agents available).
- mobile: Fetch mobile or desktop user agents (default: False = desktop).
- shuffle: Whether to shuffle/randomize the order of user agents (default: False = ordered by usage).
- force_cached: Force the use of memory or file cached user agents (default: None = fetches new user agents if cache is outdated, False = always call the API, True = always use the cache).
Â
You can set custom preferences when initializing the class with UserAgents(...)
.
- max_retries: The maximum number of retries to reach the API, before falling back to local cache (default: 3).
- timeout: The timeout in seconds for the API request (default: 5).
- cache_duration: The duration in seconds for the user agents to be cached (default: 86400 = 1 day).
-
cache_location: The folder in which the user agents are cached, specific to the OS. You can see the default location with
UserAgents._cache_location
.
Â
Notes:
- The user agents are cached locally to avoid unnecessary API calls, and are refreshed automatically every 24 hours.
- During runtime the user agents are stored in memory and written to a cache file for persistence and performance.
- Every time you invoke a simple-useragent function, it is automatically checked for outdated user agents.
Â
As an open-source project, I strive for transparency and collaboration in my development process. I greatly appreciate any contributions members of our community can provide. Whether you are fixing bugs, proposing features, improving documentation, or spreading awareness - your involvement strengthens the project. Please review the code of conduct to understand how we work together respectfully.
- Bug Report: If you are experiencing an issue while using the package, please create an issue.
- Feature Request: Make this project better by submitting a feature request.
- Documentation: Improve our documentation by adding a wiki page.
- Community Support: Help others on GitHub Discussions.
- Security Report: Report critical security issues via our template.
Â
Thank you so much for giving feedback, implementing features and improving the code and project!
Â
Full credits are in the ACKNOWLEDGMENTS file.
Â
Provided under the terms of the GNU GPL3 License © Lennart Haack 2024.
See LICENSE file for details. For the licenses of used third party libraries and software, please refer to the ACKNOWLEDGMENTS file.