<div align="center">
<h1><a href="https://jisho.org/word/%E6%9C%AC%E6%A3%9A">Hondana 『本棚』</a></h1>
<a href='https://github.com/AbstractUmbra/Hondana/actions/workflows/build.yaml'>
<img src='https://github.com/AbstractUmbra/Hondana/actions/workflows/build.yaml/badge.svg' alt='Build status' />
</a>
<a href='https://github.com/AbstractUmbra/Hondana/actions/workflows/coverage_and_lint.yaml'>
<img src='https://github.com/AbstractUmbra/Hondana/actions/workflows/coverage_and_lint.yaml/badge.svg' alt='Linting and Typechecking' />
</a>
</div>
<div align="center">
<a href='https://api.mangadex.org/'>
<img src='https://img.shields.io/website?down_color=red&down_message=offline&label=API%20Status&logo=MangaDex%20API&up_color=lime&up_message=online&url=https%3A%2F%2Fapi.mangadex.org%2Fping' alt='API Status'/>
</a>
<a href='https://hondana.readthedocs.io/en/latest/?badge=latest'>
<img src='https://readthedocs.org/projects/hondana/badge/?version=latest' alt='Documentation Status' />
</a>
<a href="https://discord.gg/aYGYJxwqe5">
<img src='https://img.shields.io/discord/705500489248145459?color=blue&label=Discord&logo=Discord%20Server&logoColor=green' alt='Discord Server'>
</a>
</div>
<h1></h1>
<br>
A lightweight and asynchronous wrapper around the [MangaDex v5 API](https://api.mangadex.org/docs.html).
You can see our stable docs [here](https://hondana.readthedocs.io/en/stable/)!
---------
## Important Notice
The MangaDex team have made great strides in implementing their OAuth2 authentication system, and as such have deprecated standard login flows (email/user and pass -> token).
This means that any accounts created AFTER December 7th 2022 cannot use Hondana currently to authenticate.
This also means for accounts created BEFORE the above date, you will also be unable to authenticate once the methods are fully removed, to which there is no set date at the time of writing this.
I have asked the staff about adding the [Client Credentials](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) OAuth2 workflow as this fits this library wrapper's auth needs, as currently it only supports [Authorization Code](https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/) flows which doesn't really work here, as it is more designed for static apps, not per-user apps.
I have a WIP branch (`feature/oauth2`) that currently attempts to spawn a webserver to handle the Auth Code flow but it is less than ideal and rather fragile.
I will keep this README updated and a project will be added on the GitHub page to mark progress.
--------
## Features
We are currently at 100% feature compliance with the API.
## Notes
### Authenticated endpoints
Sadly (thankfully?) I am not an author on MangaDex, meaning I cannot test the creation endpoints for things like scanlators, artists, authors, manga or chapters.
I have followed the API guidelines to the letter for these, but they may not work.
Any help in testing them is greatly appreciated.
### Upload & Creation
Following the above, I can only use the public test manga for upload testing.
These are currently implemented and tested to the best of my ability.
## Examples
Please take a look at the [examples](./examples/) directory for working examples.
**NOTE**: More examples will follow as the library is developed.
### Current caveats to note
- There are no API endpoints for Artist. It seems they are not differentiated from Author types except in name only.
- I have separated them logically, but under the hood all Artists are Authors and their `__eq__` reports as such.
- The tags and report reasons are locally cached since you **must** pass UUIDs to the api (and I do not think you're going to memorize those), there's a convenience method for updating the local cache as `Client.update_tags` and `Client.update_report_reasons` respectively.
- I have added [an example](./examples/updating_local_tags.py) on how to do the above for tags.
- To use these tags, you can see an example [here](./examples/search_manga.py#L17-L22).
- [Settings related endpoints](https://api.mangadex.org/docs.html#operation/get-settings-template) are not currently exposed. I have implemented their documented use, but I do not expect them to currently function.
- Once this is exposed fully I will implement a richer interface.
- Currently, if there are any errors in a chapter upload process, the error key does not contain filenames or identifiable information on exactly what file failed upload.
- This means that I locally compare the succeeded files with the ones missing from the full response payload. The examples have been updated with how to check for an error.
- Currently, the `Client.my_chapter_read_history` method will not work. It is disabled on MD's side due to an issue they had previously. If/when it is re-introduced the method will remain the same.
### Further information/tidbits
- For a bit more clarity on a Chapter's `readableAt` vs `publishAt`, see [this page](https://api.mangadex.org/docs/dates/#readableat) on the MangaDex docs.
- A query with the `include_future_updates` bool set to `True` will include chapters that are pending release by scanlation groups on MangaDex, but which may be available on their sites.
### Contributing
If you would like to contribute to Hondana, please take a look at [the contributing guidelines](./.github/CONTRIBUTING.md) and follow the procedure there.
If you have any question please feel free to join my Discord server:
<div align="left">
<a href="https://discord.gg/aYGYJxwqe5">
<img src="https://discordapp.com/api/guilds/705500489248145459/widget.png?style=banner2" alt="Discord Server"/>
</a>
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/AbstractUmbra/hondana",
"name": "hondana",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "mangadex,manga,api,wrapper",
"author": "Alex N\u00f8rgaard",
"author_email": "Umbra@AbstractUmbra.dev",
"download_url": "",
"platform": null,
"description": "<div align=\"center\">\n <h1><a href=\"https://jisho.org/word/%E6%9C%AC%E6%A3%9A\">Hondana \u300e\u672c\u68da\u300f</a></h1>\n <a href='https://github.com/AbstractUmbra/Hondana/actions/workflows/build.yaml'>\n <img src='https://github.com/AbstractUmbra/Hondana/actions/workflows/build.yaml/badge.svg' alt='Build status' />\n </a>\n <a href='https://github.com/AbstractUmbra/Hondana/actions/workflows/coverage_and_lint.yaml'>\n <img src='https://github.com/AbstractUmbra/Hondana/actions/workflows/coverage_and_lint.yaml/badge.svg' alt='Linting and Typechecking' />\n </a>\n</div>\n<div align=\"center\">\n <a href='https://api.mangadex.org/'>\n <img src='https://img.shields.io/website?down_color=red&down_message=offline&label=API%20Status&logo=MangaDex%20API&up_color=lime&up_message=online&url=https%3A%2F%2Fapi.mangadex.org%2Fping' alt='API Status'/>\n </a>\n <a href='https://hondana.readthedocs.io/en/latest/?badge=latest'>\n <img src='https://readthedocs.org/projects/hondana/badge/?version=latest' alt='Documentation Status' />\n </a>\n <a href=\"https://discord.gg/aYGYJxwqe5\">\n <img src='https://img.shields.io/discord/705500489248145459?color=blue&label=Discord&logo=Discord%20Server&logoColor=green' alt='Discord Server'>\n </a>\n</div>\n<h1></h1>\n<br>\n\nA lightweight and asynchronous wrapper around the [MangaDex v5 API](https://api.mangadex.org/docs.html).\nYou can see our stable docs [here](https://hondana.readthedocs.io/en/stable/)!\n\n---------\n## Important Notice\n\nThe MangaDex team have made great strides in implementing their OAuth2 authentication system, and as such have deprecated standard login flows (email/user and pass -> token).\nThis means that any accounts created AFTER December 7th 2022 cannot use Hondana currently to authenticate.\nThis also means for accounts created BEFORE the above date, you will also be unable to authenticate once the methods are fully removed, to which there is no set date at the time of writing this.\n\nI have asked the staff about adding the [Client Credentials](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) OAuth2 workflow as this fits this library wrapper's auth needs, as currently it only supports [Authorization Code](https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/) flows which doesn't really work here, as it is more designed for static apps, not per-user apps.\nI have a WIP branch (`feature/oauth2`) that currently attempts to spawn a webserver to handle the Auth Code flow but it is less than ideal and rather fragile.\nI will keep this README updated and a project will be added on the GitHub page to mark progress.\n\n--------\n\n## Features\nWe are currently at 100% feature compliance with the API.\n\n## Notes\n### Authenticated endpoints\n\nSadly (thankfully?) I am not an author on MangaDex, meaning I cannot test the creation endpoints for things like scanlators, artists, authors, manga or chapters.\nI have followed the API guidelines to the letter for these, but they may not work.\n\nAny help in testing them is greatly appreciated.\n\n### Upload & Creation\nFollowing the above, I can only use the public test manga for upload testing.\nThese are currently implemented and tested to the best of my ability.\n\n## Examples\nPlease take a look at the [examples](./examples/) directory for working examples.\n\n**NOTE**: More examples will follow as the library is developed.\n\n\n### Current caveats to note\n- There are no API endpoints for Artist. It seems they are not differentiated from Author types except in name only.\n - I have separated them logically, but under the hood all Artists are Authors and their `__eq__` reports as such.\n- The tags and report reasons are locally cached since you **must** pass UUIDs to the api (and I do not think you're going to memorize those), there's a convenience method for updating the local cache as `Client.update_tags` and `Client.update_report_reasons` respectively.\n - I have added [an example](./examples/updating_local_tags.py) on how to do the above for tags.\n - To use these tags, you can see an example [here](./examples/search_manga.py#L17-L22).\n- [Settings related endpoints](https://api.mangadex.org/docs.html#operation/get-settings-template) are not currently exposed. I have implemented their documented use, but I do not expect them to currently function.\n - Once this is exposed fully I will implement a richer interface.\n- Currently, if there are any errors in a chapter upload process, the error key does not contain filenames or identifiable information on exactly what file failed upload.\n - This means that I locally compare the succeeded files with the ones missing from the full response payload. The examples have been updated with how to check for an error.\n- Currently, the `Client.my_chapter_read_history` method will not work. It is disabled on MD's side due to an issue they had previously. If/when it is re-introduced the method will remain the same.\n\n### Further information/tidbits\n- For a bit more clarity on a Chapter's `readableAt` vs `publishAt`, see [this page](https://api.mangadex.org/docs/dates/#readableat) on the MangaDex docs.\n- A query with the `include_future_updates` bool set to `True` will include chapters that are pending release by scanlation groups on MangaDex, but which may be available on their sites.\n\n### Contributing\nIf you would like to contribute to Hondana, please take a look at [the contributing guidelines](./.github/CONTRIBUTING.md) and follow the procedure there.\n\n\nIf you have any question please feel free to join my Discord server:\n<div align=\"left\">\n <a href=\"https://discord.gg/aYGYJxwqe5\">\n <img src=\"https://discordapp.com/api/guilds/705500489248145459/widget.png?style=banner2\" alt=\"Discord Server\"/>\n </a>\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An asynchronous wrapper around the MangaDex v5 API",
"version": "3.4.7",
"split_keywords": [
"mangadex",
"manga",
"api",
"wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f1624b7b13e15a09749dae1898b194372cc38d24629c85c35c0f71c76cee376f",
"md5": "d921b00c618435e7288675722c283547",
"sha256": "082f678d7f7072efc20f9d25adb36fe053853edb9666f911f76fd384774ec5a3"
},
"downloads": -1,
"filename": "hondana-3.4.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d921b00c618435e7288675722c283547",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 139967,
"upload_time": "2023-01-08T05:23:18",
"upload_time_iso_8601": "2023-01-08T05:23:18.505605Z",
"url": "https://files.pythonhosted.org/packages/f1/62/4b7b13e15a09749dae1898b194372cc38d24629c85c35c0f71c76cee376f/hondana-3.4.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-08 05:23:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "AbstractUmbra",
"github_project": "hondana",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hondana"
}
JSON
