hakai_api 2.0.1__tar.gz → 2.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hakai_api-2.1.0/.github/workflows/lint.yaml +27 -0
- hakai_api-2.1.0/.github/workflows/release.yaml +83 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/.github/workflows/test.yaml +12 -5
- hakai_api-2.1.0/.github/workflows/zizmor.yaml +31 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/.pre-commit-config.yaml +7 -3
- hakai_api-2.1.0/.readthedocs.yaml +16 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/CONTRIBUTING.md +35 -8
- hakai_api-2.1.0/PKG-INFO +62 -0
- hakai_api-2.1.0/README.md +46 -0
- hakai_api-2.1.0/docs/contributing.md +1 -0
- hakai_api-2.1.0/docs/guides/authentication.md +111 -0
- hakai_api-2.1.0/docs/guides/configuration.md +79 -0
- hakai_api-2.1.0/docs/index.md +51 -0
- hakai_api-2.1.0/docs/reference.md +38 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/pyproject.toml +11 -7
- {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/__init__.py +7 -4
- {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/base.py +62 -5
- {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/desktop.py +3 -13
- {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/web.py +3 -14
- {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/client.py +52 -14
- {hakai_api-2.0.1 → hakai_api-2.1.0}/tests/test_auth_strategies.py +8 -7
- {hakai_api-2.0.1 → hakai_api-2.1.0}/tests/test_client.py +170 -19
- hakai_api-2.1.0/uv.lock +908 -0
- hakai_api-2.1.0/zensical.toml +80 -0
- hakai_api-2.0.1/.github/workflows/lint.yaml +0 -21
- hakai_api-2.0.1/.github/workflows/release.yaml +0 -54
- hakai_api-2.0.1/PKG-INFO +0 -203
- hakai_api-2.0.1/README.md +0 -187
- hakai_api-2.0.1/uv.lock +0 -758
- {hakai_api-2.0.1 → hakai_api-2.1.0}/.gitignore +0 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/CODEOWNERS +0 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/LICENSE +0 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/example.py +0 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/__init__.py +0 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/desktop_callback.html +0 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/tests/__init__.py +0 -0
- {hakai_api-2.0.1 → hakai_api-2.1.0}/tests/test_backwards_compatability.py +0 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
name: lint
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
branches:
|
|
5
|
+
- main
|
|
6
|
+
pull_request:
|
|
7
|
+
branches:
|
|
8
|
+
- main
|
|
9
|
+
workflow_dispatch:
|
|
10
|
+
|
|
11
|
+
permissions: {}
|
|
12
|
+
|
|
13
|
+
jobs:
|
|
14
|
+
ruff:
|
|
15
|
+
name: ruff
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
permissions:
|
|
18
|
+
contents: read
|
|
19
|
+
concurrency:
|
|
20
|
+
group: ${{ github.workflow }}-${{ github.ref }}-ruff
|
|
21
|
+
cancel-in-progress: true
|
|
22
|
+
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
25
|
+
with:
|
|
26
|
+
persist-credentials: false
|
|
27
|
+
- uses: astral-sh/ruff-action@278981a28ce3188b1e39527901f38254bf3aac89 # v4.1.0
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
name: 'PyPI Publish 🐍'
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches-ignore:
|
|
6
|
+
- '**'
|
|
7
|
+
tags:
|
|
8
|
+
- 'v[0-9]+.[0-9]+.[0-9]+'
|
|
9
|
+
- 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
|
|
10
|
+
paths-ignore:
|
|
11
|
+
- 'README.md'
|
|
12
|
+
|
|
13
|
+
permissions: {}
|
|
14
|
+
|
|
15
|
+
concurrency:
|
|
16
|
+
group: ${{ github.workflow }}-${{ github.ref }}
|
|
17
|
+
cancel-in-progress: false
|
|
18
|
+
|
|
19
|
+
jobs:
|
|
20
|
+
build:
|
|
21
|
+
name: build and test
|
|
22
|
+
runs-on: ubuntu-latest
|
|
23
|
+
permissions:
|
|
24
|
+
contents: read
|
|
25
|
+
steps:
|
|
26
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
27
|
+
with:
|
|
28
|
+
persist-credentials: false
|
|
29
|
+
|
|
30
|
+
- name: Install uv
|
|
31
|
+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
|
|
32
|
+
with:
|
|
33
|
+
# Never use a cache when building release artifacts (cache poisoning).
|
|
34
|
+
enable-cache: false
|
|
35
|
+
|
|
36
|
+
- name: "Set up Python"
|
|
37
|
+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
38
|
+
with:
|
|
39
|
+
python-version: "3.x"
|
|
40
|
+
|
|
41
|
+
- name: "Set version"
|
|
42
|
+
run: |
|
|
43
|
+
uv version "${GITHUB_REF_NAME#v}"
|
|
44
|
+
uv lock
|
|
45
|
+
|
|
46
|
+
- name: Install the project
|
|
47
|
+
run: uv sync --locked --all-extras --dev
|
|
48
|
+
|
|
49
|
+
- name: Run tests
|
|
50
|
+
run: uv run pytest tests
|
|
51
|
+
|
|
52
|
+
- name: Build the project
|
|
53
|
+
run: uv build
|
|
54
|
+
|
|
55
|
+
- name: Upload distributions
|
|
56
|
+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
57
|
+
with:
|
|
58
|
+
name: dist
|
|
59
|
+
path: dist/
|
|
60
|
+
|
|
61
|
+
# Publishing runs in its own job so the OIDC token is never exposed to the
|
|
62
|
+
# build and test steps.
|
|
63
|
+
publish:
|
|
64
|
+
name: upload release to PyPI
|
|
65
|
+
needs: build
|
|
66
|
+
runs-on: ubuntu-latest
|
|
67
|
+
environment: pypi
|
|
68
|
+
permissions:
|
|
69
|
+
id-token: write # OIDC token for PyPI trusted publishing
|
|
70
|
+
steps:
|
|
71
|
+
- name: Install uv
|
|
72
|
+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
|
|
73
|
+
with:
|
|
74
|
+
enable-cache: false
|
|
75
|
+
|
|
76
|
+
- name: Download distributions
|
|
77
|
+
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
|
78
|
+
with:
|
|
79
|
+
name: dist
|
|
80
|
+
path: dist/
|
|
81
|
+
|
|
82
|
+
- name: Publish to PyPI
|
|
83
|
+
run: uv publish --trusted-publishing always
|
|
@@ -8,10 +8,14 @@ on:
|
|
|
8
8
|
- main
|
|
9
9
|
workflow_dispatch:
|
|
10
10
|
|
|
11
|
+
permissions: {}
|
|
12
|
+
|
|
11
13
|
jobs:
|
|
12
14
|
Tests:
|
|
13
15
|
name: test ${{ matrix.py }} - ${{ matrix.os }}
|
|
14
16
|
runs-on: ${{ matrix.os }}-latest
|
|
17
|
+
permissions:
|
|
18
|
+
contents: read
|
|
15
19
|
concurrency:
|
|
16
20
|
group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.os }}-${{ matrix.py }}
|
|
17
21
|
cancel-in-progress: true
|
|
@@ -24,20 +28,23 @@ jobs:
|
|
|
24
28
|
- Windows
|
|
25
29
|
- MacOs
|
|
26
30
|
py:
|
|
31
|
+
- "3.15"
|
|
32
|
+
- "3.14"
|
|
27
33
|
- "3.13"
|
|
28
34
|
- "3.12"
|
|
29
35
|
- "3.11"
|
|
30
|
-
- "3.10"
|
|
31
|
-
- "3.9"
|
|
32
36
|
steps:
|
|
33
|
-
- uses: actions/checkout@
|
|
37
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
38
|
+
with:
|
|
39
|
+
persist-credentials: false
|
|
40
|
+
|
|
34
41
|
- name: Install uv
|
|
35
|
-
uses: astral-sh/setup-uv@
|
|
42
|
+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
|
|
36
43
|
with:
|
|
37
44
|
enable-cache: true
|
|
38
45
|
|
|
39
46
|
- name: "Set up Python"
|
|
40
|
-
uses: actions/setup-python@
|
|
47
|
+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
41
48
|
with:
|
|
42
49
|
python-version: ${{ matrix.py }}
|
|
43
50
|
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
name: zizmor
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
branches:
|
|
5
|
+
- main
|
|
6
|
+
pull_request:
|
|
7
|
+
branches:
|
|
8
|
+
- main
|
|
9
|
+
schedule:
|
|
10
|
+
- cron: '0 14 * * 1' # weekly, to catch new advisories against pinned actions
|
|
11
|
+
workflow_dispatch:
|
|
12
|
+
|
|
13
|
+
permissions: {}
|
|
14
|
+
|
|
15
|
+
concurrency:
|
|
16
|
+
group: ${{ github.workflow }}-${{ github.ref }}
|
|
17
|
+
cancel-in-progress: true
|
|
18
|
+
|
|
19
|
+
jobs:
|
|
20
|
+
zizmor:
|
|
21
|
+
name: zizmor
|
|
22
|
+
runs-on: ubuntu-latest
|
|
23
|
+
permissions:
|
|
24
|
+
contents: read # checkout
|
|
25
|
+
security-events: write # upload SARIF results to the Security tab
|
|
26
|
+
steps:
|
|
27
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
28
|
+
with:
|
|
29
|
+
persist-credentials: false
|
|
30
|
+
- name: Run zizmor
|
|
31
|
+
uses: zizmorcore/zizmor-action@45d7276c9ca790aabd705e31ca99c6185c3e76dd # v0.8.1
|
|
@@ -3,11 +3,11 @@
|
|
|
3
3
|
exclude: ^.*\.lock$
|
|
4
4
|
repos:
|
|
5
5
|
- repo: https://github.com/asottile/pyupgrade
|
|
6
|
-
rev: v3.
|
|
6
|
+
rev: v3.22.0
|
|
7
7
|
hooks:
|
|
8
8
|
- id: pyupgrade
|
|
9
9
|
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
10
|
-
rev:
|
|
10
|
+
rev: v6.0.0
|
|
11
11
|
hooks:
|
|
12
12
|
- id: check-added-large-files
|
|
13
13
|
- id: check-ast
|
|
@@ -17,8 +17,12 @@ repos:
|
|
|
17
17
|
- id: trailing-whitespace
|
|
18
18
|
- id: end-of-file-fixer
|
|
19
19
|
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
20
|
-
rev: v0.
|
|
20
|
+
rev: v0.17.6
|
|
21
21
|
hooks:
|
|
22
22
|
- id: ruff-check
|
|
23
23
|
args: [ --fix ]
|
|
24
24
|
- id: ruff-format
|
|
25
|
+
- repo: https://github.com/zizmorcore/zizmor-pre-commit
|
|
26
|
+
rev: v1.32.0
|
|
27
|
+
hooks:
|
|
28
|
+
- id: zizmor
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
version: 2
|
|
2
|
+
|
|
3
|
+
build:
|
|
4
|
+
os: "ubuntu-24.04"
|
|
5
|
+
tools:
|
|
6
|
+
python: "3.13"
|
|
7
|
+
jobs:
|
|
8
|
+
install:
|
|
9
|
+
- pip install uv
|
|
10
|
+
- UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen --no-dev --group docs
|
|
11
|
+
build:
|
|
12
|
+
html:
|
|
13
|
+
- zensical build --strict
|
|
14
|
+
post_build:
|
|
15
|
+
- mkdir -p $READTHEDOCS_OUTPUT/html/
|
|
16
|
+
- cp --recursive site/* $READTHEDOCS_OUTPUT/html/
|
|
@@ -17,6 +17,8 @@ and test the code, and deploy a new version.
|
|
|
17
17
|
- [Linting and Formatting](#linting-and-formatting)
|
|
18
18
|
- [Environment Variables for Testing](#environment-variables-for-testing)
|
|
19
19
|
|
|
20
|
+
[Documentation](#documentation)
|
|
21
|
+
|
|
20
22
|
[Deployment](#deployment)
|
|
21
23
|
|
|
22
24
|
</details>
|
|
@@ -24,7 +26,7 @@ and test the code, and deploy a new version.
|
|
|
24
26
|
## Project structure
|
|
25
27
|
|
|
26
28
|
The business logic for this package is located
|
|
27
|
-
in [`src/hakai_api/client.py`](src/hakai_api/client.py).
|
|
29
|
+
in [`src/hakai_api/client.py`](https://github.com/HakaiInstitute/hakai-api-client-py/blob/main/src/hakai_api/client.py).
|
|
28
30
|
All tests are located in the `tests/` directory.
|
|
29
31
|
|
|
30
32
|
Key components:
|
|
@@ -49,21 +51,22 @@ uv sync
|
|
|
49
51
|
|
|
50
52
|
### Pre-commit
|
|
51
53
|
|
|
52
|
-
This project uses [
|
|
53
|
-
|
|
54
|
-
|
|
54
|
+
This project uses [prek](https://prek.j178.dev/), a fast drop-in replacement for
|
|
55
|
+
[pre-commit](https://pre-commit.com/), to run lint checks before every commit. prek is
|
|
56
|
+
installed as a dev dependency by `uv sync`. To install the git hooks, run the following
|
|
57
|
+
command from the root directory of the repository:
|
|
55
58
|
|
|
56
59
|
```bash
|
|
57
|
-
|
|
60
|
+
uv run prek install
|
|
58
61
|
```
|
|
59
62
|
|
|
60
63
|
This is highly recommended and will prevent failed builds on GitHub Actions, as well as
|
|
61
64
|
ensure consistent code style and quality.
|
|
62
65
|
|
|
63
|
-
You can also run the
|
|
66
|
+
You can also run the hooks manually on all files by running:
|
|
64
67
|
|
|
65
68
|
```bash
|
|
66
|
-
|
|
69
|
+
uv run prek run -a
|
|
67
70
|
```
|
|
68
71
|
|
|
69
72
|
## Tests
|
|
@@ -191,9 +194,33 @@ Some tests may require environment variables:
|
|
|
191
194
|
export HAKAI_API_USER_AGENT="test-client/1.0"
|
|
192
195
|
|
|
193
196
|
# Optional: Set custom credentials file location
|
|
194
|
-
export
|
|
197
|
+
export HAKAI_API_CREDENTIALS_FILE="/tmp/test-credentials"
|
|
198
|
+
|
|
199
|
+
# Optional: Provide a credentials string instead of logging in
|
|
200
|
+
export HAKAI_API_CREDENTIALS="access_token=...&token_type=Bearer&expires_at=..."
|
|
195
201
|
```
|
|
196
202
|
|
|
203
|
+
## Documentation
|
|
204
|
+
|
|
205
|
+
The docs site is built with [Zensical](https://zensical.org/) from the Markdown files in `docs/`,
|
|
206
|
+
configured in `zensical.toml`. The API reference is generated from docstrings with
|
|
207
|
+
[mkdocstrings](https://mkdocstrings.github.io/), so keep docstrings in Google style.
|
|
208
|
+
|
|
209
|
+
Preview the site locally at http://localhost:8000 with live reload:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
uv run --group docs zensical serve
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Build it the same way Read the Docs does (warnings fail the build):
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
uv run --group docs zensical build --strict
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Read the Docs builds `main`, each release tag, and a preview for each pull request, using
|
|
222
|
+
`.readthedocs.yaml`.
|
|
223
|
+
|
|
197
224
|
## Deployment
|
|
198
225
|
|
|
199
226
|
To build and deploy a new PyPi package version, push a tag matching the
|
hakai_api-2.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: hakai_api
|
|
3
|
+
Version: 2.1.0
|
|
4
|
+
Summary: Get Hakai database resources using http calls
|
|
5
|
+
Author-email: Taylor Denouden <taylor.denouden@hakai.org>, Chris Davis <chris.davis@hakai.org>, Nate Rosenstock <nate.rosenstock@hakai.org>, Sam Albers <sam.albers@hakai.org>
|
|
6
|
+
Maintainer-email: Taylor Denouden <taylor.denouden@hakai.org>, Sam Albers <sam.albers@hakai.org>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Python: >=3.11
|
|
10
|
+
Requires-Dist: loguru>=0.7.3
|
|
11
|
+
Requires-Dist: pkce>=1.0.3
|
|
12
|
+
Requires-Dist: pytz>=2025.2
|
|
13
|
+
Requires-Dist: requests-oauthlib>=2.0.0
|
|
14
|
+
Requires-Dist: requests>=2.32.3
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# Hakai API Python Client
|
|
18
|
+
|
|
19
|
+
This project exports a single Python class that can be used to make HTTP requests to the
|
|
20
|
+
Hakai API resource server.
|
|
21
|
+
The exported `Client` class extends the functionality of the
|
|
22
|
+
Python [requests library](https://docs.python-requests.org/en/master/) to supply Hakai
|
|
23
|
+
OAuth2 credentials with url requests.
|
|
24
|
+
|
|
25
|
+
[](https://pypi.org/project/hakai_api/) [](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml) [](https://opensource.org/licenses/MIT)
|
|
26
|
+
|
|
27
|
+
**Documentation: <https://hakai-api-client-py.readthedocs.io/>**
|
|
28
|
+
|
|
29
|
+
## Installation
|
|
30
|
+
|
|
31
|
+
Python 3.11 or higher is required.
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pip install hakai-api
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Quickstart
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from hakai_api import Client
|
|
41
|
+
|
|
42
|
+
# Get the api request client
|
|
43
|
+
client = Client() # Follow stdout prompts to get an API token
|
|
44
|
+
|
|
45
|
+
# Make a data request for chlorophyll data (using relative endpoint)
|
|
46
|
+
response = client.get("/eims/views/output/chlorophyll?limit=50")
|
|
47
|
+
|
|
48
|
+
print(response.json())
|
|
49
|
+
# [{'action': '', 'event_pk': 7064, 'rn': '1', 'date': '2012-05-17', 'work_area': 'CALVERT'...
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
See the [documentation](https://hakai-api-client-py.readthedocs.io/) for the desktop OAuth flow,
|
|
53
|
+
credential management, user agent configuration, custom API roots, and the full API reference. For
|
|
54
|
+
the available endpoints, see the [Hakai API documentation](https://hakaiinstitute.github.io/hakai-api/).
|
|
55
|
+
|
|
56
|
+
## Contributing
|
|
57
|
+
|
|
58
|
+
See [CONTRIBUTING](CONTRIBUTING.md)
|
|
59
|
+
|
|
60
|
+
## License
|
|
61
|
+
|
|
62
|
+
See [LICENSE](LICENSE.md)
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Hakai API Python Client
|
|
2
|
+
|
|
3
|
+
This project exports a single Python class that can be used to make HTTP requests to the
|
|
4
|
+
Hakai API resource server.
|
|
5
|
+
The exported `Client` class extends the functionality of the
|
|
6
|
+
Python [requests library](https://docs.python-requests.org/en/master/) to supply Hakai
|
|
7
|
+
OAuth2 credentials with url requests.
|
|
8
|
+
|
|
9
|
+
[](https://pypi.org/project/hakai_api/) [](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml) [](https://opensource.org/licenses/MIT)
|
|
10
|
+
|
|
11
|
+
**Documentation: <https://hakai-api-client-py.readthedocs.io/>**
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
Python 3.11 or higher is required.
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install hakai-api
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Quickstart
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
from hakai_api import Client
|
|
25
|
+
|
|
26
|
+
# Get the api request client
|
|
27
|
+
client = Client() # Follow stdout prompts to get an API token
|
|
28
|
+
|
|
29
|
+
# Make a data request for chlorophyll data (using relative endpoint)
|
|
30
|
+
response = client.get("/eims/views/output/chlorophyll?limit=50")
|
|
31
|
+
|
|
32
|
+
print(response.json())
|
|
33
|
+
# [{'action': '', 'event_pk': 7064, 'rn': '1', 'date': '2012-05-17', 'work_area': 'CALVERT'...
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
See the [documentation](https://hakai-api-client-py.readthedocs.io/) for the desktop OAuth flow,
|
|
37
|
+
credential management, user agent configuration, custom API roots, and the full API reference. For
|
|
38
|
+
the available endpoints, see the [Hakai API documentation](https://hakaiinstitute.github.io/hakai-api/).
|
|
39
|
+
|
|
40
|
+
## Contributing
|
|
41
|
+
|
|
42
|
+
See [CONTRIBUTING](CONTRIBUTING.md)
|
|
43
|
+
|
|
44
|
+
## License
|
|
45
|
+
|
|
46
|
+
See [LICENSE](LICENSE.md)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
--8<-- "CONTRIBUTING.md"
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Authentication
|
|
2
|
+
|
|
3
|
+
Every request to the Hakai API needs an OAuth2 access token. `Client` gets one when you create it, caches
|
|
4
|
+
it on disk, and attaches it to every request.
|
|
5
|
+
|
|
6
|
+
## Choosing a flow
|
|
7
|
+
|
|
8
|
+
| | Web flow (default) | Desktop flow |
|
|
9
|
+
|-------------------------------------|---------------------------------------------------------------------|---------------------------------------------------------------------------|
|
|
10
|
+
| How you log in | Open a URL, copy the credentials string, paste it into the terminal | A browser opens; the client receives the token on a local callback server |
|
|
11
|
+
| Needs a browser on the same machine | No | Yes |
|
|
12
|
+
| Refresh tokens | No | Yes, so sessions are extended without logging in again |
|
|
13
|
+
| Good for | SSH sessions, notebooks on remote servers, quick scripts | Desktop apps and scripts run on your own machine |
|
|
14
|
+
|
|
15
|
+
=== "Web flow"
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from hakai_api import Client
|
|
19
|
+
|
|
20
|
+
client = Client() # same as Client(auth_flow="web") or Client.create_web_client()
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Running this prints a link to the [login page](https://portal.hakai.org/api-client-login). Log in there,
|
|
24
|
+
copy the credentials string, and paste it at the prompt.
|
|
25
|
+
|
|
26
|
+
=== "Desktop flow"
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from hakai_api import Client
|
|
30
|
+
|
|
31
|
+
client = Client(auth_flow="desktop") # or Client.create_desktop_client()
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The client opens your browser to log in and waits for the redirect on `http://127.0.0.1:65500/callback`.
|
|
35
|
+
Change the port with `local_port=`, and how long it waits (in seconds) with `callback_timeout=`.
|
|
36
|
+
The client uses the OAuth2 authorization code flow with
|
|
37
|
+
[PKCE](https://oauth.net/2/pkce/).
|
|
38
|
+
|
|
39
|
+
## Where credentials come from
|
|
40
|
+
|
|
41
|
+
When you create a `Client`, it looks for credentials in this order and uses the first valid, unexpired
|
|
42
|
+
set it finds:
|
|
43
|
+
|
|
44
|
+
1. **The `credentials` argument.** Either the credentials string from the login page or a dict with
|
|
45
|
+
`access_token`, `token_type`, and `expires_at` keys.
|
|
46
|
+
2. **The `HAKAI_API_CREDENTIALS` environment variable**, holding a credentials string.
|
|
47
|
+
3. **The credentials file**, `~/.hakai-api-auth` by default.
|
|
48
|
+
4. **An interactive login** using the selected flow.
|
|
49
|
+
|
|
50
|
+
Whichever source it uses, the client then writes the credentials to the credentials file. If none of
|
|
51
|
+
these work, `Client()` raises `ValueError`.
|
|
52
|
+
|
|
53
|
+
### Passing credentials directly
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
from hakai_api import Client
|
|
57
|
+
|
|
58
|
+
client = Client(credentials="access_token=...&token_type=Bearer&expires_at=1767225600")
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Read the string from a secret store or environment variable. Don't commit it.
|
|
62
|
+
|
|
63
|
+
### Using an environment variable
|
|
64
|
+
|
|
65
|
+
For containers and CI jobs that can't log in interactively, put the credentials string from the login
|
|
66
|
+
page in `HAKAI_API_CREDENTIALS`:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
export HAKAI_API_CREDENTIALS="access_token=...&token_type=Bearer&expires_at=1767225600"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
!!! danger "Keep this secret"
|
|
73
|
+
|
|
74
|
+
This string works like a password. Don't commit it to version control. Store it in your CI or container platform's
|
|
75
|
+
secret manager instead.
|
|
76
|
+
|
|
77
|
+
### Changing the credentials file location
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from hakai_api import Client
|
|
81
|
+
|
|
82
|
+
client = Client(credentials_file="/path/to/credentials")
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Or set it with the `HAKAI_API_CREDENTIALS_FILE` environment variable:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
export HAKAI_API_CREDENTIALS_FILE="/path/to/credentials"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The `credentials_file=` argument takes precedence over `HAKAI_API_CREDENTIALS_FILE`, which takes precedence
|
|
92
|
+
over the default `~/.hakai-api-auth`.
|
|
93
|
+
|
|
94
|
+
!!! note "Older versions used `HAKAI_API_CREDENTIALS` for the file path"
|
|
95
|
+
|
|
96
|
+
Setting `HAKAI_API_CREDENTIALS` to a file path still works, but logs a deprecation warning. Use
|
|
97
|
+
`HAKAI_API_CREDENTIALS_FILE` instead.
|
|
98
|
+
|
|
99
|
+
The file holds a live access token, so keep it out of version control and shared directories.
|
|
100
|
+
|
|
101
|
+
## Expiry, refresh, and logging out
|
|
102
|
+
|
|
103
|
+
- **Automatic re-authentication.** If a request gets a `401 Unauthorized` response, the client tries
|
|
104
|
+
to refresh the token (desktop flow only). If that fails, it deletes the cached credentials, runs the
|
|
105
|
+
login flow again, and retries the request once.
|
|
106
|
+
- **Refreshing manually.** `client.refresh_token()` returns `True` if it got a new access token. To
|
|
107
|
+
turn refreshing off, pass `use_refresh=False`.
|
|
108
|
+
- **Checking the cache.** `client.file_credentials_are_valid()` reports whether the credentials file
|
|
109
|
+
exists and hasn't expired.
|
|
110
|
+
- **Logging out.** `client.reset_credentials()` deletes the credentials file, so the next `Client()`
|
|
111
|
+
asks you to log in again.
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
## User agent
|
|
4
|
+
|
|
5
|
+
Set a user agent that identifies your application so the Hakai data team can see who is calling the
|
|
6
|
+
API and contact you if something breaks. A repository URL or email address works well.
|
|
7
|
+
|
|
8
|
+
```python
|
|
9
|
+
from hakai_api import Client
|
|
10
|
+
|
|
11
|
+
client = Client(user_agent="kelp-dashboard/1.2 (https://github.com/HakaiInstitute/kelp-dashboard)")
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
If you don't pass `user_agent=`, the client uses the `HAKAI_API_USER_AGENT` environment variable, and
|
|
15
|
+
falls back to `hakai-api-client-py` if that isn't set:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
export HAKAI_API_USER_AGENT="kelp-dashboard/1.2 (data@example.org)"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Relative and absolute URLs
|
|
22
|
+
|
|
23
|
+
Paths that start with `/` are appended to `client.api_root`. Full URLs are used as they are. These
|
|
24
|
+
two requests are the same:
|
|
25
|
+
|
|
26
|
+
```python
|
|
27
|
+
client.get("/eims/views/output/stations")
|
|
28
|
+
client.get("https://portal.hakai.org/api/eims/views/output/stations")
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Use `params=` for query strings instead of formatting them into the URL yourself:
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
response = client.get(
|
|
35
|
+
"/eims/views/output/chlorophyll",
|
|
36
|
+
params={"limit": 50, "work_area": "CALVERT"},
|
|
37
|
+
)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
For the endpoints and query syntax, see the [Hakai API documentation](https://hakaiinstitute.github.io/hakai-api/).
|
|
41
|
+
|
|
42
|
+
## Using a different API instance
|
|
43
|
+
|
|
44
|
+
The client points at the production API (`https://portal.hakai.org/api`) by default. To use a
|
|
45
|
+
development or local instance, pass `api_root` (and `login_page` if that instance has its own login
|
|
46
|
+
page):
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from hakai_api import Client
|
|
50
|
+
|
|
51
|
+
client = Client(api_root="http://localhost:8666")
|
|
52
|
+
print(client.api_root) # http://localhost:8666
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Credentials are tied to the API instance that issued them. When you switch instances, give each one
|
|
56
|
+
its own `credentials_file` so their cached credentials don't overwrite each other.
|
|
57
|
+
|
|
58
|
+
## Using it like `requests.Session`
|
|
59
|
+
|
|
60
|
+
`Client` subclasses `requests.Session`, so the usual session settings work:
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from requests.adapters import HTTPAdapter, Retry
|
|
64
|
+
|
|
65
|
+
client = Client()
|
|
66
|
+
client.headers["Accept"] = "application/json"
|
|
67
|
+
client.mount("https://", HTTPAdapter(max_retries=Retry(total=3, backoff_factor=0.5)))
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Logging
|
|
71
|
+
|
|
72
|
+
The client logs with [loguru](https://loguru.readthedocs.io/) and doesn't call `disable()` on its
|
|
73
|
+
logger, so its messages go to your loguru handlers. To silence it:
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from loguru import logger
|
|
77
|
+
|
|
78
|
+
logger.disable("hakai_api")
|
|
79
|
+
```
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Hakai API Python Client
|
|
2
|
+
|
|
3
|
+
`hakai-api` is a thin wrapper around [requests](https://requests.readthedocs.io/) for calling the
|
|
4
|
+
[Hakai API](https://hakaiinstitute.github.io/hakai-api/). Its `Client` is a `requests.Session` that
|
|
5
|
+
handles login, caches your credentials between sessions, refreshes tokens, and lets you use paths
|
|
6
|
+
relative to the API root.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
Requires Python 3.11 or newer.
|
|
11
|
+
|
|
12
|
+
=== "pip"
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pip install hakai-api
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
=== "uv"
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
uv add hakai-api
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Quickstart
|
|
25
|
+
|
|
26
|
+
```python
|
|
27
|
+
from hakai_api import Client
|
|
28
|
+
|
|
29
|
+
client = Client() # (1)!
|
|
30
|
+
|
|
31
|
+
response = client.get("/eims/views/output/chlorophyll?limit=50") # (2)!
|
|
32
|
+
response.raise_for_status()
|
|
33
|
+
print(response.json())
|
|
34
|
+
# [{'action': '', 'event_pk': 7064, 'rn': '1', 'date': '2012-05-17', 'work_area': 'CALVERT', ...
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
1. The first time this runs, it prints a login URL and asks you to paste the credentials string
|
|
38
|
+
from that page. The credentials are cached in `~/.hakai-api-auth`, so later runs skip the prompt
|
|
39
|
+
until they expire.
|
|
40
|
+
2. Paths that start with `/` are appended to the API root (`https://portal.hakai.org/api`).
|
|
41
|
+
|
|
42
|
+
`Client` subclasses `requests.Session` (via `requests_oauthlib.OAuth2Session`), so `get`, `post`,
|
|
43
|
+
`params=`, `json=`, `timeout=`, and the rest of the requests API work as usual.
|
|
44
|
+
|
|
45
|
+
## Next steps
|
|
46
|
+
|
|
47
|
+
- [Authentication](guides/authentication.md): pick a login flow and manage credentials in scripts,
|
|
48
|
+
containers, and CI.
|
|
49
|
+
- [Configuration](guides/configuration.md): point the client at another API instance and set a user agent.
|
|
50
|
+
- [API Reference](reference.md): every public class and method.
|
|
51
|
+
- [Hakai API endpoints](https://hakaiinstitute.github.io/hakai-api/): what data you can request.
|