The World Anvil API Python Client is a wrapper client designed to work with the Boromir API released by World Anvil on August 26, 2023. Please note that this client is currently a work in progress and may not have all features implemented. The World Anvil API enables users to interact with the World Anvil database by utilizing various API endpoints.
> NOTE: If you find any issues feel free to open an issue and I will try to fix it.
The latest version compatible with Aragorn is `0.12.1`. However, please be aware that the developer will not maintain the Aragorn version of the client. For Boromir, the latest version is recommended.
<details>
<summary>Latest</summary>
For the latest Boromir API Documentation, please visit:
- [Boromir API Documentation](https://www.worldanvil.com/api/external/boromir/documentation)
- [Boromir API Swagger Documentation](https://www.worldanvil.com/api/external/boromir/swagger-documentation)
</details>
<details>
<summary>Older Versions</summary>
The Aragorn API is deprecated and will be removed in the future. However, if needed, you can still access the Aragorn API Documentation here:
- [Aragorn API Documentation](https://www.worldanvil.com/api/aragorn/documentation)
</details>
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Endpoints](#endpoints)
- [Exceptions](#exceptions)
- [Classes](#classes)
## Installation
The package is published on PyPI and can be installed with pip. To install, run:
```python
pip --install pywaclient
```
## Usage
Below is a simple example on how to use the endpoints:
```python
import os
from pywaclient.api import BoromirApiClient
client = BoromirApiClient(
'<YourScriptName>',
'<link-to-your-website-or-bot-repository>',
'<version>',
os.environ['WA_APPLICATION_KEY'],
os.environ['WA_AUTH_TOKEN']
)
# get your own user id. It is not possible to discover the user ids of other users via the API.
authenticated_user = client.user.identity()
# get the references to all the worlds on your account.
worlds = [world for world in client.user.worlds(authenticated_user['id'])]
# get the references to all the category on the first world.
categories = [category for category in client.world.categories(worlds[0]['id'])]
# gets a list of all the articles without a category in the first world
articles = [article for article in client.category.articles(worlds[0]['id'], '-1')]
# gets the full content of the first article
article = client.article.get(articles[0]['id'], 2)
# gets the full content of the first category. Categories and most other resources do not have a granularity of 2.
category = client.category.get(categories[0]['id'], 1)
```
## Endpoints
The `BoromirApiClient` class in the **api.py** file includes the following endpoints:
| **Endpoint** | **con't.** |
|----------------|----------------------|
| /article | /map |
| /block | /markertype |
| /blockfolder | /notebook |
| /blocktemplate | /rpgsystem |
| /canvas | /secret |
| /category | /subscribergroup |
| /chronicle | /timeline |
| /history | /user |
| /image | /variable_collection |
| /manuscript | /world |
Additionally, the endpoints directory contains several Python files each representing a specific endpoint of the World Anvil API. This includes articles, blocks, categories, histories, images, maps, secrets, timelines, users, worlds, and more. Each file contains a class with methods for interacting with the respective endpoint.
## Exceptions
The **exceptions.py** file includes a series of exception classes to handle different types of errors:
| **Exception Class** | **Description** |
|-------------------------------|-----------------------------------------|
| **WorldAnvilClientException** | Base exception class. |
| **WorldAnvilServerException** | Unsuccessful server response. |
| **ConnectionException** | Connection problem with the API server. |
| **UnexpectedStatusException** | Unexpected status code from server. |
| **InternalServerException** | Server responded with a 500 status. |
| **UnauthorizedRequest** | The request was not authorized. |
| **AccessForbidden** | Access to resource is forbidden. |
| **ResourceNotFound** | The requested resource was not found. |
| **UnprocessableDataProvided** | Unprocessable data was provided. |
| **FailedRequest** | The request failed. |
Each of these exception classes are used to handle specific types of errors that may arise when using the World Anvil API Python Client.
## Classes
#### BoromirApiClient Class
The `BoromirApiClient` class is the central class in the file. It contains the headers and base URL for API communication. It also initializes the different API endpoints.
```python
class BoromirApiClient:
def __init__(self, name: str, url: str, version: str, application_key: str, authentication_token: str):
self.headers = {
'x-auth-token': authentication_token,
'x-application-key': application_key,
'Accept': 'application/json',
'User-Agent': f'{name} ({url}, {version})'
}
self.headers_post = self.headers.copy()
self.headers_post['Content-type'] = 'application/json'
self.base_url = 'https://www.worldanvil.com/api/external/boromir/'
self.article = ArticleCrudEndpoint(self)
# etc.
```
#### BasicEndpoint Class
This class contains methods for making HTTP requests (`GET`, `PUT`, `PATCH`, `POST`, `DELETE`). These methods are used to interact with the API - fetch, create, update, and delete resources. After making a request, the `_parse_response` function is used to handle the response from the server.
```python
class BasicEndpoint:
def __init__(self, client: 'AragornApiClient', base_path: str):
self.client = client
self.path = base_path
# etc.
```
#### CrudEndpoint Class
The `CrudEndpoint` class inherits from the `BasicEndpoint` class and provides methods for creating (`PUT`), updating (`PATCH`), and deleting (`DELETE`) resources.
```python
class CrudEndpoint(BasicEndpoint):
def __init__(self, client: 'AragornApiClient', base_path: str):
super().__init__(client, base_path)
# etc.
```
## License
This project is licensed under the terms of the Apache 2.0 License. For complete details, refer to the license [here](http://www.apache.org/licenses/LICENSE-2.0).
Software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/SoulLink/world-anvil-api-client",
"name": "pywaclient",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Jonas Waeber",
"author_email": "jonaswaeber@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8c/c8/84ae2908cc0dc449a8702574e9e95fbc2eb95e46eaab36ddef2c8a6b3e71/pywaclient-1.6.5.tar.gz",
"platform": null,
"description": "The World Anvil API Python Client is a wrapper client designed to work with the Boromir API released by World Anvil on August 26, 2023. Please note that this client is currently a work in progress and may not have all features implemented. The World Anvil API enables users to interact with the World Anvil database by utilizing various API endpoints.\n\n> NOTE: If you find any issues feel free to open an issue and I will try to fix it. \n\nThe latest version compatible with Aragorn is `0.12.1`. However, please be aware that the developer will not maintain the Aragorn version of the client. For Boromir, the latest version is recommended.\n\n<details>\n<summary>Latest</summary>\n\nFor the latest Boromir API Documentation, please visit:\n\n- [Boromir API Documentation](https://www.worldanvil.com/api/external/boromir/documentation) \n- [Boromir API Swagger Documentation](https://www.worldanvil.com/api/external/boromir/swagger-documentation)\n</details>\n\n<details>\n<summary>Older Versions</summary>\n\nThe Aragorn API is deprecated and will be removed in the future. However, if needed, you can still access the Aragorn API Documentation here:\n \n- [Aragorn API Documentation](https://www.worldanvil.com/api/aragorn/documentation)\n</details>\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Endpoints](#endpoints)\n- [Exceptions](#exceptions)\n- [Classes](#classes)\n\n## Installation\n\nThe package is published on PyPI and can be installed with pip. To install, run:\n\n```python\npip --install pywaclient\n```\n\n## Usage\n\nBelow is a simple example on how to use the endpoints:\n\n```python\nimport os\nfrom pywaclient.api import BoromirApiClient\n\nclient = BoromirApiClient(\n '<YourScriptName>',\n '<link-to-your-website-or-bot-repository>',\n '<version>',\n os.environ['WA_APPLICATION_KEY'],\n os.environ['WA_AUTH_TOKEN']\n)\n\n# get your own user id. It is not possible to discover the user ids of other users via the API.\nauthenticated_user = client.user.identity()\n\n# get the references to all the worlds on your account.\nworlds = [world for world in client.user.worlds(authenticated_user['id'])]\n\n# get the references to all the category on the first world.\ncategories = [category for category in client.world.categories(worlds[0]['id'])]\n\n# gets a list of all the articles without a category in the first world\narticles = [article for article in client.category.articles(worlds[0]['id'], '-1')]\n\n# gets the full content of the first article\narticle = client.article.get(articles[0]['id'], 2)\n\n# gets the full content of the first category. Categories and most other resources do not have a granularity of 2.\ncategory = client.category.get(categories[0]['id'], 1)\n```\n\n## Endpoints\n\nThe `BoromirApiClient` class in the **api.py** file includes the following endpoints:\n\n| **Endpoint** | **con't.** |\n|----------------|----------------------|\n| /article | /map |\n| /block | /markertype |\n| /blockfolder | /notebook |\n| /blocktemplate | /rpgsystem |\n| /canvas | /secret |\n| /category | /subscribergroup |\n| /chronicle | /timeline |\n| /history | /user |\n| /image | /variable_collection |\n| /manuscript | /world |\n\nAdditionally, the endpoints directory contains several Python files each representing a specific endpoint of the World Anvil API. This includes articles, blocks, categories, histories, images, maps, secrets, timelines, users, worlds, and more. Each file contains a class with methods for interacting with the respective endpoint.\n\n## Exceptions\n\nThe **exceptions.py** file includes a series of exception classes to handle different types of errors:\n\n| **Exception Class** | **Description** |\n|-------------------------------|-----------------------------------------|\n| **WorldAnvilClientException** | Base exception class. |\n| **WorldAnvilServerException** | Unsuccessful server response. |\n| **ConnectionException** | Connection problem with the API server. |\n| **UnexpectedStatusException** | Unexpected status code from server. |\n| **InternalServerException** | Server responded with a 500 status. |\n| **UnauthorizedRequest** | The request was not authorized. |\n| **AccessForbidden** | Access to resource is forbidden. |\n| **ResourceNotFound** | The requested resource was not found. |\n| **UnprocessableDataProvided** | Unprocessable data was provided. |\n| **FailedRequest** | The request failed. |\n\nEach of these exception classes are used to handle specific types of errors that may arise when using the World Anvil API Python Client.\n\n## Classes\n\n#### BoromirApiClient Class\n\nThe `BoromirApiClient` class is the central class in the file. It contains the headers and base URL for API communication. It also initializes the different API endpoints.\n\n```python\nclass BoromirApiClient:\n def __init__(self, name: str, url: str, version: str, application_key: str, authentication_token: str):\n self.headers = {\n 'x-auth-token': authentication_token,\n 'x-application-key': application_key,\n 'Accept': 'application/json',\n 'User-Agent': f'{name} ({url}, {version})'\n }\n self.headers_post = self.headers.copy()\n self.headers_post['Content-type'] = 'application/json'\n self.base_url = 'https://www.worldanvil.com/api/external/boromir/'\n self.article = ArticleCrudEndpoint(self)\n # etc.\n```\n\n#### BasicEndpoint Class\n\nThis class contains methods for making HTTP requests (`GET`, `PUT`, `PATCH`, `POST`, `DELETE`). These methods are used to interact with the API - fetch, create, update, and delete resources. After making a request, the `_parse_response` function is used to handle the response from the server.\n\n```python\nclass BasicEndpoint:\n def __init__(self, client: 'AragornApiClient', base_path: str):\n self.client = client\n self.path = base_path\n # etc.\n```\n\n#### CrudEndpoint Class\n\nThe `CrudEndpoint` class inherits from the `BasicEndpoint` class and provides methods for creating (`PUT`), updating (`PATCH`), and deleting (`DELETE`) resources.\n\n```python\nclass CrudEndpoint(BasicEndpoint):\n def __init__(self, client: 'AragornApiClient', base_path: str):\n super().__init__(client, base_path)\n # etc.\n```\n\n## License\n\nThis project is licensed under the terms of the Apache 2.0 License. For complete details, refer to the license [here](http://www.apache.org/licenses/LICENSE-2.0).\n\nSoftware is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A simple wrapper client library for the World Anvil API.",
"version": "1.6.5",
"project_urls": {
"Homepage": "https://gitlab.com/SoulLink/world-anvil-api-client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "907e2eb9527b995a4163f24ea78e5f472c23bcf86178ad3a9a1175e963a4d0e6",
"md5": "220f5311c49ebf7c68990678a3d2afcc",
"sha256": "98adece581dff5d15e7baae151f6301b80e176568d02c38d3db167c51e598c87"
},
"downloads": -1,
"filename": "pywaclient-1.6.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "220f5311c49ebf7c68990678a3d2afcc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 31153,
"upload_time": "2024-02-16T18:31:44",
"upload_time_iso_8601": "2024-02-16T18:31:44.801913Z",
"url": "https://files.pythonhosted.org/packages/90/7e/2eb9527b995a4163f24ea78e5f472c23bcf86178ad3a9a1175e963a4d0e6/pywaclient-1.6.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8cc884ae2908cc0dc449a8702574e9e95fbc2eb95e46eaab36ddef2c8a6b3e71",
"md5": "72905739a91d8cabc4383ba7fd500cc5",
"sha256": "c2a9a429ce78e5aea27339456dcdf592b640392977ce3466eb7d47cf97c6ff7c"
},
"downloads": -1,
"filename": "pywaclient-1.6.5.tar.gz",
"has_sig": false,
"md5_digest": "72905739a91d8cabc4383ba7fd500cc5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24325,
"upload_time": "2024-02-16T18:31:46",
"upload_time_iso_8601": "2024-02-16T18:31:46.508883Z",
"url": "https://files.pythonhosted.org/packages/8c/c8/84ae2908cc0dc449a8702574e9e95fbc2eb95e46eaab36ddef2c8a6b3e71/pywaclient-1.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-16 18:31:46",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "SoulLink",
"gitlab_project": "world-anvil-api-client",
"lcname": "pywaclient"
}
JSON