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.
Files changed (37) hide show
  1. hakai_api-2.1.0/.github/workflows/lint.yaml +27 -0
  2. hakai_api-2.1.0/.github/workflows/release.yaml +83 -0
  3. {hakai_api-2.0.1 → hakai_api-2.1.0}/.github/workflows/test.yaml +12 -5
  4. hakai_api-2.1.0/.github/workflows/zizmor.yaml +31 -0
  5. {hakai_api-2.0.1 → hakai_api-2.1.0}/.pre-commit-config.yaml +7 -3
  6. hakai_api-2.1.0/.readthedocs.yaml +16 -0
  7. {hakai_api-2.0.1 → hakai_api-2.1.0}/CONTRIBUTING.md +35 -8
  8. hakai_api-2.1.0/PKG-INFO +62 -0
  9. hakai_api-2.1.0/README.md +46 -0
  10. hakai_api-2.1.0/docs/contributing.md +1 -0
  11. hakai_api-2.1.0/docs/guides/authentication.md +111 -0
  12. hakai_api-2.1.0/docs/guides/configuration.md +79 -0
  13. hakai_api-2.1.0/docs/index.md +51 -0
  14. hakai_api-2.1.0/docs/reference.md +38 -0
  15. {hakai_api-2.0.1 → hakai_api-2.1.0}/pyproject.toml +11 -7
  16. {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/__init__.py +7 -4
  17. {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/base.py +62 -5
  18. {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/desktop.py +3 -13
  19. {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/web.py +3 -14
  20. {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/client.py +52 -14
  21. {hakai_api-2.0.1 → hakai_api-2.1.0}/tests/test_auth_strategies.py +8 -7
  22. {hakai_api-2.0.1 → hakai_api-2.1.0}/tests/test_client.py +170 -19
  23. hakai_api-2.1.0/uv.lock +908 -0
  24. hakai_api-2.1.0/zensical.toml +80 -0
  25. hakai_api-2.0.1/.github/workflows/lint.yaml +0 -21
  26. hakai_api-2.0.1/.github/workflows/release.yaml +0 -54
  27. hakai_api-2.0.1/PKG-INFO +0 -203
  28. hakai_api-2.0.1/README.md +0 -187
  29. hakai_api-2.0.1/uv.lock +0 -758
  30. {hakai_api-2.0.1 → hakai_api-2.1.0}/.gitignore +0 -0
  31. {hakai_api-2.0.1 → hakai_api-2.1.0}/CODEOWNERS +0 -0
  32. {hakai_api-2.0.1 → hakai_api-2.1.0}/LICENSE +0 -0
  33. {hakai_api-2.0.1 → hakai_api-2.1.0}/example.py +0 -0
  34. {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/__init__.py +0 -0
  35. {hakai_api-2.0.1 → hakai_api-2.1.0}/src/hakai_api/auth/desktop_callback.html +0 -0
  36. {hakai_api-2.0.1 → hakai_api-2.1.0}/tests/__init__.py +0 -0
  37. {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@v4
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@v5
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@v5
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.20.0
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: v5.0.0
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.12.3
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 [pre-commit](https://pre-commit.com/) to run lint checks and tests
53
- before every commit. To install the pre-commit hooks, run the following command from the
54
- root directory of the repository while the virtual environment is active:
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
- pre-commit install
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 pre-commit hooks manually on all files by running:
66
+ You can also run the hooks manually on all files by running:
64
67
 
65
68
  ```bash
66
- pre-commit run -a
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 HAKAI_API_CREDENTIALS="/tmp/test-credentials"
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
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/hakai-api)](https://pypi.org/project/hakai_api/) [![tests](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml/badge.svg)](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml) [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](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
+ [![PyPI](https://img.shields.io/pypi/v/hakai-api)](https://pypi.org/project/hakai_api/) [![tests](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml/badge.svg)](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml) [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](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.