octostar-python-client 0.1.759__tar.gz

octostar_python_client-0.1.759/CLAUDE.md

@@ -0,0 +1,170 @@
+# CLAUDE.md — octostar_python_client SDK
+
+## Critical Rule: Do Not Break the Public API
+
+This SDK is consumed by **production legacy applications** (Streamlit apps, backend services, scheduled jobs) that import and call its functions directly. The public API surface is a hard contract.
+
+### What you MUST NOT change
+
+- **Function signatures**: Every endpoint module exposes `sync()`, `sync_detailed()`, `asyncio()`, `asyncio_detailed()` with their current parameter names, types, and return types. Do not rename, reorder, add required params, or change return types.
+- **Module paths**: Code like `from octostar.api.notifications import delete_stream` must continue to resolve. Do not move, rename, or delete modules.
+- **Model classes**: The `octostar/models/` classes use `@attr.s` with `to_dict()` / `from_dict()`. Their field names map to API JSON keys. Do not rename fields or change serialization.
+- **Client classes**: `Client`, `AuthenticatedClient`, `make_client()`, `as_launching_user()`, `as_running_user()` are the primary entry points. Their interfaces are frozen.
+- **Error classes**: `UnexpectedStatus`, `DeprecatedEndpointError`, `V1MigrationPendingError` are caught by consumer code.
+
+### What you CAN change
+
+- **Internal implementation** of `_get_kwargs()`, `_parse_response()`, `_build_response()` — these are private. You can change URLs, add new status code handlers, adjust request construction.
+- **Response body handling** inside `_parse_response()` — as long as the parsed type stays compatible.
+- **Default values** for optional parameters (e.g. timeouts), within reason.
+- **Adding new status code branches** to `_parse_response()` when the FastAPI backend changes behavior.
+
+### When the backend API changes
+
+If a FastAPI endpoint changes its URL, request format, or response shape, adapt the SDK's **internal implementation** to keep the external function signatures working. The SDK acts as a compatibility shim between the new backend and old consumer code.
+
+Example: if the backend moves from `/api/octostar/streams/{id}` to `/api/v1/streams/{id}`, update `_get_kwargs()` to use `client.get_base_url_v1()` instead of `client.get_base_url_v1()`. The consumer code calling `delete_stream.sync(stream_id="x", client=c)` should not notice.
+
+### When an endpoint is permanently removed
+
+Use `DeprecatedEndpointError` — preserve the function signatures but raise on call:
+
+```python
+def sync(stream_id: str, *, client: Any = None, ...) -> Optional[Any]:
+    raise DeprecatedEndpointError("delete_stream", "Removed in v2. Use X instead.")
+```
+
+### When an endpoint is not yet migrated
+
+Use `V1MigrationPendingError` to signal the endpoint will exist in the new backend but isn't ready yet.
+
+---
+
+## SDK Architecture
+
+### Origin
+
+Originally **generated from OpenAPI spec** (`openapi.json`) targeting the old Superset-based backend. Now manually maintained as the backend migrates to FastAPI. The generation patterns are preserved for consistency.
+
+### Two-Layer Design
+
+```
+octostar/
+├── api/          # Low-level HTTP layer (generated pattern)
+│   └── <tag>/    # One module per endpoint
+│       └── <op>.py   # _get_kwargs → _parse_response → sync/asyncio
+├── utils/        # High-level helper layer (hand-written)
+│   └── <domain>/ # User-friendly wrappers around api/ modules
+├── models/       # Data models (@attr.s with to_dict/from_dict)
+├── client.py     # Client, AuthenticatedClient, make_client()
+├── types.py      # Response[T], File, UNSET sentinel
+└── errors.py     # UnexpectedStatus, DeprecatedEndpointError, V1MigrationPendingError
+```
+
+**api/ layer**: Raw HTTP — builds request kwargs, parses responses by status code, returns typed `Response[T]`. Each module has exactly 4 public functions + 3 private helpers.
+
+**utils/ layer**: Wraps api/ calls with business logic, retries, convenience methods. This is what most consumer code actually uses.
+
+### Endpoint Module Pattern
+
+Every module in `api/` follows this exact structure:
+
+```python
+client_missing_msg = '...'           # Deprecation warning for default client
+
+def _get_kwargs(...) -> Dict:         # Build httpx request dict
+def _parse_response(...) -> Optional: # Map status codes to typed models
+def _build_response(...) -> Response: # Wrap in Response[T]
+
+def sync_detailed(...) -> Response[T]:     # Sync, full response
+def sync(...) -> Optional[T]:              # Sync, parsed only
+async def asyncio_detailed(...) -> Response[T]: # Async, full response
+async def asyncio(...) -> Optional[T]:          # Async, parsed only
+```
+
+### Client URL Routing
+
+The SDK handles two backend URL schemes:
+
+- `client.get_base_url_v1()` — old Superset routes (`/api/octostar/...`)
+- `client.get_base_url_v1()` — new FastAPI routes (`/api/v1/...`), rewrites `home.*` → `api.*` for K8s ingress
+
+**Note:** The shared K8s ingress routes `/api/v1/*` to `api.*` regardless of base URL, so either method works for v1 paths.
+
+When migrating an endpoint, switch the `_get_kwargs` from `get_base_url_v1()` to `get_base_url_v1()` and update the URL path.
+
+### Authentication
+
+Token resolution order (in `AuthenticatedClient`):
+1. `fixed_token` parameter (explicit)
+2. File at `/etc/secrets/OS_JWT` (K8s secret mount)
+3. Environment variable `OS_JWT`
+
+The `make_client()` factory reads `OS_API_ENDPOINT`, `OS_ONTOLOGY`, and optional `OS_ANCESTOR`, `OS_APP_NAME` from env vars.
+
+### Models
+
+All models use `@attr.s(auto_attribs=True)` with:
+- `to_dict()` / `from_dict()` for JSON serialization
+- `additional_properties: Dict[str, Any]` for extensibility (unknown API fields)
+- Dict-like access (`__getitem__`, `__setitem__`) for additional properties
+
+Response models are status-code-specific: `GetWhoamiResponse200`, `QueryResponse401`, etc.
+
+---
+
+## Testing
+
+### Contract Tests (`tests/test_contracts.py`)
+
+Validate SDK request construction against `openapi.json` **without network calls**:
+- Every endpoint module has standard functions
+- Request URLs match OpenAPI paths
+- Request bodies match schemas
+
+Run: `pytest octostar_python_client/tests/`
+
+Note: These tests require the `octostar` package to be importable. If they fail with `ModuleNotFoundError: No module named 'octostar'`, the package needs to be installed in editable mode or the path needs to be on `PYTHONPATH`.
+
+### Backend Integration Tests
+
+The FastAPI backend has its own tests in `tests/api/v1/` that test the actual endpoints. SDK contract tests complement these by verifying the SDK constructs valid requests.
+
+---
+
+## Common Tasks
+
+### Migrating an endpoint from Superset to FastAPI
+
+1. In `_get_kwargs()`: change `get_base_url_v1()` → `get_base_url_v1()` and update the URL path
+2. In `_parse_response()`: update status code handling if response shapes changed
+3. Keep function signatures identical
+4. Update `openapi.json` if maintaining spec accuracy
+
+### Adding a new status code handler
+
+Add a new `if response.status_code == HTTPStatus.XXX:` branch in `_parse_response()`. No signature changes needed.
+
+### Deprecating an endpoint
+
+Replace function bodies with `raise DeprecatedEndpointError(...)`. Keep signatures intact for import compatibility.
+
+---
+
+## Releasing & testing PR builds
+
+Publishing is automated (no manual publish):
+
+- **On merge to `main`**, the octostar-api release pipeline publishes the SDK to
+  PyPI via OIDC trusted publishing, versioned to the octostar-api GitVersion tag.
+- **On every PR** touching the SDK, `sdk_build.yml` publishes a pre-release to
+  TestPyPI versioned `0.0.<pr>.dev<run_number>` so a PR's changes can be
+  installed and tested before merge.
+
+To install a PR build, point at TestPyPI for the package and PyPI for the deps
+(TestPyPI does not host `httpx`, `tenacity`, …). Full pip/uv commands are in
+`README.md` → "Testing a PR build (TestPyPI)".
+
+The version is injected at build time via the `SDK_VERSION` env var, applied by
+`scripts/sdk/set_version.py`. Keep the `version` in `pyproject.toml` as a
+local-dev fallback only.

octostar_python_client-0.1.759/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Octostar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

octostar_python_client-0.1.759/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: octostar-python-client
+Version: 0.1.759
+Summary: A client library for accessing Octostar API
+Author-email: Octostar <systems@octostar.com>
+License-Expression: MIT
+Project-URL: Homepage, https://octostar.com
+Project-URL: Repository, https://github.com/Octostarco/octostar-api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.28.0,>=0.20.0
+Requires-Dist: attrs>=21.3.0
+Requires-Dist: python-dateutil<3,>=2.8.0
+Requires-Dist: PyJWT<3,>=2.0.0
+Requires-Dist: python-dotenv<2,>=1.0.0
+Requires-Dist: tenacity<9,>=8.3.0
+Requires-Dist: aiofiles>=22.0.0
+Requires-Dist: pytimeparse<2,>=1.1.0
+Provides-Extra: streamlit
+Requires-Dist: octostar-streamlit<1,>=0.1.26; extra == "streamlit"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21; extra == "test"
+Dynamic: license-file
+
+# octostar-python-client
+A client library for accessing Octostar API
+
+## Usage
+First, create a client:
+
+```python
+from octostar import Client
+
+client = Client(base_url="https://api.example.com")
+```
+
+If the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:
+
+```python
+from octostar import AuthenticatedClient
+
+client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
+```
+
+Now call your endpoint and use your models:
+
+```python
+from octostar.models import MyDataModel
+from octostar.api.my_tag import get_my_data_model
+from octostar.types import Response
+
+my_data: MyDataModel = get_my_data_model.sync(client=client)
+# or if you need more info (e.g. status_code)
+response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
+```
+
+Or do the same thing with an async version:
+
+```python
+from octostar.models import MyDataModel
+from octostar.api.my_tag import get_my_data_model
+from octostar.types import Response
+
+my_data: MyDataModel = await get_my_data_model.asyncio(client=client)
+response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
+```
+
+By default, when you're calling an HTTPS API it will attempt to verify that SSL is working correctly. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken",
+    verify_ssl="/path/to/certificate_bundle.pem",
+)
+```
+
+You can also disable certificate validation altogether, but beware that **this is a security risk**.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken", 
+    verify_ssl=False
+)
+```
+
+There are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info.
+
+Things to know:
+1. Every path/method combo becomes a Python module with four functions:
+    1. `sync`: Blocking request that returns parsed data (if successful) or `None`
+    1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.
+    1. `asyncio`: Like `sync` but async instead of blocking
+    1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking
+
+1. All path/query params, and bodies become method arguments.
+1. If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)
+1. Any endpoint which did not have a tag will be in `octostar.api.default`
+
+## Installing
+
+```bash
+pip install octostar-python-client
+```
+
+### Testing a PR build (TestPyPI)
+
+Every pull request that touches the SDK publishes a pre-release to
+[TestPyPI](https://test.pypi.org/project/octostar-python-client/) versioned
+`0.0.<pr>.dev<run_number>` (e.g. `0.0.898.dev1319`) — the `<pr>` segment is the
+PR number, so you can find the build for your PR. Use it to test SDK changes
+before they merge.
+
+TestPyPI does not host third-party dependencies (`httpx`, `tenacity`, …), so
+point the resolver at PyPI as an extra index for them:
+
+```bash
+# pip
+pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  octostar-python-client==0.0.<pr>.dev<N>
+```
+
+```bash
+# uv (--index-strategy so uv considers both indexes per-package)
+uv pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  --index-strategy unsafe-best-match \
+  octostar-python-client==0.0.<pr>.dev<N>
+```
+
+## Releasing
+
+Releases are automated. On every merge to `main`, the octostar-api release
+pipeline builds this package and publishes it to PyPI, stamped with the
+octostar-api version. There is no manual publish step.
+
+To build the package locally for development:
+
+```bash
+./scripts/sdk/build.sh          # writes octostar_python_client/dist/*.whl and *.tar.gz
+pip install octostar_python_client/dist/*.whl
+```

octostar_python_client-0.1.759/README.md

@@ -0,0 +1,122 @@
+# octostar-python-client
+A client library for accessing Octostar API
+
+## Usage
+First, create a client:
+
+```python
+from octostar import Client
+
+client = Client(base_url="https://api.example.com")
+```
+
+If the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:
+
+```python
+from octostar import AuthenticatedClient
+
+client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
+```
+
+Now call your endpoint and use your models:
+
+```python
+from octostar.models import MyDataModel
+from octostar.api.my_tag import get_my_data_model
+from octostar.types import Response
+
+my_data: MyDataModel = get_my_data_model.sync(client=client)
+# or if you need more info (e.g. status_code)
+response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
+```
+
+Or do the same thing with an async version:
+
+```python
+from octostar.models import MyDataModel
+from octostar.api.my_tag import get_my_data_model
+from octostar.types import Response
+
+my_data: MyDataModel = await get_my_data_model.asyncio(client=client)
+response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
+```
+
+By default, when you're calling an HTTPS API it will attempt to verify that SSL is working correctly. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken",
+    verify_ssl="/path/to/certificate_bundle.pem",
+)
+```
+
+You can also disable certificate validation altogether, but beware that **this is a security risk**.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken", 
+    verify_ssl=False
+)
+```
+
+There are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info.
+
+Things to know:
+1. Every path/method combo becomes a Python module with four functions:
+    1. `sync`: Blocking request that returns parsed data (if successful) or `None`
+    1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.
+    1. `asyncio`: Like `sync` but async instead of blocking
+    1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking
+
+1. All path/query params, and bodies become method arguments.
+1. If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)
+1. Any endpoint which did not have a tag will be in `octostar.api.default`
+
+## Installing
+
+```bash
+pip install octostar-python-client
+```
+
+### Testing a PR build (TestPyPI)
+
+Every pull request that touches the SDK publishes a pre-release to
+[TestPyPI](https://test.pypi.org/project/octostar-python-client/) versioned
+`0.0.<pr>.dev<run_number>` (e.g. `0.0.898.dev1319`) — the `<pr>` segment is the
+PR number, so you can find the build for your PR. Use it to test SDK changes
+before they merge.
+
+TestPyPI does not host third-party dependencies (`httpx`, `tenacity`, …), so
+point the resolver at PyPI as an extra index for them:
+
+```bash
+# pip
+pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  octostar-python-client==0.0.<pr>.dev<N>
+```
+
+```bash
+# uv (--index-strategy so uv considers both indexes per-package)
+uv pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  --index-strategy unsafe-best-match \
+  octostar-python-client==0.0.<pr>.dev<N>
+```
+
+## Releasing
+
+Releases are automated. On every merge to `main`, the octostar-api release
+pipeline builds this package and publishes it to PyPI, stamped with the
+octostar-api version. There is no manual publish step.
+
+To build the package locally for development:
+
+```bash
+./scripts/sdk/build.sh          # writes octostar_python_client/dist/*.whl and *.tar.gz
+pip install octostar_python_client/dist/*.whl
+```

octostar_python_client-0.1.759/examples/README.md

@@ -0,0 +1,54 @@
+# SDK examples
+
+Runnable scripts that exercise the `octostar` SDK against a live Octostar
+backend. They're meant for manual testing and as copy-paste starting points,
+not as automated tests.
+
+## `create_linkchart_demo.py`
+
+Interactive end-to-end demo for `create_linkchart`. It:
+
+1. Connects using your JWT and API endpoint.
+2. Searches workspaces by name and lets you pick one.
+3. Searches people by name (one or more) and lets you pick them.
+4. Discovers each person's relationships from the ontology and pulls in the
+   related entities (their phones, cars, and anything else the ontology links
+   to a person).
+5. Saves the result as a linkchart in the chosen workspace.
+
+This verifies the linkchart is written in the current format — an `os_file`
+entity whose attachment body holds the
+`application/octostar-linkchart-settings+json` graph — rather than the legacy
+`os_linkchart` shape.
+
+### Run it
+
+```bash
+export OS_JWT='your.jwt.token'
+export OS_API_ENDPOINT='https://home.main.octostar.com/'
+export OS_ONTOLOGY='os_ontology_v1'
+
+uv run python octostar_python_client/examples/create_linkchart_demo.py
+```
+
+When it finishes it prints the new chart's id and a link to open the
+workspace. Open the chart in the linkchart UI to confirm the nodes and edges
+render.
+
+### Useful flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--ontology` | Ontology name (defaults to `$OS_ONTOLOGY`, else prompted). |
+| `--person-concept` | Concept to search people in (default `os_person`). |
+| `--concepts` | Comma-separated substrings to keep only some neighbour types, e.g. `phone,car`. Empty = include every related entity. |
+| `--search-limit` | Max people returned per name search (default 15). |
+| `--chart-name` | Name for the linkchart (default: prompted). |
+
+### Notes
+
+- Many-to-many relationships are not traversed by the simple join path and are
+  skipped with an `INFO` log; the people you pick plus their one-to-many
+  neighbours still make it onto the chart.
+- The script prints each relationship it follows, so a first run is also a
+  quick way to learn what your ontology actually calls "phone", "car", etc.