# 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": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "hydrus, api",
"author": "cryzed",
"author_email": "cryzed@googlemail.com",
"download_url": "https://files.pythonhosted.org/packages/d9/79/b888c8f7649b4890bbefc7933ec9c2a0d21624e5aca8a44d8fb587c3454c/hydrus_api-5.1.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.1.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": "f16e34f4a2cf28ee5bec42a039000113afd10524d264fb5e44a84c83a481fe33",
"md5": "5e5c77e89d588b087049e5069f2aa993",
"sha256": "2317d9cd5f1e0814127ba7b657426dac5214beeb3be6f9b9b95de3532eb47283"
},
"downloads": -1,
"filename": "hydrus_api-5.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e5c77e89d588b087049e5069f2aa993",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 37214,
"upload_time": "2024-09-28T13:45:48",
"upload_time_iso_8601": "2024-09-28T13:45:48.360736Z",
"url": "https://files.pythonhosted.org/packages/f1/6e/34f4a2cf28ee5bec42a039000113afd10524d264fb5e44a84c83a481fe33/hydrus_api-5.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d979b888c8f7649b4890bbefc7933ec9c2a0d21624e5aca8a44d8fb587c3454c",
"md5": "de389c98dda84b33a901a5b8649fc1d1",
"sha256": "a00dc36dd5fe31166222708a5eeac174a954150e23794fa31ebf4dc4c1074262"
},
"downloads": -1,
"filename": "hydrus_api-5.1.1.tar.gz",
"has_sig": false,
"md5_digest": "de389c98dda84b33a901a5b8649fc1d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 25911,
"upload_time": "2024-09-28T13:45:50",
"upload_time_iso_8601": "2024-09-28T13:45:50.320259Z",
"url": "https://files.pythonhosted.org/packages/d9/79/b888c8f7649b4890bbefc7933ec9c2a0d21624e5aca8a44d8fb587c3454c/hydrus_api-5.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-28 13:45:50",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "cryzed",
"gitlab_project": "hydrus-api",
"lcname": "hydrus-api"
}
JSON