# Hakai Api Python Client
This project exports a single Python class that can be used to make HTTP requests to the
Hakai API resource server.
The exported `Client` class extends the functionality of the
Python [requests library](https://docs.python-requests.org/en/master/) to supply Hakai
OAuth2 credentials with url requests.
 [](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml) [](https://opensource.org/licenses/MIT)
<details>
<summary>Table of Contents</summary>
[Installation](#installation)
[Quickstart](#quickstart)
[Methods](#methods)
[API endpoints](#api-endpoints)
[Advanced usage](#advanced-usage)
[Contributing](#contributing)
</details>
# Installation
Python 3.8 or higher is required. Install with pip:
```bash
pip install hakai-api
```
# Quickstart
```python
from hakai_api import Client
# Get the api request client
client = Client() # Follow stdout prompts to get an API token
# Make a data request for chlorophyll data
url = '%s/%s' % (client.api_root, 'eims/views/output/chlorophyll?limit=50')
response = client.get(url)
print(url) # https://hecate.hakai.org/api/eims/views/output/chlorophyll...
print(response.json())
# [{'action': '', 'event_pk': 7064, 'rn': '1', 'date': '2012-05-17', 'work_area': 'CALVERT'...
```
# Methods
This library exports a single client name `Client`. Instantiating this class produces
a `requests.Session` client from the Python requests library. The Hakai API Python
Client inherits directly from `requests.Session` thus all methods available on that
parent class are available. For details see
the [requests documentation](http://docs.python-requests.org/).
The hakai_api `Client` class also contains a property `api_root` which is useful for
constructing urls to access data from the API. The
above [Quickstart example](#quickstart) demonstrates using this property to construct a
url to access project names.
# API endpoints
For details about the API, including available endpoints where data can be requested
from, see the [Hakai API documentation](https://github.com/HakaiInstitute/hakai-api).
# Advanced usage
You can specify which API to access when instantiating the Client. By default, the API
uses `https://hecate.hakai.org/api` as the API root. It may be useful to use this
library to access a locally running API instance or to access the Goose API for testing
purposes. If you are always going to be accessing data from a locally running API
instance, you are better off using the requests.py library directly since Authorization
is not required for local requests.
```python
from hakai_api import Client
# Get a client for a locally running API instance
client = Client("http://localhost:8666")
print(client.api_root) # http://localhost:8666
```
You can also pass in the credentials string retrieved from the hakai API login page
while initiating the Client class.
```python
from hakai_api import Client
# Pass a credentials token as the Client Class is initiated
client = Client(credentials="CREDENTIAL_TOKEN")
```
Finally, you can set credentials for the client class using the `HAKAI_API_CREDENTIALS`
environment variable. This is useful for e.g. setting credentials in a docker container.
The value of the environment variable should be the credentials token retrieved from the
Hakai API login page.
# Contributing
See [CONTRIBUTING](CONTRIBUTING.md)
# License
See [LICENSE](LICENSE.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/HakaiInstitute/hakai-api-client-py",
"name": "hakai-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "",
"author": "Taylor Denouden",
"author_email": "taylor.denouden@hakai.org",
"download_url": "https://files.pythonhosted.org/packages/fe/c3/31da5940a600a569c88d58b98455c10eaf47a4f499cd7769dc8f56862dfd/hakai_api-1.5.1.tar.gz",
"platform": null,
"description": "# Hakai Api Python Client\n\nThis project exports a single Python class that can be used to make HTTP requests to the\nHakai API resource server.\nThe exported `Client` class extends the functionality of the\nPython [requests library](https://docs.python-requests.org/en/master/) to supply Hakai\nOAuth2 credentials with url requests.\n\n [](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml) [](https://opensource.org/licenses/MIT)\n\n<details>\n\n<summary>Table of Contents</summary>\n\n[Installation](#installation)\n\n[Quickstart](#quickstart)\n\n[Methods](#methods)\n\n[API endpoints](#api-endpoints)\n\n[Advanced usage](#advanced-usage)\n\n[Contributing](#contributing)\n\n</details>\n\n# Installation\n\nPython 3.8 or higher is required. Install with pip:\n\n```bash\npip install hakai-api\n```\n\n# Quickstart\n\n```python\nfrom hakai_api import Client\n\n# Get the api request client\nclient = Client() # Follow stdout prompts to get an API token\n\n# Make a data request for chlorophyll data\nurl = '%s/%s' % (client.api_root, 'eims/views/output/chlorophyll?limit=50')\nresponse = client.get(url)\n\nprint(url) # https://hecate.hakai.org/api/eims/views/output/chlorophyll...\nprint(response.json())\n# [{'action': '', 'event_pk': 7064, 'rn': '1', 'date': '2012-05-17', 'work_area': 'CALVERT'...\n```\n\n# Methods\n\nThis library exports a single client name `Client`. Instantiating this class produces\na `requests.Session` client from the Python requests library. The Hakai API Python\nClient inherits directly from `requests.Session` thus all methods available on that\nparent class are available. For details see\nthe [requests documentation](http://docs.python-requests.org/).\n\nThe hakai_api `Client` class also contains a property `api_root` which is useful for\nconstructing urls to access data from the API. The\nabove [Quickstart example](#quickstart) demonstrates using this property to construct a\nurl to access project names.\n\n# API endpoints\n\nFor details about the API, including available endpoints where data can be requested\nfrom, see the [Hakai API documentation](https://github.com/HakaiInstitute/hakai-api).\n\n# Advanced usage\n\nYou can specify which API to access when instantiating the Client. By default, the API\nuses `https://hecate.hakai.org/api` as the API root. It may be useful to use this\nlibrary to access a locally running API instance or to access the Goose API for testing\npurposes. If you are always going to be accessing data from a locally running API\ninstance, you are better off using the requests.py library directly since Authorization\nis not required for local requests.\n\n```python\nfrom hakai_api import Client\n\n# Get a client for a locally running API instance\nclient = Client(\"http://localhost:8666\")\nprint(client.api_root) # http://localhost:8666\n```\n\nYou can also pass in the credentials string retrieved from the hakai API login page\nwhile initiating the Client class.\n\n```python\nfrom hakai_api import Client\n\n# Pass a credentials token as the Client Class is initiated\nclient = Client(credentials=\"CREDENTIAL_TOKEN\")\n```\n\nFinally, you can set credentials for the client class using the `HAKAI_API_CREDENTIALS`\nenvironment variable. This is useful for e.g. setting credentials in a docker container.\nThe value of the environment variable should be the credentials token retrieved from the\nHakai API login page.\n\n# Contributing\n\nSee [CONTRIBUTING](CONTRIBUTING.md)\n\n# License\n\nSee [LICENSE](LICENSE.md)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Get Hakai database resources using http calls",
"version": "1.5.1",
"project_urls": {
"Homepage": "https://github.com/HakaiInstitute/hakai-api-client-py",
"Repository": "https://github.com/HakaiInstitute/hakai-api-client-py"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3def1a26921bd2d2c5d31f1988365c8f439444191f5526c9893f1c0c43fb65d1",
"md5": "9ea3f19d57cd8a85e56e7d2c6048f144",
"sha256": "1244a8fc03fd69385204b3008e2f2eccf77c2b61d83d69fb7934684ef7d85956"
},
"downloads": -1,
"filename": "hakai_api-1.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ea3f19d57cd8a85e56e7d2c6048f144",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 5456,
"upload_time": "2023-08-16T19:57:37",
"upload_time_iso_8601": "2023-08-16T19:57:37.872872Z",
"url": "https://files.pythonhosted.org/packages/3d/ef/1a26921bd2d2c5d31f1988365c8f439444191f5526c9893f1c0c43fb65d1/hakai_api-1.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fec331da5940a600a569c88d58b98455c10eaf47a4f499cd7769dc8f56862dfd",
"md5": "d47c0e1e75bdfc24c07b1ed8d5e1d059",
"sha256": "e0992c99107e63ca386034122c90f471e397f9c9094313b37cabc6aa216f29fd"
},
"downloads": -1,
"filename": "hakai_api-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "d47c0e1e75bdfc24c07b1ed8d5e1d059",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 5508,
"upload_time": "2023-08-16T19:57:40",
"upload_time_iso_8601": "2023-08-16T19:57:40.270466Z",
"url": "https://files.pythonhosted.org/packages/fe/c3/31da5940a600a569c88d58b98455c10eaf47a4f499cd7769dc8f56862dfd/hakai_api-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-16 19:57:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HakaiInstitute",
"github_project": "hakai-api-client-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "hakai-api"
}
JSON
