# yukinator
[](https://yukinator.readthedocs.io/en/latest/?badge=latest)[](https://pepy.tech/project/yukinator)
Unofficial API wrapper for [Ergast API](http://ergast.com/mrd/).
Created mainly for learning purposes. There are already at least two other wrappers worth checking: [fastF1](https://github.com/theOehrly/Fast-F1) - a swiss army knife for F1-related analyses, [pyErgast](https://github.com/weiranyu/pyErgast) - a neat pandas wrapper.
The name of the wrapper is Yukinator, in honor of the Japanese Formula 1 driver - Yuki Tsunoda.
## Features
- **Extensive**: covers all Ergast API endpoints
- **Responsible**: minimize the load on the API server
- implemented caching
- **Simple**: easy to use and customize:
- object-oriented design
- use of data transfer objects
- convert adequate fields from strings to the more suitable types
- **Lightweight**: minimal usage of the third-party packages
## Installation
```
pip install yukinator
```
## Getting started
Obtaining data for an Ergast API endpoint is very simple. For example, you can get a list of race objects from the 2020 season like this:
```python
import yukinator
y = yukinator.Yuki()
races_2020 = y.get_races(year=2020)
```
Check the docs to get acquainted with the methods for the rest of the endpoints.
The wrapper is initiated with the caching enabled by default. You can manually set the caching-related attributes like a directory for cache file, time after cached items expire, or clear the whole cache before the first request as follows:
```python
y = yukinator.Yuki(cache_dir='f1project/races', expires_after=9000, force_clear=True)
```
The caching can be also disabled (strongly not recommended):
```python
y = yukinator.Yuki(cache_enabled=False)
```
Chosen fields of the object can be accessed easily:
```python
race_1 = races_2020[0]
# print name of the race
print(race_1.raceName)
# print name from every nested Circuit object
for race in races_2020:
print(race.Circuit.circuitName)
```
Every object from the obtained list can be converted to the simpler structures:
```python
# convert object to the dictionary
race_1_dict = race_1.to_dict()
# convert object to the tuple
race_1_tuple = race_1.to_tuple()
# convert object to the flat dict - useful for creating pandas dataframes
race_1_flat_dict = race_1.to_flat_dict()
# convert object to a json string
race_1_json = race_1.to_json()
```
**WARNING**
The Ergast API has a limit of four calls per second and 200 per hour. Please take care while calling the methods within a loop.
## Documentation
The documentation is hosted on [ReadTheDocs.io](https://yukinator.readthedocs.io/en/latest/)
## Help, questions, and contributing
All contributors are very welcome. If you have any questions or a bug to report feel free to open an issue.
## External packages
Yukinator depends on these third-party packages:
* [attrs](https://www.attrs.org/en/stable/)
* [requests-cache](https://requests-cache.readthedocs.io/en/stable/)
Raw data
{
"_id": null,
"home_page": "https://github.com/BrozenSenpai/yukinator",
"name": "yukinator",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "Ergast API",
"author": "brozen",
"author_email": "szymon.mazurkievicz@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b2/72/7232f62f02ac8871d55c5b7f26702e994573df689b22491c68eb6c074d8a/yukinator-0.1.2.tar.gz",
"platform": null,
"description": "# yukinator\n[](https://yukinator.readthedocs.io/en/latest/?badge=latest)[](https://pepy.tech/project/yukinator)\n\nUnofficial API wrapper for [Ergast API](http://ergast.com/mrd/). \n\nCreated mainly for learning purposes. There are already at least two other wrappers worth checking: [fastF1](https://github.com/theOehrly/Fast-F1) - a swiss army knife for F1-related analyses, [pyErgast](https://github.com/weiranyu/pyErgast) - a neat pandas wrapper.\n\nThe name of the wrapper is Yukinator, in honor of the Japanese Formula 1 driver - Yuki Tsunoda.\n\n## Features\n- **Extensive**: covers all Ergast API endpoints\n- **Responsible**: minimize the load on the API server\n - implemented caching\n- **Simple**: easy to use and customize:\n - object-oriented design\n - use of data transfer objects\n - convert adequate fields from strings to the more suitable types\n- **Lightweight**: minimal usage of the third-party packages\n\n## Installation\n```\npip install yukinator\n ```\n\n## Getting started\nObtaining data for an Ergast API endpoint is very simple. For example, you can get a list of race objects from the 2020 season like this:\n```python\nimport yukinator\n\ny = yukinator.Yuki()\nraces_2020 = y.get_races(year=2020)\n```\nCheck the docs to get acquainted with the methods for the rest of the endpoints.\n\nThe wrapper is initiated with the caching enabled by default. You can manually set the caching-related attributes like a directory for cache file, time after cached items expire, or clear the whole cache before the first request as follows:\n```python\ny = yukinator.Yuki(cache_dir='f1project/races', expires_after=9000, force_clear=True)\n```\nThe caching can be also disabled (strongly not recommended):\n```python\ny = yukinator.Yuki(cache_enabled=False)\n```\nChosen fields of the object can be accessed easily:\n```python\nrace_1 = races_2020[0]\n\n# print name of the race\nprint(race_1.raceName)\n\n# print name from every nested Circuit object\nfor race in races_2020:\n print(race.Circuit.circuitName)\n```\nEvery object from the obtained list can be converted to the simpler structures:\n```python\n# convert object to the dictionary\nrace_1_dict = race_1.to_dict()\n\n# convert object to the tuple\nrace_1_tuple = race_1.to_tuple()\n\n# convert object to the flat dict - useful for creating pandas dataframes\nrace_1_flat_dict = race_1.to_flat_dict() \n\n# convert object to a json string\nrace_1_json = race_1.to_json()\n```\n\n**WARNING**\n\nThe Ergast API has a limit of four calls per second and 200 per hour. Please take care while calling the methods within a loop.\n\n## Documentation\nThe documentation is hosted on [ReadTheDocs.io](https://yukinator.readthedocs.io/en/latest/)\n\n## Help, questions, and contributing\nAll contributors are very welcome. If you have any questions or a bug to report feel free to open an issue.\n\n## External packages\nYukinator depends on these third-party packages:\n* [attrs](https://www.attrs.org/en/stable/)\n* [requests-cache](https://requests-cache.readthedocs.io/en/stable/)",
"bugtrack_url": null,
"license": "MIT",
"summary": "Unofficial Ergast API wrapper",
"version": "0.1.2",
"split_keywords": [
"ergast",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8189169f26a329fb1b08c72062f864d1bff88cc5a32056a3a7abdb15a89b4d73",
"md5": "8ce01e34e7a37dc407b948133d016f51",
"sha256": "5c68da1074ed60ea85e2c0fb11ed4507ccccca7b5ca855a73db1ec6e95ed1760"
},
"downloads": -1,
"filename": "yukinator-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ce01e34e7a37dc407b948133d016f51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 9793,
"upload_time": "2023-01-30T22:29:52",
"upload_time_iso_8601": "2023-01-30T22:29:52.006436Z",
"url": "https://files.pythonhosted.org/packages/81/89/169f26a329fb1b08c72062f864d1bff88cc5a32056a3a7abdb15a89b4d73/yukinator-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b2727232f62f02ac8871d55c5b7f26702e994573df689b22491c68eb6c074d8a",
"md5": "d67c7e15468cde7dc54d1cd016ddde4d",
"sha256": "2b9238125c94a0e529955cc674dc7714f729bf2637d38fd6ebfc92c27a9a1341"
},
"downloads": -1,
"filename": "yukinator-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "d67c7e15468cde7dc54d1cd016ddde4d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 10047,
"upload_time": "2023-01-30T22:29:54",
"upload_time_iso_8601": "2023-01-30T22:29:54.644393Z",
"url": "https://files.pythonhosted.org/packages/b2/72/7232f62f02ac8871d55c5b7f26702e994573df689b22491c68eb6c074d8a/yukinator-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-30 22:29:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "BrozenSenpai",
"github_project": "yukinator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "yukinator"
}
JSON
