Metadata-Version: 2.1
Name: rand-useragent
Version: 0.2.0
Summary: An up-to-date simple random user-agent with real world database.
Author-email: Tolulope Kuyoro <tolukuyoro@gmail.com>
License: BSD-3-Clause
Project-URL: homepage, https://github.com/redbugg/rand-useragent
Project-URL: source, https://github.com/redbugg/rand-useragent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE

rand-useragent
==============

An up-to-date simple random user-agent with real world database. 
The collections of user-agent data is pre-downloaded from 
[techblog.willshouse.com](https://techblog.willshouse.com/2012/01/03/most-common-user-agents/).


Installation
------------

```shell
$ pip install rand-useragent
```

Usage
-----

Simple usage example, see below for more examples:


```python
from rand_useragent import randua

# Get a random browser user-agent string
print(randua())
```

---

If you want to specify your own browser list, you can do that via the `browsers` 
argument (default is: `["chrome", "edge", "firefox", "safari"]`).  
This example will only return random useragents from Edge and Chrome:

```python
from rand_useragent import randua

# Get a random browser user-agent string
print(randua(browsers=["edge", "chrome"]))
```

---

If you want to specify your own operating systems, 
you can do that via the `os` argument (default is: `["windows", "mac os x", "linux"]`).  
In this example you will only get Linux useragents back:

```python
from rand_useragent import randua

# Get a random browser user-agent string
print(randua(os=["linux"]))
```

---

If you want to return more popular useragent strings, you can play with the `min_percent` 
argument (default is: `0.0`, meaning all useragents will match).  
In this example you get only useragents that have a minimum usage percentage of 10.0% (or higher):

```python
from rand_useragent import randua

# Get a random browser user-agent string
print(randua(min_percent=10.0))
```

---

You can override the fallback string using the `fallback` parameter, in very rare cases something failed:

```python
from rand_useragent import randua

# If something went wrong
print(
    randua(
        fallback="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36"
    )
)
```

Development
-----------

Since GitHub Actions is unable to reach willshouse.com and has Cloudflare protection. 
We can run the script below to automatically scrape the user-agent strings from the external data source. 
The script will copy the [JSONlines](https://jsonlines.org/) file to the `src/rand_useragent/data` directory.
Execute:

```shell
$ ./scripts/update-data.sh
```

The data JSON file is part of the Python package, 
see [pyproject.toml](https:://github.com/redbugg/rand-useragent/pyproject.toml). 
Read more about [Data files support](https://setuptools.pypa.io/en/latest/userguide/datafiles.html).

---

<p align="center">
    <i>rand-useragent is a <a href="https://github.com/redbugg/rand-useragent/blob/master/LICENSE">BSD licensed</a> code.</i>
</p>
