hakai_api 1.5.2__tar.gz → 2.0.1__tar.gz

{hakai_api-1.5.2 → hakai_api-2.0.1}/.github/workflows/release.yaml

@@ -7,6 +7,8 @@ on:
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+'
       - 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
+    paths-ignore:
+      - 'README.md'
 
 jobs:
   publish:

{hakai_api-1.5.2 → hakai_api-2.0.1}/.gitignore

@@ -101,3 +101,7 @@ ENV/
 .mypy_cache/
 
 .idea/
+.serena
+.aider*
+/.claude/
+CLAUDE.md

{hakai_api-1.5.2 → hakai_api-2.0.1}/.pre-commit-config.yaml

@@ -1,19 +1,24 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
+exclude: ^.*\.lock$
 repos:
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.20.0
+    hooks:
+      - id: pyupgrade
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: mixed-line-ending
       - id: trailing-whitespace
       - id: end-of-file-fixer
-      - id: check-yaml
-      - id: check-added-large-files
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
-    rev: v0.11.9
+    rev: v0.12.3
     hooks:
-      # Run the linter.
-      - id: ruff
+      - id: ruff-check
         args: [ --fix ]
-      # Run the formatter.
       - id: ruff-format

hakai_api-2.0.1/CONTRIBUTING.md

@@ -0,0 +1,202 @@
+# Contributing
+
+This document describes how to set up a development environment for this project, modify
+and test the code, and deploy a new version.
+
+<details>
+
+<summary>Table of Contents</summary>
+
+[Project structure](#project-structure)
+
+[Configuration](#configuration)
+
+[Tests](#tests)
+- [Running Tests](#running-tests)
+- [Authentication Flow Testing](#authentication-flow-testing)
+- [Linting and Formatting](#linting-and-formatting)
+- [Environment Variables for Testing](#environment-variables-for-testing)
+
+[Deployment](#deployment)
+
+</details>
+
+## Project structure
+
+The business logic for this package is located
+in [`src/hakai_api/client.py`](src/hakai_api/client.py).
+All tests are located in the `tests/` directory.
+
+Key components:
+- `client.py` - Main OAuth2Session client with authentication flows
+- `auth/` - Authentication strategies (web and desktop flows)
+- `tests/` - Comprehensive test suite including authentication flow tests
+
+## Configuration
+
+### uv
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management and
+package installation. Install `uv` using the instructions on their website before continuing.
+
+To set up an environment for development, clone this repository and run the following
+commands from the root directory of the repository:
+
+```bash
+# Install the package and its dependencies (uv handles virtual environment automatically)
+uv sync
+```
+
+### Pre-commit
+
+This project uses [pre-commit](https://pre-commit.com/) to run lint checks and tests
+before every commit. To install the pre-commit hooks, run the following command from the
+root directory of the repository while the virtual environment is active:
+
+```bash
+pre-commit install
+```
+
+This is highly recommended and will prevent failed builds on GitHub Actions, as well as
+ensure consistent code style and quality.
+
+You can also run the pre-commit hooks manually on all files by running:
+
+```bash
+pre-commit run -a
+```
+
+## Tests
+
+Tests and lint checks are automatically run on pull requests and pushes to the main
+branch using GitHub Actions.
+
+### Running Tests
+
+To run the tests locally:
+
+```bash
+# Run all tests
+pytest
+
+# Run a specific test file
+pytest tests/test_client.py
+
+# Run a specific test function
+pytest tests/test_client.py::test_get_valid_credentials_from_file
+
+# Run tests with verbose output
+pytest -v
+```
+
+### Authentication Flow Testing
+
+The project includes comprehensive tests for both authentication flows:
+
+- **Web flow tests**: Test credential parsing, file operations, and web-based authentication
+- **Desktop flow tests**: Test OAuth2 with PKCE flow, token refresh, and callback handling
+- **Mock tests**: Most tests use mocked authentication to avoid requiring real credentials
+
+When adding new authentication features, ensure you add appropriate tests for both flows.
+
+#### Web Authentication Flow
+
+The web flow requires users to manually copy credentials from a browser:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client
+    participant Browser
+    participant API
+
+    User->>Client: Create Client()
+    Client->>Client: Check cached credentials
+    alt No valid cached credentials
+        Client->>User: Display login URL
+        User->>Browser: Open login URL
+        Browser->>API: User logs in
+        API->>Browser: Display credentials token
+        Browser->>User: Show credentials token
+        User->>Client: Copy/paste credentials
+        Client->>Client: Parse and validate credentials
+        Client->>Client: Cache credentials to file
+    end
+    Client->>API: Make authenticated request
+    API->>Client: Return response
+```
+
+#### Desktop Authentication Flow (OAuth2 with PKCE)
+
+The desktop flow uses OAuth2 with PKCE for more secure authentication:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client
+    participant LocalServer
+    participant Browser
+    participant API
+
+    User->>Client: Create Client(auth_flow="desktop")
+    Client->>Client: Check cached credentials
+    alt No valid cached credentials
+        Client->>Client: Generate PKCE code_verifier & code_challenge
+        Client->>LocalServer: Start local callback server
+        Client->>Browser: Open OAuth URL with PKCE params
+        Browser->>API: User logs in and authorizes
+        API->>Browser: Redirect to local callback with auth code
+        Browser->>LocalServer: Send auth code
+        LocalServer->>Client: Receive auth code
+        Client->>API: Exchange auth code + code_verifier for tokens
+        API->>Client: Return access_token & refresh_token
+        Client->>Client: Cache credentials to file
+        Client->>LocalServer: Shutdown callback server
+    end
+    Client->>API: Make authenticated request
+    alt Token expired
+        Client->>API: Use refresh_token to get new access_token
+        API->>Client: Return new access_token
+        Client->>Client: Update cached credentials
+    end
+    API->>Client: Return response
+```
+
+### Linting and Formatting
+
+To run lint checks locally:
+
+```bash
+ruff check .
+```
+
+To automatically fix linting issues:
+
+```bash
+ruff check --fix .
+```
+
+To automatically format the code:
+
+```bash
+ruff format .
+```
+
+### Environment Variables for Testing
+
+Some tests may require environment variables:
+
+```bash
+# Optional: Set custom user agent for testing
+export HAKAI_API_USER_AGENT="test-client/1.0"
+
+# Optional: Set custom credentials file location
+export HAKAI_API_CREDENTIALS="/tmp/test-credentials"
+```
+
+## Deployment
+
+To build and deploy a new PyPi package version, push a tag matching the
+pattern `v[0-9]+.[0-9]+.[0-9]+` or `v[0-9]+.[0-9]+.[0-9]+rc[0-9]+` (e.g. `v0.4.1`
+or `v0.5.2rc1`) to GitHub. GitHub Actions will take care of packaging and pushing it
+to Hakai's PyPi repository from there.

{hakai_api-1.5.2 → hakai_api-2.0.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Hakai Institute
+Copyright (c) 2025 Hakai Institute
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

hakai_api-2.0.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: hakai_api
+Version: 2.0.1
+Summary: Get Hakai database resources using http calls
+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>
+Maintainer-email: Taylor Denouden <taylor.denouden@hakai.org>, Sam Albers <sam.albers@hakai.org>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pkce>=1.0.3
+Requires-Dist: pytz>=2025.2
+Requires-Dist: requests-oauthlib>=2.0.0
+Requires-Dist: requests>=2.32.3
+Description-Content-Type: text/markdown
+
+# 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.
+
+![PyPI](https://img.shields.io/pypi/v/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)
+
+<details>
+
+<summary>Table of Contents</summary>
+
+[Installation](#installation)
+
+[Quickstart](#quickstart)
+- [Desktop OAuth Flow](#desktop-oauth-flow)
+- [User Agent Configuration](#user-agent-configuration)
+
+[Methods](#methods)
+
+[API endpoints](#api-endpoints)
+
+[Advanced usage](#advanced-usage)
+- [Custom API Endpoints](#custom-api-endpoints)
+- [Relative Endpoint Support](#relative-endpoint-support)
+- [Credentials Configuration](#credentials-configuration)
+
+[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 (using relative endpoint)
+response = client.get('/eims/views/output/chlorophyll?limit=50')
+
+print(response.json())
+# [{'action': '', 'event_pk': 7064, 'rn': '1', 'date': '2012-05-17', 'work_area': 'CALVERT'...
+```
+
+## Desktop OAuth Flow
+
+For native applications and automated scripts, use the desktop OAuth flow with PKCE:
+
+```python
+from hakai_api import Client
+
+# Use desktop OAuth flow (opens browser, more secure)
+client = Client(auth_flow="desktop")
+
+# Or use the factory method
+client = Client.create_desktop_client()
+
+# Make requests using relative endpoints
+response = client.get('/eims/views/output/stations')
+print(response.json())
+```
+
+## User Agent Configuration
+
+**Important**: Set a descriptive user agent to help identify your application on the backend. Often the repository url is a good way to identify yourself:
+
+```python
+from hakai_api import Client
+import os
+
+# Set user agent during initialization
+client = Client(user_agent="MyApp/1.0 (contact@example.com)")
+
+# Or set via environment variable
+os.environ['HAKAI_API_USER_AGENT'] = "MyApp/1.0 (contact@example.com)"
+client = Client()
+```
+
+# 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
+
+## Custom API Endpoints
+
+You can specify which API to access when instantiating the Client. By default, the API
+uses `https://portal.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
+```
+
+## Relative Endpoint Support
+
+The client supports relative endpoints that automatically prepend the API root:
+
+```python
+from hakai_api import Client
+
+client = Client()
+
+# These are equivalent:
+response1 = client.get('/eims/views/output/stations')
+response2 = client.get('https://portal.hakai.org/api/eims/views/output/stations')
+```
+
+## Credentials Configuration
+
+### Direct Credentials
+
+You can 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")
+```
+
+### Environment Variables
+
+Set credentials 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.
+
+```bash
+export HAKAI_API_CREDENTIALS="your_credential_token_here"
+```
+
+### Custom Credentials File Location
+
+By default, credentials are saved to `~/.hakai-api-auth`. You can customize this location:
+
+```python
+from hakai_api import Client
+
+# Set custom credentials file path
+client = Client(credentials_file="/path/to/my/credentials")
+
+# Or use environment variable
+# export HAKAI_API_CREDENTIALS="/path/to/my/credentials"
+client = Client()
+```
+
+# Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md)
+
+# License
+
+See [LICENSE](LICENSE.md)

hakai_api-1.5.2/PKG-INFO → hakai_api-2.0.1/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: hakai_api
-Version: 1.5.2
-Summary: Get Hakai database resources using http calls
-Author-email: Taylor Denouden <taylor.denouden@hakai.org>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.8
-Requires-Dist: pytz>=2025.2
-Requires-Dist: requests-oauthlib>=2.0.0
-Requires-Dist: requests>=2.32.3
-Description-Content-Type: text/markdown
-
 # Hakai Api Python Client
 
 This project exports a single Python class that can be used to make HTTP requests to the
@@ -28,12 +15,17 @@ OAuth2 credentials with url requests.
 [Installation](#installation)
 
 [Quickstart](#quickstart)
+- [Desktop OAuth Flow](#desktop-oauth-flow)
+- [User Agent Configuration](#user-agent-configuration)
 
 [Methods](#methods)
 
 [API endpoints](#api-endpoints)
 
 [Advanced usage](#advanced-usage)
+- [Custom API Endpoints](#custom-api-endpoints)
+- [Relative Endpoint Support](#relative-endpoint-support)
+- [Credentials Configuration](#credentials-configuration)
 
 [Contributing](#contributing)
 
@@ -55,15 +47,47 @@ 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)
+# Make a data request for chlorophyll data (using relative endpoint)
+response = client.get('/eims/views/output/chlorophyll?limit=50')
 
-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'...
 ```
 
+## Desktop OAuth Flow
+
+For native applications and automated scripts, use the desktop OAuth flow with PKCE:
+
+```python
+from hakai_api import Client
+
+# Use desktop OAuth flow (opens browser, more secure)
+client = Client(auth_flow="desktop")
+
+# Or use the factory method
+client = Client.create_desktop_client()
+
+# Make requests using relative endpoints
+response = client.get('/eims/views/output/stations')
+print(response.json())
+```
+
+## User Agent Configuration
+
+**Important**: Set a descriptive user agent to help identify your application on the backend. Often the repository url is a good way to identify yourself:
+
+```python
+from hakai_api import Client
+import os
+
+# Set user agent during initialization
+client = Client(user_agent="MyApp/1.0 (contact@example.com)")
+
+# Or set via environment variable
+os.environ['HAKAI_API_USER_AGENT'] = "MyApp/1.0 (contact@example.com)"
+client = Client()
+```
+
 # Methods
 
 This library exports a single client name `Client`. Instantiating this class produces
@@ -84,8 +108,10 @@ from, see the [Hakai API documentation](https://github.com/HakaiInstitute/hakai-
 
 # Advanced usage
 
+## Custom API Endpoints
+
 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
+uses `https://portal.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
@@ -99,7 +125,25 @@ 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
+## Relative Endpoint Support
+
+The client supports relative endpoints that automatically prepend the API root:
+
+```python
+from hakai_api import Client
+
+client = Client()
+
+# These are equivalent:
+response1 = client.get('/eims/views/output/stations')
+response2 = client.get('https://portal.hakai.org/api/eims/views/output/stations')
+```
+
+## Credentials Configuration
+
+### Direct Credentials
+
+You can pass in the credentials string retrieved from the hakai API login page
 while initiating the Client class.
 
 ```python
@@ -109,10 +153,30 @@ from hakai_api import Client
 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.
+### Environment Variables
+
+Set credentials 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.
+
+```bash
+export HAKAI_API_CREDENTIALS="your_credential_token_here"
+```
+
+### Custom Credentials File Location
+
+By default, credentials are saved to `~/.hakai-api-auth`. You can customize this location:
+
+```python
+from hakai_api import Client
+
+# Set custom credentials file path
+client = Client(credentials_file="/path/to/my/credentials")
+
+# Or use environment variable
+# export HAKAI_API_CREDENTIALS="/path/to/my/credentials"
+client = Client()
+```
 
 # Contributing
 

hakai_api-2.0.1/example.py

@@ -0,0 +1,14 @@
+"""An example showing how to use the Hakai Api Python Client."""
+
+from hakai_api import Client
+
+if __name__ == "__main__":
+    # WEB FLOW (default)
+    client = Client()
+    response = client.get(f"{client.api_root}/whoami")
+    print(response.json())
+
+    # DESKTOP FLOW
+    client = Client(auth_flow="desktop")  # Follow the prompts in the webpage that opens
+    response = client.get("/whoami")
+    print(response.json())