## Python Open Pinball Database Client
This is a Python client for the Open Pinball Database API.
### Installation
```bash
pip install open-pinball-db
```
```python
import open_pinball_db
opdb_client = open_pinball_db.Client()
# Start using the client
```
## Usage
### Public API (no authentication required)
#### Get changelog
```python
import open_pinball_db
opdb_client = open_pinball_db.Client()
opdb_client.get_changelog()
```
#### Typeahead search
| Parameter | Type | Description |
|-----------------|------|-----------------------------------------------------------|
| q | str | The search query |
| include_aliases | bool | Whether to include aliases in the search. Default is True |
| include_groups | bool | Whether to include groups in the search. Default is False |
```python
import open_pinball_db
opdb_client = open_pinball_db.Client()
opdb_client.typeahead_search('The Addams Family')
```
### Private API (authentication required)
Get your free api key at [Open Pinball Database](https://opdb.org/).
#### Search Machines
| Parameter | Type | Description |
|--------------------------|------|---------------------------------------------------------------------|
| q | str | The search query |
| require_opdb | bool | Limit results to machines with OPDB ids. Defaults to True |
| include_aliases | bool | Whether to include aliases in the search. Default is True |
| include_groups | bool | Whether to include groups in the search. Default is False |
| include_grouping_entries | bool | Whether to include grouping entries in the search. Default is False |
```python
import open_pinball_db
opdb_client = open_pinball_db.Client(api_key="your_secret_api_key")
opdb_client.search('The Addams Family')
```
#### Get Machine By OPDB ID
| Parameter | Type | Description |
|-----------|------|----------------------------|
| opdb_id | str | The IPDB ID of the machine |
```python
import open_pinball_db
opdb_client = open_pinball_db.Client(api_key="your_secret_api_key")
opdb_client.get_machine("OPDB-ID")
```
#### Get Machine By IPDB ID
| Parameter | Type | Description |
|-----------|------|----------------------------|
| ipdb_id | int | The IPDB ID of the machine |
```python
import open_pinball_db
opdb_client = open_pinball_db.Client(api_key="your_secret_api_key")
opdb_client.get_machine_by_ipdb_id(1234)
```
#### Export Machines and Aliases
Export all machines and aliases into a big json document. According to the OPDB
API docs this endpoint is rate limited to once every hour.
```python
import open_pinball_db
opdb_client = open_pinball_db.Client(api_key="your_secret_api_key")
opdb_client.export_machines_and_aliases()
```
#### Export Machines Groups
Export all machine groups as a single JSON document.
```python
import open_pinball_db
opdb_client = open_pinball_db.Client(api_key="your_secret_api_key")
opdb_client.export_machine_groups()
```
### Handling Exceptions
The client can raise the following exceptions:
| Exception | Description |
|-------------------|-------------------------------------------------------------------------------|
| OpdbError | Base exception class for all exceptions |
| OpdbMissingApiKey | Raised when trying to access private parts of the OPDB API without an API key |
| OpdbHttpError | Raised upon http errors. Contains status code and message. |
| OpdbTimeoutError | Raised upon timeout errors. |
Raw data
{
"_id": null,
"home_page": "https://github.com/Mollemoll/open-pinball-db",
"name": "open-pinball-db",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "pinball, database, client",
"author": "Mollemoll",
"author_email": "jonas.molander@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c3/92/8377c5c5be69e2efaac67256d06b2b7c6e601938c1ae4b7b996a036f7d8e/open_pinball_db-0.1.0.tar.gz",
"platform": null,
"description": "## Python Open Pinball Database Client\n\nThis is a Python client for the Open Pinball Database API.\n\n### Installation\n\n```bash\npip install open-pinball-db\n```\n\n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client()\n\n# Start using the client\n```\n\n## Usage\n\n### Public API (no authentication required)\n\n#### Get changelog\n \n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client()\nopdb_client.get_changelog()\n```\n\n#### Typeahead search\n\n| Parameter | Type | Description |\n|-----------------|------|-----------------------------------------------------------|\n| q | str | The search query |\n| include_aliases | bool | Whether to include aliases in the search. Default is True |\n| include_groups | bool | Whether to include groups in the search. Default is False |\n\n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client()\nopdb_client.typeahead_search('The Addams Family')\n```\n\n### Private API (authentication required)\n\nGet your free api key at [Open Pinball Database](https://opdb.org/).\n\n#### Search Machines\n\n| Parameter | Type | Description |\n|--------------------------|------|---------------------------------------------------------------------|\n| q | str | The search query |\n| require_opdb | bool | Limit results to machines with OPDB ids. Defaults to True | \n| include_aliases | bool | Whether to include aliases in the search. Default is True |\n| include_groups | bool | Whether to include groups in the search. Default is False |\n| include_grouping_entries | bool | Whether to include grouping entries in the search. Default is False |\n\n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client(api_key=\"your_secret_api_key\")\nopdb_client.search('The Addams Family')\n```\n\n#### Get Machine By OPDB ID\n\n| Parameter | Type | Description |\n|-----------|------|----------------------------|\n| opdb_id | str | The IPDB ID of the machine |\n\n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client(api_key=\"your_secret_api_key\")\nopdb_client.get_machine(\"OPDB-ID\")\n```\n\n#### Get Machine By IPDB ID\n\n| Parameter | Type | Description |\n|-----------|------|----------------------------|\n| ipdb_id | int | The IPDB ID of the machine |\n\n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client(api_key=\"your_secret_api_key\")\nopdb_client.get_machine_by_ipdb_id(1234)\n```\n\n#### Export Machines and Aliases\n\nExport all machines and aliases into a big json document. According to the OPDB\nAPI docs this endpoint is rate limited to once every hour.\n\n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client(api_key=\"your_secret_api_key\")\nopdb_client.export_machines_and_aliases()\n```\n\n#### Export Machines Groups\n\nExport all machine groups as a single JSON document.\n\n```python\nimport open_pinball_db\nopdb_client = open_pinball_db.Client(api_key=\"your_secret_api_key\")\nopdb_client.export_machine_groups()\n```\n\n### Handling Exceptions\n\nThe client can raise the following exceptions:\n\n| Exception | Description |\n|-------------------|-------------------------------------------------------------------------------|\n| OpdbError | Base exception class for all exceptions |\n| OpdbMissingApiKey | Raised when trying to access private parts of the OPDB API without an API key |\n| OpdbHttpError | Raised upon http errors. Contains status code and message. |\n| OpdbTimeoutError | Raised upon timeout errors. |\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An open pinball database client for Python",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/Mollemoll/open-pinball-db#readme",
"Homepage": "https://github.com/Mollemoll/open-pinball-db",
"Repository": "https://github.com/Mollemoll/open-pinball-db"
},
"split_keywords": [
"pinball",
" database",
" client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3e7720673685b52d71ff2b5780317a25ebf13ea59654dd88ff90c4749a252f9",
"md5": "fa1a6544f15a1ca2d312b7b1d33f9dce",
"sha256": "d7d9cb56918da56a19b01c0efea0c8a99771c344185b79a47c06e3e2e55b17b4"
},
"downloads": -1,
"filename": "open_pinball_db-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa1a6544f15a1ca2d312b7b1d33f9dce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 4842,
"upload_time": "2024-10-14T20:40:17",
"upload_time_iso_8601": "2024-10-14T20:40:17.280157Z",
"url": "https://files.pythonhosted.org/packages/c3/e7/720673685b52d71ff2b5780317a25ebf13ea59654dd88ff90c4749a252f9/open_pinball_db-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c3928377c5c5be69e2efaac67256d06b2b7c6e601938c1ae4b7b996a036f7d8e",
"md5": "759ee69423486a45aaebf3268e29646d",
"sha256": "9decb97bd5b77ef95e9319520aeb9c28d899a47e6007f22cf19e795c4eb9c472"
},
"downloads": -1,
"filename": "open_pinball_db-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "759ee69423486a45aaebf3268e29646d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 3769,
"upload_time": "2024-10-14T20:40:19",
"upload_time_iso_8601": "2024-10-14T20:40:19.128721Z",
"url": "https://files.pythonhosted.org/packages/c3/92/8377c5c5be69e2efaac67256d06b2b7c6e601938c1ae4b7b996a036f7d8e/open_pinball_db-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-14 20:40:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mollemoll",
"github_project": "open-pinball-db",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "open-pinball-db"
}
JSON
