aind-code-ocean-pipeline-utils 0.4.2__tar.gz

aind_code_ocean_pipeline_utils-0.4.2/.copier-answers.yml

@@ -0,0 +1,26 @@
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+_commit: 0.1.15
+_src_path: /home/galen.lynch/Documents/Code/aind-python-copier-template
+author_email: galen@galenlynch.com
+author_fullname: Galen Lynch
+auto_setup_repo: true
+current_year: '2026'
+github_org: AllenNeuralDynamics
+github_url: https://github.com/AllenNeuralDynamics/aind-code-ocean-pipeline-utils
+include_claude_md: true
+include_cli: false
+include_commitizen: true
+include_docs: false
+include_notebooks: false
+include_type_hints: true
+institute_name: Allen Institute for Neural Dynamics
+license: MIT
+project_description: Utilities for use in Code Ocean pipelines
+project_name: AIND Code Ocean pipeline utils
+project_slug: aind-code-ocean-pipeline-utils
+publish_to_pypi: true
+python_package_import_name: aind_code_ocean_pipeline_utils
+python_version: '3.11'
+target_python_version: '3.13'
+workflow_source: AllenNeuralDynamics/galen-uv-workflows
+workflow_version: v2

aind_code_ocean_pipeline_utils-0.4.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

aind_code_ocean_pipeline_utils-0.4.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

aind_code_ocean_pipeline_utils-0.4.2/.github/ISSUE_TEMPLATE/user-story.md

@@ -0,0 +1,27 @@
+---
+name: User story
+about: This template provides a basic structure for user story issues.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+# User story
+As a ..., I want to ..., so I can ...
+
+*Ideally, this is in the issue title, but if not, you can put it here. If so, delete this section.*
+
+# Acceptance criteria
+- [ ] This is something that can be verified to show that this user story is satisfied.
+
+# Sprint Ready Checklist 
+- [ ] 1. Acceptance criteria defined 
+- [ ] 2. Team understands acceptance criteria 
+- [ ] 3. Team has defined solution / steps to satisfy acceptance criteria 
+- [ ] 4. Acceptance criteria is verifiable / testable 
+- [ ] 5. External / 3rd Party dependencies identified
+- [ ] 6. Ticket is prioritized and sized
+
+# Notes
+*Add any helpful notes here.*

aind_code_ocean_pipeline_utils-0.4.2/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # Enable version updates for GitHub Actions
+  - package-ecosystem: "github-actions"
+    # Workflow files stored in the default location of `.github/workflows`
+    # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  # Enable version updates for pip
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

aind_code_ocean_pipeline_utils-0.4.2/.github/workflows/bump-call.yml

@@ -0,0 +1,33 @@
+name: Bump Version
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    branches: [ main ]
+    types: [ completed ]
+  workflow_dispatch:
+
+permissions:
+  contents: write    # needed to push commits/tags
+  id-token: write    # needed if your reusable workflow exchanges OIDC tokens
+
+concurrency:
+  group: bump-${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  bump:
+    # Only run when:
+    #  • a CI run just succeeded (and the head commit message doesn't start with 'bump:')
+    #  • OR this is a manual dispatch
+    if: >
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       !startsWith(github.event.workflow_run.head_commit.message, 'bump:')) ||
+      (github.event_name == 'workflow_dispatch' &&
+      github.ref == 'refs/heads/main')
+    uses: AllenNeuralDynamics/galen-uv-workflows/.github/workflows/bump-version.yml@v2
+    with:
+      default-branch: main
+    secrets:
+      repo-token: ${{ secrets.SERVICE_TOKEN }}

aind_code_ocean_pipeline_utils-0.4.2/.github/workflows/ci-call.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  run-ci:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.13"]
+
+    if: >
+      (github.event_name != 'pull_request' || github.event.pull_request.draft == false) &&
+      github.actor != 'github-actions[bot]' &&
+      !(github.event_name == 'push' && startsWith(github.event.head_commit.message, 'bump:'))
+
+    uses: AllenNeuralDynamics/galen-uv-workflows/.github/workflows/ci.yml@v2
+    with:
+      os: ${{ matrix.os }}
+      python-version: ${{ matrix.python-version }}
+      package-name: aind_code_ocean_pipeline_utils
+      run-mypy: true
+    secrets:
+      repo-token: ${{ secrets.GITHUB_TOKEN }}

aind_code_ocean_pipeline_utils-0.4.2/.github/workflows/publish-call.yml

@@ -0,0 +1,25 @@
+name: "Release"
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'          # semver tags
+  workflow_dispatch:
+
+permissions:
+  contents: write    # create release + upload assets
+
+concurrency:
+  group: release
+  cancel-in-progress: false   # let releases finish
+
+jobs:
+  run-release:
+    uses: AllenNeuralDynamics/galen-uv-workflows/.github/workflows/publish.yml@v2
+    with:
+      tag-name: ${{ github.ref_name }}
+      python-version: "3.13"
+      publish-to-pypi: true
+    secrets:
+      repo-token: ${{ secrets.GITHUB_TOKEN }}
+      pypi-token: ${{ secrets.AIND_PYPI_TOKEN }}

aind_code_ocean_pipeline_utils-0.4.2/.gitignore

@@ -0,0 +1,153 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# MacOs
+**/.DS_Store
+
+# VSCode
+.vscode/
+
+# Scratch / working directory
+scratch/
+TODO.md
+
+# Claude
+.claude/
+
+# Repo setup scripts (generated by template, not meant to be committed)
+setup_repo.sh
+configure_repo.sh

aind_code_ocean_pipeline_utils-0.4.2/.python-version

@@ -0,0 +1 @@
+3.13

aind_code_ocean_pipeline_utils-0.4.2/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+### Feat
+
+- re-export cli + provenance from top level; extend README
+- **log**: add build_progress and make_progress_callback
+- **provenance**: add capsule_commit and package_version
+- **cli**: add parse_truthy for CO app-panel parameters
+- re-export role_dispatch + diagnostics from top level; extend README
+- **diagnostics**: add data-tree and memory reporters
+- **role_dispatch**: add launcher/worker/aggregator skeleton
+- re-export core API from top-level package
+- **threading_utils**: add contextvars-preserving submit wrapper
+- **log**: add rich-aware logging under [rich] extra
+- **cache**: add input_fingerprint for cache keys
+- **io**: add retry_on_oserror and atomic writes
+- **process**: add graceful shutdown module
+
+## v0.4.2 (2026-07-22)
+
+### Fix
+
+- publish to pypi
+
+## v0.4.1 (2026-06-04)
+
+### Perf
+
+- **step**: lazy-import aind-data-schema so the metadata tax is near-zero
+
+## v0.4.0 (2026-06-03)
+
+### Feat
+
+- **step**: add capsule_step decorator for frictionless processing.json
+
+## v0.3.0 (2026-06-03)
+
+### Feat
+
+- add optional metadata module for processing.json DAG assembly
+
+## v0.2.0 (2026-04-23)
+
+### Feat
+
+- add file handler
+
+## v0.1.0 (2026-04-21)
+
+### Feat
+
+- re-export cli + provenance from top level; extend README
+- **log**: add build_progress and make_progress_callback
+- **provenance**: add capsule_commit and package_version
+- **cli**: add parse_truthy for CO app-panel parameters
+- re-export role_dispatch + diagnostics from top level; extend README
+- **diagnostics**: add data-tree and memory reporters
+- **role_dispatch**: add launcher/worker/aggregator skeleton
+- re-export core API from top-level package
+- **threading_utils**: add contextvars-preserving submit wrapper
+- **log**: add rich-aware logging under [rich] extra
+- **cache**: add input_fingerprint for cache keys
+- **io**: add retry_on_oserror and atomic writes
+- **process**: add graceful shutdown module

aind_code_ocean_pipeline_utils-0.4.2/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run all checks (formatting, linting, type checking, tests)
+./scripts/run_linters_and_checks.sh -c
+
+# Run tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_example.py
+
+# Run a single test by name
+uv run pytest -k "test_name"
+
+# Formatting
+uv run ruff format
+
+# Linting
+uv run ruff check
+uv run ruff check --fix
+
+# Type checking
+uv run mypy
+
+# Spell checking
+uv run codespell --check-filenames
+
+```
+
+Always use `uv run` to execute commands, `uv add` to add dependencies, and `uv sync` to set up the environment. Never use bare `pip` or `python`.
+
+## Architecture
+
+This is a Python package using a `src/` layout. Source code lives in `src/aind_code_ocean_pipeline_utils/`, tests in `tests/`.
+
+- Build system: hatchling
+- Formatting/linting: ruff (line length 120, numpy docstring convention)
+- Testing: pytest with coverage reporting
+- Type checking: mypy (strict mode)
+- Versioning: commitizen (semantic versioning via conventional commits)
+
+### Package layout
+
+Planned module structure (see `TODO.md` for full API sketches and rationale):
+
+```
+src/aind_code_ocean_pipeline_utils/
+├── process.py          # graceful shutdown — SIGINT/SIGTERM → GracefulExit(BaseException)
+├── io.py               # retry_on_oserror, atomic_json_write / atomic_write_text
+├── cache.py            # input_fingerprint — SHA256 of canonical JSON
+├── log.py              # rich+stdlib-logging compatibility (optional extra [rich])
+└── threading_utils.py  # copy_context()-per-submit ThreadPoolExecutor wrapper
+```
+
+Module names deliberately avoid shadowing stdlib (`logging`, `concurrent`) so sibling modules can `import logging` / `from concurrent.futures import ...` without ambiguity.
+
+**Core (`process`, `io`, `cache`) stays stdlib-only.** Optional modules gate heavy deps via named extras (e.g. `pip install aind-code-ocean-pipeline-utils[rich]`). Any new dependency outside those three modules must come with its own extra.
+
+### Release plan
+
+- **v0.1.0** — `process` + `io` + `cache` (stdlib-only)
+- **v0.2.0** — add `log` with `[rich]` extra
+- **v0.3.0** — add `threading_utils` (stdlib-only, no extra)
+
+### Design invariants to preserve
+
+These are load-bearing — every module has a subtle bug it exists to prevent. Don't relax them without understanding the original failure mode documented in `TODO.md`:
+
+- `process.GracefulExit` inherits from `BaseException`, not `Exception`, so consumer `except Exception:` blocks don't swallow shutdown signals. Signal handlers flip a `threading.Event` and return — never call `sys.exit`, `logger.exception`, or other non-async-signal-safe code from inside the handler. Exit code = `128 + signum`. Second signal escalates via `os._exit`.
+- `io.retry_on_oserror` uses a narrow `TRANSIENT_ERRNOS` frozenset (EIO, EAGAIN, EBUSY, network errnos). Permanent errors (ENOENT, EACCES, EINVAL) must raise immediately — retrying them hides config typos behind minutes of backoff. Use `os.replace` (not `os.rename`) for cross-platform atomicity. `fsync` defaults to True.
+- `cache.input_fingerprint` requires JSON-serializable input and raises `TypeError` on anything else. Callers coerce `Path → str`, `ndarray → list`, etc. at the call site. Return value is prefixed `sha256:` so the algorithm can change without breaking string comparisons.
+- `threading_utils.submit_with_context` calls `copy_context()` **per submit**, not once shared across submits. A shared Context raises `RuntimeError` when active on two threads concurrently (bit `ecephys-mipmap-zarr` at `prefetch_chunks >= 2`).
+- `log.install_rich_handler` returns the `Console` object so the caller can pass the same one to `rich.progress.Progress(console=...)`. Not sharing it is what causes `logger.exception` inside `with Progress():` to lose its traceback tail.
+
+### Target consumers
+
+- `ecephys-mipmap-builder-capsule` (local path: `/home/galen.lynch/Documents/Code/ecephys-mipmap-builder-capsule`) — reference consumer for shaking out API friction. First migration target.
+- `pl-oversplitting-analysis-capsule` (ccg monorepo) — has none of the patterns; its `--merge-only` resume does a raw file-exists check with no fingerprint validation. Migration candidate after first bug report.
+
+Note: `ecephys-mipmap-zarr` is **not** a target — it is Code-Ocean-agnostic and should not depend on this package.

aind_code_ocean_pipeline_utils-0.4.2/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Allen Institute for Neural Dynamics
+
+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.
+