hemonc-alchemy 0.1.0__tar.gz

hemonc_alchemy-0.1.0/.devcontainer/Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.12-slim-bookworm
+
+# Copy uv from the official image while keeping the application image Python slim.
+COPY --from=ghcr.io/astral-sh/uv:0.8.17 /uv /uvx /bin/
+
+ARG USERNAME=vscode
+ARG USER_UID=1000
+ARG USER_GID=1000
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_LINK_MODE=copy \
+    UV_PROJECT_ENVIRONMENT=/opt/venv \
+    PATH="/opt/venv/bin:/home/${USERNAME}/.local/bin:${PATH}"
+
+RUN groupadd --gid "${USER_GID}" "${USERNAME}" \
+    && useradd --uid "${USER_UID}" --gid "${USER_GID}" -m -s /bin/bash "${USERNAME}"
+
+WORKDIR /workspace/hemonc-alchemy
+
+# The source is mounted by Compose. The project and its extras are installed by
+# the Compose command/post-create hook when the mounted Git checkout is
+# available to hatch-vcs; installing here would omit the mounted source tree.
+RUN apt-get update \
+    && apt-get install --yes --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir --parents /opt/venv \
+    && chown -R "${USERNAME}:${USERNAME}" /opt/venv
+
+USER ${USERNAME}

hemonc_alchemy-0.1.0/.devcontainer/bootstrap.py

@@ -0,0 +1,45 @@
+import os
+from pathlib import Path
+
+import sqlalchemy as sa
+import sqlalchemy.orm as so
+
+from hemonc_alchemy.model import entities
+from hemonc_alchemy.model.base import Base, concrete_entities, register_enum_casts
+from hemonc_alchemy.toolkit.loading import load_all
+
+data_dir = Path("/workspace/hemonc-alchemy/data/Tables")
+engine = sa.create_engine(os.environ["DATABASE_URL"])
+
+# This script is a full rebuild for the disposable development database. The
+# denormalised child tables are loaded with INSERTs, so dropping first also
+# makes reruns after a partial import deterministic.
+with engine.begin() as connection:
+    inspector = sa.inspect(connection)
+    for table_name in inspector.get_table_names():
+        if table_name.startswith("_staging_"):
+            quoted_name = connection.dialect.identifier_preparer.quote(table_name)
+            connection.exec_driver_sql(f"DROP TABLE IF EXISTS {quoted_name} CASCADE")
+
+Base.metadata.drop_all(engine)
+Base.metadata.create_all(engine)
+register_enum_casts()
+
+source_entities = sorted(
+    (
+        cls for cls in concrete_entities(entities)
+        if getattr(cls, "filename", None)
+    ),
+    key=lambda cls: cls.__tablename__,
+)
+
+with so.Session(engine) as session:
+    for entity_cls in source_entities:
+        counts = load_all(
+            session,
+            entity_cls,
+            data_dir,
+            chunksize=100_000,
+        )
+        session.commit()
+        print(entity_cls.__tablename__, counts)

hemonc_alchemy-0.1.0/.devcontainer/compose.yaml

@@ -0,0 +1,62 @@
+services:
+  python-hemonc-alchemy:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+    command: ["/bin/sh", "-c", "uv sync --frozen --extra dev --extra author --extra exploration --extra postgres --extra omop && sleep infinity"]
+    environment:
+      DATABASE_URL: postgresql+psycopg://hemonc:hemonc@postgres:5432/hemonc_alchemy
+      OA_CONFIG_PATH: /home/vscode/.config/omop/config.toml
+      PGHOST: postgres
+      PGPORT: "5432"
+      PGDATABASE: hemonc_alchemy
+      PGUSER: hemonc
+      PGPASSWORD: hemonc
+    depends_on:
+      postgres:
+        condition: service_healthy
+    volumes:
+      - ..:/workspace/hemonc-alchemy:cached
+
+  postgres:
+    image: pgvector/pgvector:0.8.6-pg18-bookworm
+    environment:
+      POSTGRES_DB: hemonc_alchemy
+      POSTGRES_USER: hemonc
+      POSTGRES_PASSWORD: hemonc
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U hemonc -d hemonc_alchemy"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    ports:
+      - "5432:5432"
+    volumes:
+      # PostgreSQL 18 stores data under a major-version-specific subdirectory.
+      - postgres-data:/var/lib/postgresql
+      - ./initdb:/docker-entrypoint-initdb.d:ro
+
+  pgadmin:
+    image: dpage/pgadmin4:latest
+    environment:
+      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL:-admin@example.com}
+      # Development-only default; override this in .env for a shared machine.
+      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD:-hemonc-admin}
+      # Load the checked-in server definition whenever the container starts.
+      PGADMIN_SERVER_JSON_FILE: /pgadmin4/servers.json
+      PGADMIN_REPLACE_SERVERS_ON_STARTUP: ${PGADMIN_REPLACE_SERVERS_ON_STARTUP:-True}
+      # The password cannot be stored in servers.json; pgAdmin reads it from pgpass.
+      PGPASS_FILE: /pgadmin4/pgpass
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "${PGADMIN_PORT:-5050}:80"
+    volumes:
+      - pgadmin-data:/var/lib/pgadmin
+      - ./servers.json:/pgadmin4/servers.json:ro
+      - ./pgpass:/pgadmin4/pgpass:ro
+
+volumes:
+  postgres-data:
+  pgadmin-data:

hemonc_alchemy-0.1.0/.devcontainer/config.toml

@@ -0,0 +1,80 @@
+# oa-configurator stack config for the HemOnc Alchemy devcontainer.
+#
+# Copied to ~/.config/omop/config.toml (mode 600) by post-create.sh the first
+# time the container is created, so `omop-config configure hemonc_alchemy` can
+# edit it afterwards without touching this checked-in seed. Delete that copy
+# and rebuild the container to start again from this file.
+#
+# The credentials below are the throwaway ones the compose stack creates; they
+# only reach the `postgres` service on the devcontainer network. Real passwords
+# belong in your own ~/.config/omop/config.toml, never here.
+
+# ---------------------------------------------------------------------------
+# Connections: the compose `postgres` service, addressed by service name.
+# ---------------------------------------------------------------------------
+
+[connections.devcontainer_postgres]
+dialect       = "postgresql+psycopg"
+host          = "postgres"
+port          = 5432
+user          = "hemonc"
+password      = "hemonc"
+database_name = "hemonc_alchemy"
+
+# Same server, separate database, so `pytest -m postgres` never writes to the
+# database you loaded with bootstrap.py. Created on first use by the
+# oa-configurator pytest plugin; `test_only` is the safety check that lets it.
+[connections.devcontainer_postgres_test]
+dialect       = "postgresql+psycopg"
+host          = "postgres"
+port          = 5432
+user          = "hemonc"
+password      = "hemonc"
+database_name = "hemonc_alchemy_test"
+test_only     = true
+
+# ---------------------------------------------------------------------------
+# Databases: the logical targets used by HemOnc and OMOP Alchemy.
+# ---------------------------------------------------------------------------
+
+[databases.hemonc_db]
+kind        = "generic"
+connection  = "devcontainer_postgres"
+schema_name = "public"
+
+[databases.test_hemonc_db]
+kind        = "generic"
+connection  = "devcontainer_postgres_test"
+schema_name = "public"
+
+# OMOP-alchemy's CDM target shares the compose PostgreSQL service and the
+# HemOnc schema for now. This is a configuration choice for the disposable
+# development database; oa-configurator will own schema resolution when its
+# cross-package support is available.
+[databases.cdm_db]
+kind        = "cdm"
+connection  = "devcontainer_postgres"
+schema_name = "public"
+
+[databases.test_cdm_db]
+kind        = "cdm"
+connection  = "devcontainer_postgres_test"
+schema_name = "public"
+
+# ---------------------------------------------------------------------------
+# Tools: package-specific [tools.<tool_name>] sections.
+# ---------------------------------------------------------------------------
+
+[tools.hemonc_alchemy]
+hemonc_db      = "hemonc_db"
+test_hemonc_db = "test_hemonc_db"
+
+[tools.omop_alchemy]
+cdm_db      = "cdm_db"
+test_cdm_db = "test_cdm_db"
+
+[logging]
+level = "INFO"
+
+[logging.loggers]
+"sqlalchemy.engine" = "WARNING"

hemonc_alchemy-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,28 @@
+{
+  "name": "HemOnc Alchemy",
+  "dockerComposeFile": "compose.yaml",
+  "service": "python-hemonc-alchemy",
+  "workspaceFolder": "/workspace/hemonc-alchemy",
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": true,
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  // also on start, so containers created before the kernel fix get it
+  "postStartCommand": "bash .devcontainer/register-kernel.sh",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-toolsai.jupyter",
+        "charliermarsh.ruff"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/opt/venv/bin/python",
+        "python.analysis.extraPaths": [
+          "/workspace/hemonc-alchemy"
+        ]
+      }
+    }
+  },
+  "shutdownAction": "none"
+}

hemonc_alchemy-0.1.0/.devcontainer/initdb/01-enable-pgvector.sql

@@ -0,0 +1 @@
+CREATE EXTENSION IF NOT EXISTS vector;

hemonc_alchemy-0.1.0/.devcontainer/pgpass

@@ -0,0 +1 @@
+postgres:5432:hemonc_alchemy:hemonc:hemonc

hemonc_alchemy-0.1.0/.devcontainer/post-create.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Devcontainer create-time setup: install the project, then seed the
+# oa-configurator stack config pointing at the compose `postgres` service.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+uv sync --frozen --extra dev --extra author --extra exploration --extra postgres --extra omop
+
+bash "$(dirname "$0")/register-kernel.sh"
+
+config_path="${OA_CONFIG_PATH:-${HOME}/.config/omop/config.toml}"
+mkdir -p "$(dirname "${config_path}")"
+
+if [ -e "${config_path}" ]; then
+  echo "Keeping the existing stack config at ${config_path}"
+else
+  # Mode 600 because the file holds database passwords; oa-configurator warns
+  # about anything more permissive. Copied rather than mounted so that
+  # `omop-config configure hemonc_alchemy` can rewrite it in place, without
+  # the edit landing back in the checked-in seed.
+  install -m 600 .devcontainer/config.toml "${config_path}"
+  echo "Installed the devcontainer stack config at ${config_path}"
+fi

hemonc_alchemy-0.1.0/.devcontainer/register-kernel.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Register the project environment as the `python3` Jupyter kernel.
+#
+# The VS Code Jupyter extension supplies its own kernel when it attaches, but
+# `jupyter execute`, nbclient and papermill all resolve `python3` from the
+# kernel spec directory. Without this, running the notebooks from the CLI
+# fails with NoSuchKernel even though every dependency is installed.
+#
+# Run from postStartCommand, not just postCreateCommand: a container created
+# before this script existed would otherwise never get the kernel.
+# `ipykernel install` is idempotent, so re-running on every start is safe.
+set -euo pipefail
+
+if ! python -c "import ipykernel" 2>/dev/null; then
+  echo "ipykernel not installed; skipping kernel registration (needs the exploration extra)"
+  exit 0
+fi
+
+python -m ipykernel install --user --name python3 --display-name "hemonc-alchemy" >/dev/null
+echo "Registered the python3 Jupyter kernel"

hemonc_alchemy-0.1.0/.devcontainer/servers.json

@@ -0,0 +1,16 @@
+{
+  "Servers": {
+    "1": {
+      "Name": "HemOnc Alchemy PostgreSQL",
+      "Group": "HemOnc Alchemy",
+      "Host": "postgres",
+      "Port": 5432,
+      "MaintenanceDB": "hemonc_alchemy",
+      "Username": "hemonc",
+      "ConnectionParameters": {
+        "sslmode": "prefer",
+        "connect_timeout": 10
+      }
+    }
+  }
+}

hemonc_alchemy-0.1.0/.env_sample

@@ -0,0 +1,13 @@
+# The devcontainer seeds its own oa-configurator stack config from
+# .devcontainer/config.toml into ~/.config/omop/config.toml inside the
+# container
+
+# Set OA_CONFIG_PATH only to point oa-configurator at a different file.
+# OA_CONFIG_PATH=/home/vscode/.config/omop/config.toml
+
+# pgAdmin (available at http://localhost:5050 by default)
+PGADMIN_PORT=5050
+PGADMIN_DEFAULT_EMAIL=admin@example.com
+PGADMIN_DEFAULT_PASSWORD=change-me
+# Set to False if you want to preserve servers added manually in pgAdmin.
+PGADMIN_REPLACE_SERVERS_ON_STARTUP=True

hemonc_alchemy-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: "🐞 Bug Report"
+description: Report a reproducible bug.
+type: "Bug"
+body:
+  - type: checkboxes
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One or two sentences describing the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Steps and/or a minimal code example that reproduces the issue. Wrap code in triple backticks.
+      placeholder: |
+        1. Import X and call Y with Z
+        2. Observe error
+
+        ```python
+        # minimal example
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output
+      description: Full traceback if applicable. Formatted automatically.
+      render: python-traceback
+
+  - type: textarea
+    id: system
+    attributes:
+      label: System info
+      description: |
+        Run the following command and paste its output:
+        python <(curl -s https://raw.githubusercontent.com/AustralianCancerDataNetwork/cava-devops/main/scripts/cava_system_info.py)
+      render: shell

hemonc_alchemy-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Existing issues
+    url: https://github.com/AustralianCancerDataNetwork/hemonc-alchemy/issues
+    about: Search existing issues before opening a new report.

hemonc_alchemy-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: "🚀 Feature Request"
+description: Propose a new feature or enhancement.
+type: "Feature"
+body:
+  - type: checkboxes
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this has not been requested before.
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What are you trying to do that you currently cannot?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you considered and why you ruled them out.

hemonc_alchemy-0.1.0/.github/ISSUE_TEMPLATE/not_working.yml

@@ -0,0 +1,55 @@
+name: "❗ Something is not working"
+description: Something behaves unexpectedly but you are not sure if it is a bug.
+body:
+  - type: checkboxes
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues for this problem.
+          required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Problem summary
+      description: One or two sentences describing what is not working.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Steps and/or a minimal code example. Wrap code in triple backticks.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual outcome
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected outcome
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error messages
+      description: Full traceback if applicable. Formatted automatically.
+      render: python-traceback
+
+  - type: textarea
+    id: system
+    attributes:
+      label: System info
+      description: |
+        Run the following command and paste its output:
+        python <(curl -s https://raw.githubusercontent.com/AustralianCancerDataNetwork/cava-devops/main/scripts/cava_system_info.py)
+      render: shell

hemonc_alchemy-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- Keep the PR title concise and factual: it becomes the release-note entry. Use this section for reviewer context, trade-offs, and validation details. -->
+
+## Checklist
+
+- [ ] Applied exactly one label (`breaking`, `feature`, `fix`, `dependencies`, or `chore`)
+- [ ] Tests pass locally (`uv run pytest -q`)
+- [ ] Lint passes (`uv run ruff check .`)
+- [ ] Generated model changes were regenerated and reviewed, if applicable

hemonc_alchemy-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,31 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+commitish: main
+
+categories:
+  - title: Breaking Changes
+    labels: ['breaking']
+  - title: Features
+    labels: ['feature']
+  - title: Fixes
+    labels: ['fix']
+  - title: Dependencies
+    labels: ['dependencies']
+
+template: |
+  $CHANGES
+
+change-template: '- **$TITLE** (#$NUMBER) @$AUTHOR'
+
+version-resolver:
+  major:
+    labels: ['breaking']
+  minor:
+    labels: ['feature']
+  patch:
+    labels: ['fix', 'dependencies']
+  default: patch
+
+exclude-labels: ['chore']
+
+autolabeler: []

hemonc_alchemy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  label-gate:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/label-gate.yml@main
+
+  build-test:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test-postgres.yml@main
+    with:
+      python-version: "3.12"
+      postgres-db: test
+      postgres-user: test
+      postgres-password: test
+      # The generated model and loader use dynamic SQLAlchemy/pandas types
+      # that are not yet clean under ty. Keep the shared check focused on the
+      # typed public/configuration boundary until those surfaces are annotated.
+      ty-src: hemonc_alchemy/cli.py hemonc_alchemy/config.py hemonc_alchemy/integrations
+      setup-commands: |
+        mkdir -p "$HOME/.config/omop"
+        cat > "$HOME/.config/omop/config.toml" <<'EOF'
+        [connections.ci_postgres]
+        dialect = "postgresql+psycopg"
+        host = "localhost"
+        port = 5432
+        user = "test"
+        password = "test"
+        database_name = "test"
+        test_only = true
+
+        [databases.ci_hemonc_db]
+        kind = "generic"
+        connection = "ci_postgres"
+        schema_name = "public"
+
+        [tools.hemonc_alchemy]
+        hemonc_db = "ci_hemonc_db"
+        test_hemonc_db = "ci_hemonc_db"
+        EOF

hemonc_alchemy-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,13 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/deploy-docs.yml@main

hemonc_alchemy-0.1.0/.github/workflows/manual-release.yml

@@ -0,0 +1,24 @@
+name: Manual Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to release (for example, 1.2.3; no leading v)
+        required: true
+        type: string
+      prerelease:
+        description: Mark the release as a pre-release
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/manual-release.yml@main
+    with:
+      version: ${{ inputs.version }}
+      prerelease: ${{ inputs.prerelease }}

hemonc_alchemy-0.1.0/.github/workflows/merge.yml

@@ -0,0 +1,16 @@
+name: Release Update
+
+on:
+  pull_request:
+    branches: [main]
+    types: [closed]
+
+permissions:
+  contents: write
+  pull-requests: read
+
+jobs:
+  draft:
+    if: github.event.pull_request.merged == true
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/release-drafter.yml@main
+    secrets: inherit

hemonc_alchemy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/publish.yml@main
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hemonc-alchemy
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1