lavlab-shell 0.1.0__tar.gz

lavlab_shell-0.1.0/.devcontainer/Dockerfile

@@ -0,0 +1,43 @@
+ARG PY_VERSION=3.12
+
+FROM python:${PY_VERSION}-slim AS base
+
+# create non-root user (primarily for devcontainer)
+RUN groupadd --gid 1000 vscode \
+    && useradd --uid 1000 --gid 1000 -m vscode
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libopenslide0 \
+        libvips42 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE.txt ./
+COPY src/ src/
+
+RUN chown -R vscode:vscode /app
+
+FROM base AS hatch
+RUN pip3 install --no-cache-dir hatch
+ENV HATCH_ENV=default
+ENTRYPOINT ["hatch", "run"]
+
+FROM base AS dev
+COPY requirements/ requirements/
+COPY requirements.txt ./
+COPY tests/ tests/
+COPY docs/ docs/
+COPY mkdocs.yml ./
+RUN pip3 install --no-cache-dir hatch \
+    && hatch build \
+    && pip3 install --no-cache-dir $(find /app -name 'requirement*.txt' -exec echo -n '-r {} ' \;)
+USER vscode
+
+FROM base AS prod
+COPY --from=dev /app/dist/*.whl /tmp/
+RUN pip3 install --no-cache-dir /tmp/*.whl \
+    && rm -rf /tmp/*.whl
+USER vscode
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import shell" || exit 1

lavlab_shell-0.1.0/.editorconfig

@@ -0,0 +1,36 @@
+# EditorConfig — https://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+indent_size = 4
+max_line_length = 88
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{json,jsonc}]
+indent_size = 2
+
+[*.{toml,cfg,ini}]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{sh,bash,zsh}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[Dockerfile*]
+indent_size = 4

lavlab_shell-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"

lavlab_shell-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,22 @@
+name: Build Wheel using Hatch
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        run: docker build --target hatch -t shell:hatch .
+      - name: Build wheel with hatch
+        run: docker run --rm --entrypoint hatch -v "${{ github.workspace }}:/app" shell:hatch build
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: dist/*.whl

lavlab_shell-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,19 @@
+name: Lint and Format with Ruff
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint-and-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        run: docker build --target hatch -t shell:hatch .
+      - name: Check formatting with Ruff
+        run: docker run --rm -e HATCH_ENV=lint -v "${{ github.workspace }}:/app" shell:hatch format-check
+      - name: Run Ruff linter
+        run: docker run --rm -e HATCH_ENV=lint -v "${{ github.workspace }}:/app" shell:hatch check

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

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip setuptools wheel hatch
+
+      - name: Build wheel and sdist
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

lavlab_shell-0.1.0/.github/workflows/pytest.yml

@@ -0,0 +1,36 @@
+name: Run Pytest and Codecov with Hatch
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build --target hatch -t shell:hatch .
+
+      - name: Run pytest and generate coverage report
+        run: docker run --rm -e HATCH_ENV=test -v "${{ github.workspace }}:/app" shell:hatch cov
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: ${{ github.workspace }}/coverage.xml
+
+      - name: Upload coverage report to Codecov
+        if: ${{ secrets.CODECOV_TOKEN != '' }}
+        uses: codecov/codecov-action@v4
+        with:
+          fail_ci_if_error: true
+          files: ${{ github.workspace }}/coverage.xml
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Skip Codecov upload (no token)
+        if: ${{ secrets.CODECOV_TOKEN == '' }}
+        run: echo "Skipping Codecov — CODECOV_TOKEN not set."

lavlab_shell-0.1.0/.gitignore

@@ -0,0 +1,87 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+*.whl
+sdist/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Hatch
+.hatch/
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Testing / Coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.pytest_cache/
+.mypy_cache/
+
+# Documentation builds
+site/
+
+# Jupyter Notebooks
+.ipynb_checkpoints/
+
+# Ruff
+.ruff_cache/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Secrets — never commit these
+*.pem
+*.key
+
+# Logs
+*.log
+
+# Type stubs
+.pytype/
+dmypy.json
+
+# Pre-commit
+.pre-commit-cache/
+
+# Misc
+*.bak
+*.tmp
+*.png
+*.csv
+*.json
+
+# Data / model weights (too large for git)
+*.pth
+!src/shell/weights/*.pth
+*.tiff
+*.tif
+data/
+preprocessed/
+evaluation_results/

lavlab_shell-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--ignore-missing-imports]

lavlab_shell-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thank you for your interest in contributing! This document provides guidelines for working with this project.
+
+## Development Setup
+
+1. **Clone the repository:**
+
+   ```console
+   git clone https://github.com/LavLabInfrastructure/shell.git
+   cd shell
+   ```
+
+2. **Install Hatch** (build & environment manager):
+
+   ```console
+   pip install hatch
+   ```
+
+3. **Install pre-commit hooks:**
+
+   ```console
+   pip install pre-commit
+   pre-commit install
+   ```
+
+## Common Tasks
+
+| Task                    | Command                      |
+|-------------------------|------------------------------|
+| Run tests               | `hatch run test:test`        |
+| Run tests with coverage | `hatch run test:cov`         |
+| Lint code               | `hatch run lint:check`       |
+| Format code             | `hatch run lint:format`      |
+| Auto-fix lint issues    | `hatch run lint:fix`         |
+| Run all lint checks     | `hatch run lint:all`         |
+| Type check              | `hatch run types:check`      |
+| Build docs              | `hatch run docs:build-docs`  |
+| Serve docs locally      | `hatch run docs:serve-docs`  |
+| Build wheel             | `hatch build`                |
+
+## Code Style
+
+- **Formatter & Linter:** [Ruff](https://docs.astral.sh/ruff/) handles both formatting and linting.
+- **Line length:** 88 characters.
+- **Docstrings:** Sphinx-style (`:param:`, `:type:`, `:return:`, `:rtype:`).
+- **Type hints:** Encouraged. The project includes a `py.typed` marker for PEP 561 compliance.
+
+## Project Architecture
+
+1. **Library modules** (`src/shell/`) contain all business logic as importable functions.
+2. **CLI** (`src/shell/cli.py`) is a thin wrapper that delegates to library functions.
+3. **Tests** (`tests/`) import directly from the library.
+
+## Submitting Changes
+
+1. Create a branch from `main`.
+2. Make your changes and ensure all checks pass.
+3. Open a Pull Request against `main`.
+
+## License
+
+`shell` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

lavlab_shell-0.1.0/Dockerfile

@@ -0,0 +1,46 @@
+ARG PY_VERSION=3.12
+
+FROM python:${PY_VERSION}-slim AS base
+
+# create non-root user (primarily for devcontainer)
+RUN groupadd --gid 1000 vscode \
+    && useradd --uid 1000 --gid 1000 -m vscode
+
+# System libraries required by openslide, pyvips, and macenko-pca (OpenBLAS)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libopenslide0 \
+    libvips42 \
+    libopenblas0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# install dependencies first for better layer caching
+COPY pyproject.toml README.md LICENSE.txt ./
+COPY src/ src/
+
+RUN chown -R vscode:vscode /app
+
+FROM base AS hatch
+RUN pip3 install --no-cache-dir hatch uv
+ENV HATCH_ENV=default
+ENTRYPOINT ["hatch", "run"]
+
+FROM base AS dev
+COPY requirements/ requirements/
+COPY requirements.txt ./
+COPY tests/ tests/
+COPY docs/ docs/
+COPY mkdocs.yml ./
+RUN pip3 install --no-cache-dir hatch \
+    && hatch build \
+    && pip3 install --no-cache-dir $(find /app -name 'requirement*.txt' -exec echo -n '-r {} ' \;)
+USER vscode
+
+FROM base AS prod
+COPY --from=dev /app/dist/*.whl /tmp/
+RUN pip3 install --no-cache-dir /tmp/*.whl \
+    && rm -rf /tmp/*.whl
+USER vscode
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import shell" || exit 1

lavlab_shell-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present barrettMCW
+
+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.

lavlab_shell-0.1.0/Makefile

@@ -0,0 +1,57 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help test cov lint format fix types docs serve-docs build clean install pre-commit
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install the package in development mode with hatch
+	pip install hatch
+	hatch env create
+
+test: ## Run tests
+	hatch run test:test
+
+cov: ## Run tests with coverage report
+	hatch run test:cov
+
+lint: ## Run Ruff linter
+	hatch run lint:check
+
+format: ## Format code with Ruff
+	hatch run lint:format
+
+fix: ## Auto-fix lint issues and format
+	hatch run lint:all
+
+types: ## Run mypy type checking
+	hatch run types:check
+
+docs: ## Build documentation
+	hatch run docs:build-docs
+
+serve-docs: ## Serve documentation locally
+	hatch run docs:serve-docs
+
+build: ## Build wheel and sdist
+	hatch build
+
+clean: ## Remove build artifacts and caches
+	rm -rf dist/ build/ site/ htmlcov/
+	rm -f coverage.xml .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name '*.egg-info' -exec rm -rf {} + 2>/dev/null || true
+
+pre-commit: ## Install and run pre-commit hooks
+	pre-commit install
+	pre-commit run --all-files
+
+docker-dev: ## Build and run dev Docker image
+	docker build --target dev -t shell:dev .
+
+docker-prod: ## Build production Docker image
+	docker build --target prod -t shell:prod .