Package: simple-useragent
Fetches real world, up-to-date user agents for use in web scraping to avoid bot detection.
No more fake or outdated user agents, only user agents of real users.
You can either get random or usage-weighted user agents. It caches
the user agents locally to avoid unnecessary API calls, and refreshes them automatically every 24 hours
from the public API ofuseragents.me. If you need full-fledge fake browser
headers including client hints like sec-ch-ua, sec-fetch-site and more, check out mysimple-headerpackage.ContentsFeaturesInstallationUsageQuickstartAdvanced UsageSettings and ParametersDevelopmentContributorsCreditsLicenseFeaturesUp-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:SupportsPython 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.InstallationJust install the package fromPyPiusing pip:pipinstallsimple-useragentUsageQuickstartJust import the package and use the convenience functions. For more advanced usage, you can initialize the class to set custom settings.importsimple_useragentassuasua.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 ...', ...]}Advanced UsageImport the package and initialize the UserAgents class to set custom settings (optional, seeSettings and Parametersfor details).importsimple_useragentassuasimple_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 / FalseSettings and ParametersThe 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 withUserAgents(...).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 withUserAgents._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.DevelopmentAs 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 thecode of conductto understand how we work together
respectfully.Bug Report:If you are experiencing an issue while using the package, pleasecreate an issue.Feature Request:Make this project better bysubmitting a feature request.Documentation:Improve our documentation byadding a wiki page.Community Support:Help others onGitHub Discussions.Security Report:Report critical security issues via ourtemplate.ContributorsThank you so much for giving feedback, implementing features and improving the code and project!CreditsFull credits are in theACKNOWLEDGMENTSfile.LicenseProvided under the terms of theGNU GPL3 License© Lennart Haack 2024.SeeLICENSEfile for details.
For the licenses of used third party libraries and software, please refer to theACKNOWLEDGMENTSfile.