# Hydrus API
Python module implementing the Hydrus API.
# Requirements
- Python >= 3.9 (I think; Let me know if you can use this with an older Python version)
- requests library (`pip install requests`)
# Installation
`$ pip install hydrus-api`
If you want to use the package in your own (installable) Python project, specify it in your `setup.py` using:
`install_requires=['hydrus-api']`.
# Contributing
Please feel free to contribute in the form of a pull request when the API changes (keep close to the existing code style
or you'll create more work than help); I've been bad about merging these until now, I'll try to be more conscientious of
them.
Try to avoid checking in your modifications to `.vscode/settings.json` and `.env` please.
I can't guarantee any fixed timespan in which I'll update this module myself when the API changes -- the only reason it
was updated now is because prkc kept bugging me; So if you desperately need this module to be updated, please create a
pull request.
# Description
Read the (latest) official documentation [here](https://hydrusnetwork.github.io/hydrus/help/client_api.html).
When instantiating `hydrus_api.Client` the `acccess_key` is optional, allowing you to initially manually request
permissions using `request_new_permissions()`. Alternatively there is `hydrus_api.utils.request_api_key()` to make this
easier. You can instantiate a new `Client` with the returned access key after that.
If the API version the module is developed against and the API version of the Hydrus client differ, there is a chance
that using this API module might have unintended consequences -- be careful.
If something with the API goes wrong, a subclass of `APIError` (`MissingParameter`, `InsufficientAccess`,
`DatabaseLocked`, `ServerError`) or `APIError` itself will be raised with the
[`requests.Response`](http://docs.python-requests.org/en/master/api/#requests.Response) object that caused the error.
`APIError` will only be raised directly, if the returned status code is unrecognized.
The module provides `Permission`, `URLType`, `ImportStatus`, `TagAction`, `TagStatus`, `PageType`, `PageState`,
`FileSortType`, `ServiceType`, `NoteConflictResolution` and `DuplicateStatus` Enums for your convenience. Due to a
limitation of JSON, all dictionary keys that are returned by the client will be strings, so when using Enum members to
index a dictionary that was returned by the client, make sure to use the string representation of its value. Usually you
would have to do this: `str(Enum.member.value)`, but the listed Enums allow you to just do `str(Enum.member)` instead to
get the string representation of the member's value directly.
The module provides convenience functions in `hydrus_api.utils` that are not strictly part of the API, e.g.
`add_and_tag_files()` and `get_page_list()`; read their docstrings to figure out what they do.
The client methods `add_file()` and `add_and_tag_files()` accept `str`, `pathlib.Path` and objects that implement the
internal `BinaryFileLike` protocol (i.e. all objects that provide a `read()`-method that returns `bytes`).
The function `hydrus_api.utils.parse_hydrus_metadata_file` behaves similarly, except that it accepts objects that
implement the internal `TextFileLike` protocol (i.e. its `read()`-method returns a string).
Check out `examples/` for some example applications. Some of them might be outdated, but they should be good enough to
give you an idea how to use the module.
# Changes with v5.0.0
To avoid confusion, starting with v5.0.0, responses will be returned unmodified from the API, exactly like described in
the official documentation. The previous functionality of automatically indexing a single top-level key has been
removed.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/cryzed/hydrus-api",
"name": "hydrus-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "hydrus,api",
"author": "cryzed",
"author_email": "cryzed@googlemail.com",
"download_url": "https://files.pythonhosted.org/packages/35/49/42e4d5478bdd5770227b57d7abf9538e91ca17af61c7542c0da3abb3f455/hydrus_api-5.0.1.tar.gz",
"platform": null,
"description": "# Hydrus API\nPython module implementing the Hydrus API.\n\n# Requirements\n- Python >= 3.9 (I think; Let me know if you can use this with an older Python version)\n- requests library (`pip install requests`)\n\n# Installation\n`$ pip install hydrus-api`\n\nIf you want to use the package in your own (installable) Python project, specify it in your `setup.py` using:\n`install_requires=['hydrus-api']`.\n\n# Contributing\nPlease feel free to contribute in the form of a pull request when the API changes (keep close to the existing code style\nor you'll create more work than help); I've been bad about merging these until now, I'll try to be more conscientious of\nthem.\n\nTry to avoid checking in your modifications to `.vscode/settings.json` and `.env` please.\n\nI can't guarantee any fixed timespan in which I'll update this module myself when the API changes -- the only reason it\nwas updated now is because prkc kept bugging me; So if you desperately need this module to be updated, please create a\npull request.\n\n# Description\nRead the (latest) official documentation [here](https://hydrusnetwork.github.io/hydrus/help/client_api.html).\n\nWhen instantiating `hydrus_api.Client` the `acccess_key` is optional, allowing you to initially manually request\npermissions using `request_new_permissions()`. Alternatively there is `hydrus_api.utils.request_api_key()` to make this\neasier. You can instantiate a new `Client` with the returned access key after that.\n\nIf the API version the module is developed against and the API version of the Hydrus client differ, there is a chance\nthat using this API module might have unintended consequences -- be careful.\n\nIf something with the API goes wrong, a subclass of `APIError` (`MissingParameter`, `InsufficientAccess`,\n`DatabaseLocked`, `ServerError`) or `APIError` itself will be raised with the\n[`requests.Response`](http://docs.python-requests.org/en/master/api/#requests.Response) object that caused the error.\n`APIError` will only be raised directly, if the returned status code is unrecognized.\n\nThe module provides `Permission`, `URLType`, `ImportStatus`, `TagAction`, `TagStatus`, `PageType`, `PageState`,\n`FileSortType`, `ServiceType`, `NoteConflictResolution` and `DuplicateStatus` Enums for your convenience. Due to a\nlimitation of JSON, all dictionary keys that are returned by the client will be strings, so when using Enum members to\nindex a dictionary that was returned by the client, make sure to use the string representation of its value. Usually you\nwould have to do this: `str(Enum.member.value)`, but the listed Enums allow you to just do `str(Enum.member)` instead to\nget the string representation of the member's value directly.\n\nThe module provides convenience functions in `hydrus_api.utils` that are not strictly part of the API, e.g.\n`add_and_tag_files()` and `get_page_list()`; read their docstrings to figure out what they do.\n\nThe client methods `add_file()` and `add_and_tag_files()` accept `str`, `pathlib.Path` and objects that implement the\ninternal `BinaryFileLike` protocol (i.e. all objects that provide a `read()`-method that returns `bytes`).\n\nThe function `hydrus_api.utils.parse_hydrus_metadata_file` behaves similarly, except that it accepts objects that\nimplement the internal `TextFileLike` protocol (i.e. its `read()`-method returns a string).\n\nCheck out `examples/` for some example applications. Some of them might be outdated, but they should be good enough to\ngive you an idea how to use the module.\n\n# Changes with v5.0.0\nTo avoid confusion, starting with v5.0.0, responses will be returned unmodified from the API, exactly like described in\nthe official documentation. The previous functionality of automatically indexing a single top-level key has been\nremoved.\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Python module implementing the Hydrus API",
"version": "5.0.1",
"project_urls": {
"Homepage": "https://gitlab.com/cryzed/hydrus-api",
"Repository": "https://gitlab.com/cryzed/hydrus-api"
},
"split_keywords": [
"hydrus",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "849ebd1b3ef70aa1ecf9276ebacfc904d1a6b70899951baa3379ea7a49c006b9",
"md5": "76b545a61ae22b40596992479c20bdc2",
"sha256": "711b4b23e49c562be26ca0720a911aae4d77a24fad7fd88449098ade7558676b"
},
"downloads": -1,
"filename": "hydrus_api-5.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "76b545a61ae22b40596992479c20bdc2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 35025,
"upload_time": "2023-07-05T19:47:28",
"upload_time_iso_8601": "2023-07-05T19:47:28.285263Z",
"url": "https://files.pythonhosted.org/packages/84/9e/bd1b3ef70aa1ecf9276ebacfc904d1a6b70899951baa3379ea7a49c006b9/hydrus_api-5.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "354942e4d5478bdd5770227b57d7abf9538e91ca17af61c7542c0da3abb3f455",
"md5": "fea287973cae1ca703c64303bac1febb",
"sha256": "dd1a1e69bf7fc28185fda6589bd9dbaab73260df02280d64eba713471c7a8cce"
},
"downloads": -1,
"filename": "hydrus_api-5.0.1.tar.gz",
"has_sig": false,
"md5_digest": "fea287973cae1ca703c64303bac1febb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 23580,
"upload_time": "2023-07-05T19:47:29",
"upload_time_iso_8601": "2023-07-05T19:47:29.842969Z",
"url": "https://files.pythonhosted.org/packages/35/49/42e4d5478bdd5770227b57d7abf9538e91ca17af61c7542c0da3abb3f455/hydrus_api-5.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-05 19:47:29",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "cryzed",
"gitlab_project": "hydrus-api",
"lcname": "hydrus-api"
}
JSON