labapi 1.0.3__tar.gz

labapi-1.0.3/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,110 @@
+name: Bug report
+description: Report a reproducible problem in labapi.
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a problem.
+
+        Please redact API credentials, auth keys, notebook content, and any other sensitive data before submitting.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: A short description of the problem and the impact it has on your workflow.
+      placeholder: default_authenticate() raises an exception after opening the browser callback flow.
+    validations:
+      required: true
+  - type: input
+    id: labapi-version
+    attributes:
+      label: labapi version
+      description: The package version you are using, or the commit/branch name if installed from source.
+      placeholder: 0.1.0, main, or a git commit SHA
+    validations:
+      required: true
+  - type: dropdown
+    id: python-version
+    attributes:
+      label: Python version
+      description: Which Python version reproduces the issue?
+      options:
+        - "3.12"
+        - "3.13"
+        - Other
+    validations:
+      required: true
+  - type: dropdown
+    id: install-profile
+    attributes:
+      label: Install profile
+      description: Which install path most closely matches your environment?
+      options:
+        - Installed from source with `uv sync`
+        - `pip install labapi`
+        - `pip install 'labapi[dotenv]'`
+        - `pip install 'labapi[builtin-auth]'`
+        - `pip install 'labapi[dotenv,builtin-auth]'`
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include your OS, shell, and any other environment details that matter.
+      placeholder: |
+        Windows 11
+        PowerShell 7
+        API_URL=https://api.labarchives.com
+        Running behind a VPN
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Share the smallest sequence of steps that reproduces the issue.
+      placeholder: |
+        1. Create a client with `Client()`
+        2. Call `default_authenticate()`
+        3. Complete the browser auth flow
+        4. Observe the exception
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      placeholder: The client should authenticate and return the current user object.
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      placeholder: The browser flow completes, but the callback server times out after 60 seconds.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproducible example
+      description: If possible, share a small script that reproduces the problem.
+      render: python
+  - type: textarea
+    id: logs
+    attributes:
+      label: Traceback or logs
+      description: Paste any error output, traceback, or debug logs that may help.
+      render: shell
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I searched the existing issues before opening this report.
+          required: true
+        - label: I redacted secrets and sensitive notebook data from the details above.
+          required: true

labapi-1.0.3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Usage and setup docs
+    url: https://github.com/nimh-dsst/labapi/tree/main/docs/source
+    about: Start here for installation, authentication, quick-start, and FAQ guidance.
+  - name: Contributing guide
+    url: https://github.com/nimh-dsst/labapi/blob/main/CONTRIBUTING.md
+    about: Review local setup, testing commands, and code-quality expectations for contributions.

labapi-1.0.3/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,50 @@
+name: Feature request
+description: Suggest an improvement to the library, docs, or developer workflow.
+title: "[Feature]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement to labapi.
+
+        Clear examples of the workflow you want to support make it much easier to evaluate the request.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: What are you trying to do, and what is hard or missing today?
+      placeholder: I need a simpler way to authenticate in a headless CI job without wiring my own callback server.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the API, behavior, or docs change you would like to see.
+      placeholder: Add a helper that exchanges a one-time auth token for a session using environment variables.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Share any workarounds, adjacent APIs, or alternative approaches you have tried.
+      placeholder: Today I build the auth URL myself and parse the callback in a separate script.
+  - type: textarea
+    id: examples
+    attributes:
+      label: Example usage
+      description: If helpful, sketch the code or command-line flow you want.
+      render: python
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add links, screenshots, docs references, or other details that would help.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I searched the existing issues before opening this request.
+          required: true

labapi-1.0.3/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Docs
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  docs:
+    name: Docs build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Build Sphinx docs
+        run: uv run sphinx-build -b html docs/source docs/_build

labapi-1.0.3/.github/workflows/format.yml

@@ -0,0 +1,13 @@
+name: Ruff Format
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  format:
+    uses: ./.github/workflows/python_check.yml
+    with:
+      job_name: Ruff format
+      command: uv run ruff format --check .
+      python_versions: '["3.13"]'

labapi-1.0.3/.github/workflows/integration_tests.yml

@@ -0,0 +1,43 @@
+name: Integration Test Suite
+
+on:
+  workflow_dispatch:
+    inputs:
+      la_key:
+        description: LabArchives Authentication Token
+        required: true
+        type: string
+      la_email:
+        description: LabArchives Authentication la_email
+        required: true
+        type: string
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v5
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+        version: "latest"
+
+    - name: Set up Python
+      run: uv python install 3.13
+
+    - name: Install dependencies
+      run: uv sync --all-groups
+
+    - name: Run tests with pytest
+      env:
+        API_URL: ${{ secrets.API_URL }}
+        ACCESS_KEYID: ${{ secrets.AKID }}
+        ACCESS_PWD: ${{ secrets.AKPASS }}
+        AUTH_KEY: ${{ github.event.inputs.la_key }}
+        AUTH_EMAIL: ${{ github.event.inputs.la_email }}
+        NOTEBOOK: ${{ secrets.NOTEBOOK }}
+      run: uv run pytest tests/test_integration.py

labapi-1.0.3/.github/workflows/lint.yml

@@ -0,0 +1,13 @@
+name: Ruff Lint
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    uses: ./.github/workflows/python_check.yml
+    with:
+      job_name: Ruff lint
+      command: uv run ruff check .
+      python_versions: '["3.13"]'

labapi-1.0.3/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/labapi/
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build distributions
+        run: uv build --python 3.13 --clear --no-build-logs
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

labapi-1.0.3/.github/workflows/python_check.yml

@@ -0,0 +1,47 @@
+name: Python Check
+
+on:
+  workflow_call:
+    inputs:
+      job_name:
+        required: true
+        type: string
+      command:
+        required: true
+        type: string
+      append_python_version_arg:
+        required: false
+        type: boolean
+        default: false
+      python_versions:
+        required: false
+        type: string
+        default: '["3.12", "3.13"]'
+
+jobs:
+  check:
+    name: ${{ inputs.job_name }} (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ fromJSON(inputs.python_versions) }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run check
+        run: ${{ inputs.command }}${{ inputs.append_python_version_arg && format(' --python-version {0}', matrix.python-version) || '' }}

labapi-1.0.3/.github/workflows/typecheck.yml

@@ -0,0 +1,19 @@
+name: Type Check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  pyright:
+    uses: ./.github/workflows/python_check.yml
+    with:
+      job_name: Pyright
+      command: uv run pyright
+
+  ty:
+    uses: ./.github/workflows/python_check.yml
+    with:
+      job_name: ty
+      command: uv run ty check
+      append_python_version_arg: true

labapi-1.0.3/.github/workflows/unit_tests.yml

@@ -0,0 +1,12 @@
+name: Unit Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  unit-tests:
+    uses: ./.github/workflows/python_check.yml
+    with:
+      job_name: Unit tests
+      command: uv run pytest

labapi-1.0.3/.gitignore

@@ -0,0 +1,55 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+tests/__pycache__
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.env
+.python-version
+.ruff_cache/
+.mypy_cache/
+
+
+# Coverage reports
+.coverage
+
+# IDE files
+.vscode/
+.idea/
+*.iml
+.idea
+
+
+.claude/
+.notes
+.environment-*
+.mcp.json
+
+# Sandbox stub files (empty placeholders created by Claude Code's sandbox)
+.gitconfig
+.gitmodules
+.zprofile
+.zshrc
+.bashrc
+.bash_profile
+.profile
+.ripgreprc
+HEAD
+config
+hooks
+objects
+refs
+
+docs/build/
+docs/_build/
+docs/source/reference/generated/
+
+
+.ipynb-checkpoints
+.tmpdocs

labapi-1.0.3/.mockenv

@@ -0,0 +1,10 @@
+# LabArchives API Client credentials
+API_URL=https://api.labarchives.com
+ACCESS_KEYID=your_access_key_id_here
+ACCESS_PWD=your_access_password_here
+
+# Integration test settings
+AUTH_EMAIL=your_email@example.com
+AUTH_KEY=your_auth_key_here
+AUTH_INTERACTIVE=false
+NOTEBOOK=My Test Notebook

labapi-1.0.3/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: local
+    hooks:
+      - id: pyright-check
+        name: Run Pyright
+        entry: uv
+        args: [run, pyright]
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: pytest-check
+        name: Run Pytest (pre-push)
+        entry: uv
+        args: [run, pytest, --no-cov]
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.14.11
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format

labapi-1.0.3/.zenodo.json

@@ -0,0 +1,20 @@
+{
+  "title": "labapi",
+  "description": "Python client for the LabArchives API",
+  "creators": [
+    {
+      "name": "Li, Christoph",
+      "affiliation": "National Institute of Mental Health",
+      "orcid": "0009-0009-4624-2578"
+    },
+    {
+      "name": "Lawrimore, Josh",
+      "affiliation": "National Institute of Mental Health",
+      "orcid": "0000-0003-2301-9073"
+    }
+  ],
+  "keywords": ["Electronic Lab Notebook", "ELN", "LabArchives", "API"],
+  "license": "CC0-1.0",
+  "access_right": "open",
+  "upload_type": "software"
+}

labapi-1.0.3/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+**Important:** Check `.environment-setup` if it exists - it contains host-specific instructions (e.g., using Nix instead of uv).
+
+## Project Overview
+
+`labapi` is a Python client library for the LabArchives API, providing an object-oriented interface for managing notebooks, folders, pages, and entries. The LabArchives API uses XML, and requests are signed with HMAC-SHA512.
+
+## Build & Development Commands
+
+```bash
+# Setup (using uv)
+uv sync
+source .venv/bin/activate
+
+# Run all tests with coverage
+pytest
+
+# Run specific test file
+pytest tests/test_unit.py
+pytest tests/test_integration.py  # requires LA_KEY and LA_EMAIL env vars
+
+# Lint and format
+ruff check .
+ruff format .
+ruff check --fix .  # auto-fix linting issues
+```
+
+## Architecture
+
+The codebase follows a hierarchical tree structure mirroring LabArchives organization:
+
+**Core modules:**
+- `src/labapi/client.py` - Main API client with HMAC-SHA512 request signing, authentication flows (`generate_auth_url`, `login_authcode`), and `api_get`/`api_post` methods
+- `src/labapi/user.py` - Authenticated user session; provides access to notebooks via `user.notebooks`
+- `src/labapi/tree/` - Hierarchical data model: `Notebook` → `NotebookDirectory` → `NotebookPage`
+- `src/labapi/entry/` - Entry types on pages: `TextEntry`, `HeaderEntry`, `PlainTextEntry`, `AttachmentEntry`, `WidgetEntry`
+- `src/labapi/util/extract.py` - XML extraction helpers (`extract_etree`, `to_bool`, `_flatten_dict`)
+- `src/labapi/util/index.py` - Indexing enum for accessing items by ID or name: `notebook[Index.Id:"some_id"]` or `notebook[Index.Name:"some_name"]`
+
+**Entry point pattern:**
+```python
+from labapi import Client
+client = Client(base_url, akid, password)  # or Client() to load from .env
+auth_url = client.generate_auth_url(redirect_url)
+user = client.login_authcode(user_email, auth_code)
+notebooks = user.notebooks
+```
+
+## Development Conventions
+
+- **Type hinting:** All new code must be fully type-hinted
+- **XML handling:** Use `lxml` for all XML parsing; use helpers in `src/labapi/util/extract.py`
+- **Testing:** Prefer unit tests with `MockClient` (in `tests/test_unit.py`) over integration tests to avoid hitting the live API
+- **Error handling:** API errors are raised as `RuntimeError` (future: type these more specifically)
+
+## Environment Variables
+
+The `Client` class auto-loads from a `.env` file via `python-dotenv` when credentials aren't passed directly. Create a `.env` file (gitignored) with:
+
+```bash
+API_URL=https://api.labarchives.com  # optional, this is the default
+ACCESS_KEYID=your_akid               # required
+ACCESS_PWD=your_password             # required
+```
+
+**Other environment variables:**
+- `LA_KEY`, `LA_EMAIL` - Required for integration tests
+- `LA_AUTH_BROWSER` - Browser for OAuth flows (chrome, firefox, edge)
+- `AUTH_INTERACTIVE` - Enable interactive authentication mode
+- `NOTEBOOK` - Target notebook name for testing

labapi-1.0.3/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+## Setup
+
+```bash
+uv sync --all-groups
+pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+## Running Tests
+
+Unit tests run entirely offline using `MockClient`:
+
+```bash
+uv run pytest
+```
+
+Integration tests are opt-in and require live API credentials in `.env` or the environment:
+
+```bash
+# Required
+ACCESS_KEYID=your_akid
+ACCESS_PWD=your_password
+API_URL=https://api.labarchives.com
+
+# Required for non-interactive login used by tests/test_integration.py
+AUTH_EMAIL=your@email.com
+AUTH_KEY=your_auth_key
+
+# Optional: use the browser callback flow instead
+# AUTH_INTERACTIVE=true
+```
+
+```bash
+uv run pytest --integration tests/test_integration.py
+```
+
+`Client()` only auto-loads `API_URL`, `ACCESS_KEYID`, and `ACCESS_PWD`; `AUTH_EMAIL` and `AUTH_KEY` are test-fixture conventions used by the integration suite.
+
+## Code Style
+
+Ruff handles linting, formatting, and branch-complexity checks. Pyright handles type checking. After installing both hook types:
+
+- `ruff-check`, `ruff-format`, and `pyright-check` run on `pre-commit`
+- `pytest-check` runs `uv run pytest --no-cov` on `pre-push`
+
+Manual equivalents:
+
+```bash
+uv run ruff check --fix .   # lint
+uv run ruff format .        # format
+uv run pyright              # typecheck
+uv run radon cc src tests -s -a  # complexity report
+uv run pytest --no-cov      # pre-push test gate
+```
+
+## Type Annotations
+
+Run type checking locally with:
+
+```bash
+uv run pyright
+```
+
+All new code must be fully type-annotated. Key conventions:
+
+- `from __future__ import annotations` in every module
+- `override` on all method overrides
+- `TYPE_CHECKING` guards to avoid circular imports
+- Generics where they give callers concrete return types (e.g. `Entry[Attachment]`)