Metadata-Version: 2.1
Name: tranco
Version: 0.8.1
Summary: Tranco: A Research-Oriented Top Sites Ranking Hardened Against Manipulation
Home-page: https://github.com/DistriNet/tranco-python-package
Author: Victor Le Pochat
Author-email: victor.lepochat@kuleuven.be
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: codetiming ; extra == 'dev'

# Tranco

This package allows easy access to the Tranco list, published at [https://tranco-list.eu](https://tranco-list.eu/).

## Usage

Create a `Tranco` object, indicating where you want to cache downloaded lists (caching is required):
```python
from tranco import Tranco
t = Tranco(cache=True, cache_dir='.tranco')
```

You can then retrieve lists from this object using the `list` method:

```python
latest_list = t.list()
date_list = t.list(date='2019-02-25')
```

The `list` method accepts the following parameters:
- `date`: the date of the list you want to retrieve (in the format `YYYY-MM-DD`). If not given, the latest daily list is returned
- `list_id`: the ID of the list you want to retrieve. If neither list ID nor date are given, the latest daily list is returned. If both are given, you will get an exception
- `subdomains`: whether to include subdomains; only relevant when requesting a daily list. Default: False
- `full`: whether to retrieve the full list (else only the top million). Default: False

This method returns a `TrancoList`, which allows you to retrieve a certain prefix of the list (`top`), 
the list ID (`list_id`), the list page (`list_page`) or the rank of a domain (`rank`):
```python
latest_list.top(10000)
latest_list.list_id
latest_list.list_page
latest_list.rank("google.com")
latest_list.rank("not.in.ranking") # returns -1
```

You can also generate custom lists. 
First, create a `Tranco` object with valid credentials 
(available from your [account page](https://tranco-list.eu/account)):
```python
from tranco import Tranco
t = Tranco(account_email="abc@xyz.eu", api_key="123ABC")
```

Then, pass the configuration (according to [this schema](https://tranco-list.eu/api_documentation#datatypes-configuration))
of your custom list to `configure`:
```python
c = t.configure(
    {
        'providers': ['alexa', 'umbrella', 'majestic'],
        'startDate': '2021-01-01',
        'endDate': '2021-01-30',
        'combinationMethod': 'dowdall',
        'listPrefix': 'full',
        'filterPLD': 'on',
    }
)
```
This method returns a tuple: whether the list is already available or is still being generated, 
and the ID that has been/will be assigned to the list.

You can retrieve metadata for a list through `list_metadata`:
```python
m = t.list_metadata(list_id="6P7X")
```
If a list is still being generated, you can use this method to track the progress; 
once a list has been generated, this metadata will indicate how the list was configured.
