# HowLongToBeat Python API
[](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/actions/workflows/python-test-release.yml)
[](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/actions/workflows/codeql-analysis.yml)
[](https://codecov.io/gh/ScrappyCocco/HowLongToBeat-PythonAPI)
[](https://sonarcloud.io/dashboard?id=ScrappyCocco_HowLongToBeat-PythonAPI)
A simple Python API to read data from howlongtobeat.com.
It is inspired by [ckatzorke - howlongtobeat](https://github.com/ckatzorke/howlongtobeat) JS API.
## Content
- [Usage](#usage)
- [Installation](#installation)
- [Installing the package downloading the last release](#installing-the-package-downloading-the-last-release)
- [Installing the package from the source code](#installing-the-package-from-the-source-code)
- [Usage in code](#usage-in-code)
- [Start including it in your file](#start-including-it-in-your-file)
- [Now call search()](#now-call-search)
- [Alternative search (by ID)](#alternative-search-by-id)
- [DLC search](#dlc-search)
- [Results auto-filter](#results-auto-filter)
- [Reading an entry](#reading-an-entry)
- [Issues, Questions & Discussions](#issues-questions--discussions)
- [Authors](#authors)
- [License](#license)
## Usage
## Installation
### Installing the package downloading the last release
```python
pip install howlongtobeatpy
```
### Installing the package from the source code
Download the repo, enter the folder with 'setup.py' and run the command
```python
pip install .
```
## Usage in code
### Start including it in your file
```python
from howlongtobeatpy import HowLongToBeat
```
### Now call search()
The API main functions are:
```python
results = HowLongToBeat().search("Awesome Game")
```
or, if you prefer using async:
```python
results = await HowLongToBeat().async_search("Awesome Game")
```
The return of that function is a **list** of possible games, or **None** in case you passed an invalid "game name" as parameter or if there was an error in the request.
If the list **is not None** you should choose the best entry checking the Similarity value with the original name, example:
```python
results_list = await HowLongToBeat().async_search("Awesome Game")
if results_list is not None and len(results_list) > 0:
best_element = max(results_list, key=lambda element: element.similarity)
```
Once done, "best_element" will contain the best game found in the research.
Every entry in the list (if not None in case of errors) is an object of type: [HowLongToBeatEntry](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/blob/master/howlongtobeatpy/howlongtobeatpy/HowLongToBeatEntry.py).
### Alternative search (by ID)
If you prefer, you can get a game by ID, this can be useful if you already have the game's howlongtobeat-id (the ID is the number in the URL, for example in [https://howlongtobeat.com/game/7231]([hello](https://howlongtobeat.com/game/7231)) the ID is 7231).
To avoid a new parser, the search by ID use a first request to get the game title, and then use the standard search with that title, filtering the results and returning the unique game with that ID.
Remember that it could be a bit slower, but you avoid searching the game in the array by similarity.
Here's the example:
```python
result = HowLongToBeat().search_from_id(123456)
```
or, if you prefer using async:
```python
result = await HowLongToBeat().async_search_from_id(123456)
```
This call will return an unique [HowLongToBeatEntry](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/blob/master/howlongtobeatpy/howlongtobeatpy/HowLongToBeatEntry.py) or None in case of errors.
### DLC search
An `enum` has been added to have a filter in the search:
```python
SearchModifiers.NONE # default
SearchModifiers.ISOLATE_DLC
SearchModifiers.HIDE_DLC
```
This optional parameter allow you to specify in the search if you want the default search (with DLCs), to HIDE DLCs and only show games, or to ISOLATE DLCs (show only DLCs).
### Results auto-filter
To ignore games with a very different name, the standard search automatically filter results with a game name that has a similarity with the given name > than `0.4`, not adding the others to the result list.
If you want all the results, or you want to change this value, you can put a parameter in the constructor:
```python
results = HowLongToBeat(0.0).search("Awesome Game")
```
putting `0.0` (or just `0`) will return all the found games, otherwise you can write another (`float`) number between 0...1 to set a new filter, such as `0.7`.
Also remember that by default the similarity check **is case-sensitive** between the name given and the name found, if you want to ignore the case you can use:
```python
results = HowLongToBeat(0.0).search("Awesome Game", similarity_case_sensitive=False)
```
**Remember** that, when searching by ID, the similarity value and the case-sensitive bool are **ignored**.
### Reading an entry
An entry is made of few values, you can check them [in the Entry class file](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/blob/master/howlongtobeatpy/howlongtobeatpy/HowLongToBeatEntry.py). It also include the full JSON of values (already converted to Python dict) received from HLTB.
## Issues, Questions & Discussions
If you found a bug report it as soon as you can creating an [issue](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/issues/new), the code may not be perfect.
If you need any new feature, or want to discuss the current implementation/features, consider opening a [discussion](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/discussions) or even propose a change with a [Pull Request](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/pulls).
## Authors
* **ScrappyCocco** - Thank you for using my API
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details
Raw data
{
"_id": null,
"home_page": "https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI",
"name": "howlongtobeatpy",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "howlongtobeat gaming steam uplay origin time length how long to beat",
"author": "ScrappyCocco",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/97/bc/74dc9ad0fc7ade0389784f40e289e2c48e6d6a1e3af89370c4ece1b2b4c4/howlongtobeatpy-1.0.5.tar.gz",
"platform": null,
"description": "# HowLongToBeat Python API\r\n\r\n[](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/actions/workflows/python-test-release.yml)\r\n[](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/actions/workflows/codeql-analysis.yml)\r\n\r\n[](https://codecov.io/gh/ScrappyCocco/HowLongToBeat-PythonAPI)\r\n[](https://sonarcloud.io/dashboard?id=ScrappyCocco_HowLongToBeat-PythonAPI)\r\n\r\nA simple Python API to read data from howlongtobeat.com.\r\n\r\nIt is inspired by [ckatzorke - howlongtobeat](https://github.com/ckatzorke/howlongtobeat) JS API.\r\n\r\n## Content\r\n\r\n- [Usage](#usage)\r\n- [Installation](#installation)\r\n - [Installing the package downloading the last release](#installing-the-package-downloading-the-last-release)\r\n - [Installing the package from the source code](#installing-the-package-from-the-source-code)\r\n- [Usage in code](#usage-in-code)\r\n - [Start including it in your file](#start-including-it-in-your-file)\r\n - [Now call search()](#now-call-search)\r\n - [Alternative search (by ID)](#alternative-search-by-id)\r\n - [DLC search](#dlc-search)\r\n - [Results auto-filter](#results-auto-filter)\r\n - [Reading an entry](#reading-an-entry)\r\n- [Issues, Questions & Discussions](#issues-questions--discussions)\r\n- [Authors](#authors)\r\n- [License](#license)\r\n\r\n## Usage\r\n\r\n## Installation\r\n\r\n### Installing the package downloading the last release\r\n\r\n```python\r\npip install howlongtobeatpy\r\n```\r\n\r\n### Installing the package from the source code\r\n\r\nDownload the repo, enter the folder with 'setup.py' and run the command\r\n\r\n```python\r\npip install .\r\n```\r\n\r\n## Usage in code\r\n\r\n### Start including it in your file\r\n\r\n```python\r\nfrom howlongtobeatpy import HowLongToBeat\r\n```\r\n\r\n### Now call search()\r\n\r\nThe API main functions are:\r\n\r\n```python\r\nresults = HowLongToBeat().search(\"Awesome Game\")\r\n```\r\n\r\nor, if you prefer using async:\r\n\r\n```python\r\nresults = await HowLongToBeat().async_search(\"Awesome Game\")\r\n```\r\n\r\nThe return of that function is a **list** of possible games, or **None** in case you passed an invalid \"game name\" as parameter or if there was an error in the request.\r\n\r\nIf the list **is not None** you should choose the best entry checking the Similarity value with the original name, example:\r\n\r\n```python\r\nresults_list = await HowLongToBeat().async_search(\"Awesome Game\")\r\nif results_list is not None and len(results_list) > 0:\r\n best_element = max(results_list, key=lambda element: element.similarity)\r\n```\r\n\r\nOnce done, \"best_element\" will contain the best game found in the research.\r\nEvery entry in the list (if not None in case of errors) is an object of type: [HowLongToBeatEntry](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/blob/master/howlongtobeatpy/howlongtobeatpy/HowLongToBeatEntry.py).\r\n\r\n### Alternative search (by ID)\r\n\r\nIf you prefer, you can get a game by ID, this can be useful if you already have the game's howlongtobeat-id (the ID is the number in the URL, for example in [https://howlongtobeat.com/game/7231]([hello](https://howlongtobeat.com/game/7231)) the ID is 7231).\r\n\r\nTo avoid a new parser, the search by ID use a first request to get the game title, and then use the standard search with that title, filtering the results and returning the unique game with that ID.\r\n\r\nRemember that it could be a bit slower, but you avoid searching the game in the array by similarity.\r\n\r\nHere's the example:\r\n\r\n```python\r\nresult = HowLongToBeat().search_from_id(123456)\r\n```\r\n\r\nor, if you prefer using async:\r\n\r\n```python\r\nresult = await HowLongToBeat().async_search_from_id(123456)\r\n```\r\n\r\nThis call will return an unique [HowLongToBeatEntry](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/blob/master/howlongtobeatpy/howlongtobeatpy/HowLongToBeatEntry.py) or None in case of errors.\r\n\r\n### DLC search\r\n\r\nAn `enum` has been added to have a filter in the search:\r\n\r\n```python\r\nSearchModifiers.NONE # default\r\nSearchModifiers.ISOLATE_DLC\r\nSearchModifiers.HIDE_DLC\r\n```\r\n\r\nThis optional parameter allow you to specify in the search if you want the default search (with DLCs), to HIDE DLCs and only show games, or to ISOLATE DLCs (show only DLCs).\r\n\r\n### Results auto-filter\r\n\r\nTo ignore games with a very different name, the standard search automatically filter results with a game name that has a similarity with the given name > than `0.4`, not adding the others to the result list.\r\nIf you want all the results, or you want to change this value, you can put a parameter in the constructor:\r\n\r\n```python\r\nresults = HowLongToBeat(0.0).search(\"Awesome Game\")\r\n```\r\n\r\nputting `0.0` (or just `0`) will return all the found games, otherwise you can write another (`float`) number between 0...1 to set a new filter, such as `0.7`.\r\n\r\nAlso remember that by default the similarity check **is case-sensitive** between the name given and the name found, if you want to ignore the case you can use:\r\n\r\n```python\r\nresults = HowLongToBeat(0.0).search(\"Awesome Game\", similarity_case_sensitive=False)\r\n```\r\n\r\n**Remember** that, when searching by ID, the similarity value and the case-sensitive bool are **ignored**.\r\n\r\n### Reading an entry\r\n\r\nAn entry is made of few values, you can check them [in the Entry class file](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/blob/master/howlongtobeatpy/howlongtobeatpy/HowLongToBeatEntry.py). It also include the full JSON of values (already converted to Python dict) received from HLTB.\r\n\r\n## Issues, Questions & Discussions\r\n\r\nIf you found a bug report it as soon as you can creating an [issue](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/issues/new), the code may not be perfect.\r\n\r\nIf you need any new feature, or want to discuss the current implementation/features, consider opening a [discussion](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/discussions) or even propose a change with a [Pull Request](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI/pulls).\r\n\r\n## Authors\r\n\r\n* **ScrappyCocco** - Thank you for using my API\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python API for How Long to Beat",
"version": "1.0.5",
"split_keywords": [
"howlongtobeat",
"gaming",
"steam",
"uplay",
"origin",
"time",
"length",
"how",
"long",
"to",
"beat"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "6b2d29f6b66db46ac8491aab8e08fb6e",
"sha256": "4af041092f6ed1605f550103658583f9cf4b6b033f04c54c77c4beff4fd15380"
},
"downloads": -1,
"filename": "howlongtobeatpy-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "6b2d29f6b66db46ac8491aab8e08fb6e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11164,
"upload_time": "2022-12-02T11:20:25",
"upload_time_iso_8601": "2022-12-02T11:20:25.614981Z",
"url": "https://files.pythonhosted.org/packages/97/bc/74dc9ad0fc7ade0389784f40e289e2c48e6d6a1e3af89370c4ece1b2b4c4/howlongtobeatpy-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-02 11:20:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ScrappyCocco",
"github_project": "HowLongToBeat-PythonAPI",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "howlongtobeatpy"
}
JSON
