Merge pull request #286 from clamsproject/283-pyproject-migration

pyproject-based build processes

Author: keighrim

.github/workflows/codecov.yml

@@ -12,7 +12,7 @@ on:
 jobs:
   test-and-codecov:
     name: "🤙 Call SDK test workflow"
-    uses: clamsproject/.github/.github/workflows/sdk-codecov.yml@main
+    uses: clamsproject/.github/.github/workflows/sdk-codecov-pyproj.yml@main
     secrets:
       CC_REPO_UPLOAD_TOKEN: ${{ secrets.CODECOV_UPLOAD_TOKEN_CLAMS_PYTHON }}
 

.github/workflows/publish.yml

@@ -36,7 +36,7 @@ jobs:
     name: "📦 Build and upload to PyPI"
     needs: check-pypi
     if: needs.check-pypi.outputs.exists == 'false'
-    uses: clamsproject/.github/.github/workflows/sdk-publish.yml@main
+    uses: clamsproject/.github/.github/workflows/sdk-publish-pyproj.yml@main
     secrets: inherit
 
   publish-docs:
@@ -48,7 +48,4 @@ jobs:
       source_repo: clamsproject/clams-python
       source_ref: ${{ needs.check-pypi.outputs.version }}
       project_name: clams-python
-      build_command: 'echo "${{ needs.check-pypi.outputs.version }}" > VERSION && python3 build-tools/docs.py --output-dir docs'
-      docs_output_dir: 'docs'
-      python_version: '3.11'
     secrets: inherit

.gitignore

@@ -4,7 +4,6 @@
 
 # build time temp files
 VERSION*
-clams/ver
 
 # linux
 .*.sw?
@@ -67,6 +66,7 @@ hs_err_pid* # virtual machine crash logs, see http://www.java.com/en/download/he
 build/
 dist/
 *.egg-info
+clams_python-*/
 coverage.xml
 
 # shared folders
@@ -84,3 +84,5 @@ tags
 
 # sphinx
 docs-test/
+documentation/appmetadata.jsonschema
+documentation/whatsnew.md

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to clams-python
+
+## Prerequisites
+
+- Python 3.10+
+- `gh` CLI (for changelog generation)
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+Unlike the old `setup.py`-based workflow, an editable install
+(`pip install -e .`) is now required before running tests or building
+docs. The package uses `importlib.metadata` for version resolution at
+runtime, which only works when the package is registered in the
+environment. You can no longer run `pytest` or `pytype` directly
+against the source tree without installing first. If you want to avoid
+pulling in all dependencies, `pip install -e . --no-deps` is sufficient
+to register the package metadata.
+
+## Local Development
+
+All build tasks are handled by scripts in `build-tools/`. Each script
+is self-contained and installs its own dependencies as needed.
+
+| Task | Command |
+|------|---------|
+| Build (sdist + wheel) | `python build-tools/build.py` |
+| Run tests | `python build-tools/test.py` |
+| Build docs | `python build-tools/docs.py` |
+| Clean artifacts | `python build-tools/clean.py` |
+| Publish | `python build-tools/publish.py` |
+
+All scripts support `--help` for full usage details.
+
+### Build
+
+```bash
+python build-tools/build.py
+```
+
+Produces sdist and wheel in `dist/`.
+
+### Test
+
+```bash
+python build-tools/test.py
+```
+
+Runs pytest with coverage. Use `--skip-install` if you already have the
+package installed in editable mode.
+
+### Documentation
+
+```bash
+python build-tools/docs.py
+```
+
+Builds Sphinx HTML docs into `docs-test/` (override with `--output-dir`).
+The `--build-ver` flag is accepted for CI compatibility but has no effect
+— clams-python uses unversioned documentation.
+
+### Versioning
+
+Versions are derived automatically from git tags via `setuptools-scm`.
+There is no `VERSION` file to manage. At runtime, the version is
+accessed through `importlib.metadata`:
+
+```python
+from clams.ver import __version__
+```
+
+For a dev install without a matching tag, `setuptools-scm` generates a
+version like `1.4.1.dev20+gaf551a4e4.d20260325`.
+
+## Migration from Makefile
+
+The old `Makefile` and `setup.py` have been removed. If you are
+accustomed to the old workflow, here is a mapping:
+
+| Old command | New equivalent |
+|-------------|----------------|
+| `make package` / `python setup.py sdist` | `python build-tools/build.py` |
+| `make develop` / `python setup.py develop` | `pip install -e ".[dev]"` |
+| `make test` | `python build-tools/test.py` |
+| `make doc` | `python build-tools/docs.py` |
+| `make version` / `make devversion` | Automatic via `setuptools-scm` (tag-based) |
+| `make clean` | `python build-tools/clean.py` |
+| `make publish` | `python build-tools/publish.py` |

MANIFEST.in

@@ -0,0 +1,54 @@
+"""
+Build the clams-python package.
+
+Installs dependencies and runs `python -m build` to produce sdist + wheel.
+"""
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).parent
+
+
+def run_command(command, cwd=None, check=True):
+    """Helper to run a shell command."""
+    print(f"Running: {' '.join(str(c) for c in command)}")
+    result = subprocess.run(command, cwd=cwd)
+    if check and result.returncode != 0:
+        print(
+            f"Error: Command failed with exit code "
+            f"{result.returncode}"
+        )
+        sys.exit(result.returncode)
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Build the clams-python package."
+    )
+    parser.parse_args()
+
+    project_root = SCRIPT_DIR.parent
+
+    # Install dev + build dependencies
+    print("--- Installing dependencies ---")
+    run_command(
+        [sys.executable, "-m", "pip",
+         "install", "-e", ".[dev]", "build"],
+        cwd=project_root,
+    )
+
+    # Build sdist + wheel
+    print("\n--- Building sdist + wheel ---")
+    run_command(
+        [sys.executable, "-m", "build"],
+        cwd=project_root,
+    )
+
+    print("\nBuild complete. Output in: dist/")
+
+
+if __name__ == "__main__":
+    main()

Makefile

@@ -0,0 +1,70 @@
+"""
+Clean build artifacts, caches, and generated files.
+
+Replaces ``make clean`` / ``make distclean`` from the old Makefile.
+"""
+import argparse
+import shutil
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).parent
+PROJECT_ROOT = SCRIPT_DIR.parent
+
+# Directories to remove
+CLEAN_DIRS = [
+    "build", "dist", "*.egg-info", "clams_python-*",
+    ".pytest_cache", ".pytype", ".hypothesis",
+    "tests/.hypothesis", "htmlcov",
+    "docs-test",
+]
+
+# Files to remove
+CLEAN_FILES = [
+    "coverage.xml", ".coverage",
+]
+
+# Glob patterns for recursive removal
+CLEAN_GLOBS = [
+    "**/__pycache__",
+]
+
+
+def clean(root: Path):
+    removed = []
+
+    for pattern in CLEAN_DIRS:
+        for p in root.glob(pattern):
+            if p.is_dir():
+                shutil.rmtree(p)
+                removed.append(str(p.relative_to(root)))
+
+    for name in CLEAN_FILES:
+        p = root / name
+        if p.exists():
+            p.unlink()
+            removed.append(str(p.relative_to(root)))
+
+    for pattern in CLEAN_GLOBS:
+        for p in root.glob(pattern):
+            if p.is_dir():
+                shutil.rmtree(p)
+                removed.append(str(p.relative_to(root)))
+
+    if removed:
+        print(f"Removed {len(removed)} items:")
+        for item in sorted(removed):
+            print(f"  {item}")
+    else:
+        print("Nothing to clean.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Clean build artifacts and caches."
+    )
+    parser.parse_args()
+    clean(PROJECT_ROOT)
+
+
+if __name__ == "__main__":
+    main()