juniper-ci-tools 0.1.0__tar.gz

juniper_ci_tools-0.1.0/LICENSE

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

juniper_ci_tools-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: juniper-ci-tools
+Version: 0.1.0
+Summary: Shared CI / build tooling for the Juniper ML platform (dependency-documentation generator with YAML-safe conda export)
+Author: Paul Calnon
+License: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-ml
+Project-URL: Repository, https://github.com/pcalnon/juniper-ml
+Project-URL: Issues, https://github.com/pcalnon/juniper-ml/issues
+Keywords: juniper,ci,dependency-documentation,conda,pip
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Dynamic: license-file
+
+<!-- markdownlint-disable -->
+
+# juniper-ci-tools
+
+Shared CI / build tooling for the [Juniper ML platform](https://github.com/pcalnon/juniper-ml).
+
+This package is the **single source of truth** for the dependency-documentation
+generator that historically lived as `scripts/generate_dep_docs.sh` (or
+`util/generate_dep_docs.sh`) in every Juniper repo. Three variants of that
+script drifted on `origin/main`; the 2026-05-20 bug fix in
+[juniper-cascor#276](https://github.com/pcalnon/juniper-cascor/pull/276)
+(switching the conda-dependency extraction from `sed` to `awk` to avoid
+emitting an invalid trailing `prefix:` / `variables:` key) shipped in 1 of 8
+repos. This package distributes that fix as `pip install`-able tooling so it
+cannot drift again.
+
+This work mirrors the
+[`juniper-doc-tools` PyPI migration plan](https://github.com/pcalnon/juniper-ml/blob/main/notes/JUNIPER_DOC_TOOLS_PYPI_MIGRATION_PLAN_2026-05-18.md)
+that addressed the analogous 2026-05-18 doc-link validator incident.
+
+## Installation
+
+```bash
+pip install juniper-ci-tools
+```
+
+This installs the `juniper-generate-dep-docs` console script. The package
+requires Python 3.11 or newer and depends on PyYAML.
+
+## Usage
+
+Run from the root of any Juniper repo that has a `pyproject.toml`:
+
+```bash
+juniper-generate-dep-docs
+```
+
+Equivalent module form:
+
+```bash
+python -m juniper_ci_tools
+```
+
+This will:
+
+1. Create `conf/` if needed.
+2. Back up any existing `conf/requirements_ci.txt` with a timestamp infix.
+3. Render `notes/PIP_DEPENDENCY_FILE_HEADER.md` (substituting placeholders
+   like `<X.Y.Z ...>`, `<YYYY-MM-dd ...>`, `<Python Version>`, `<Pip Version>`)
+   and append `pip list --format=freeze` output.
+4. If `conda` is on `PATH`: back up any existing
+   `conf/conda_environment_ci.yaml`, render
+   `notes/CONDA_DEPENDENCY_FILE_HEADER.md`, append the dependency block
+   extracted from `conda env export --no-builds` (using the awk-equivalent
+   logic that produces valid YAML), and validate the result with
+   `yaml.safe_load`.
+
+If conda is not available the conda step is skipped with a warning (matches
+the legacy bash script). If the generated YAML fails to parse, the command
+exits non-zero.
+
+### CLI options
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--repo-root` | cwd | Repo root containing `pyproject.toml` |
+| `--conf-dir` | `conf` | Output directory |
+| `--notes-dir` | `notes` | Directory containing header templates |
+| `--pip-header` | `PIP_DEPENDENCY_FILE_HEADER.md` | Pip header template filename |
+| `--conda-header` | `CONDA_DEPENDENCY_FILE_HEADER.md` | Conda header template filename |
+| `--pip-filename` | `requirements_ci.txt` | Pip output filename |
+| `--conda-filename` | `conda_environment_ci.yaml` | Conda output filename |
+| `--no-conda` | off | Skip conda generation even if conda is installed |
+| `--no-yaml-validation` | off | Skip `yaml.safe_load` on generated conda file |
+
+## Library API
+
+```python
+from juniper_ci_tools import generate_dep_docs
+
+result = generate_dep_docs(repo_root="/path/to/repo")
+print(result.pip_file, result.conda_file, result.yaml_validated)
+```
+
+See the package's `juniper_ci_tools/generate_dep_docs.py` docstring for the
+full surface.
+
+## Development
+
+```bash
+cd juniper-ci-tools
+pip install -e ".[test]"
+pytest
+```
+
+## License
+
+MIT. Copyright (c) 2024-2026 Paul Calnon.

juniper_ci_tools-0.1.0/README.md

@@ -0,0 +1,98 @@
+<!-- markdownlint-disable -->
+
+# juniper-ci-tools
+
+Shared CI / build tooling for the [Juniper ML platform](https://github.com/pcalnon/juniper-ml).
+
+This package is the **single source of truth** for the dependency-documentation
+generator that historically lived as `scripts/generate_dep_docs.sh` (or
+`util/generate_dep_docs.sh`) in every Juniper repo. Three variants of that
+script drifted on `origin/main`; the 2026-05-20 bug fix in
+[juniper-cascor#276](https://github.com/pcalnon/juniper-cascor/pull/276)
+(switching the conda-dependency extraction from `sed` to `awk` to avoid
+emitting an invalid trailing `prefix:` / `variables:` key) shipped in 1 of 8
+repos. This package distributes that fix as `pip install`-able tooling so it
+cannot drift again.
+
+This work mirrors the
+[`juniper-doc-tools` PyPI migration plan](https://github.com/pcalnon/juniper-ml/blob/main/notes/JUNIPER_DOC_TOOLS_PYPI_MIGRATION_PLAN_2026-05-18.md)
+that addressed the analogous 2026-05-18 doc-link validator incident.
+
+## Installation
+
+```bash
+pip install juniper-ci-tools
+```
+
+This installs the `juniper-generate-dep-docs` console script. The package
+requires Python 3.11 or newer and depends on PyYAML.
+
+## Usage
+
+Run from the root of any Juniper repo that has a `pyproject.toml`:
+
+```bash
+juniper-generate-dep-docs
+```
+
+Equivalent module form:
+
+```bash
+python -m juniper_ci_tools
+```
+
+This will:
+
+1. Create `conf/` if needed.
+2. Back up any existing `conf/requirements_ci.txt` with a timestamp infix.
+3. Render `notes/PIP_DEPENDENCY_FILE_HEADER.md` (substituting placeholders
+   like `<X.Y.Z ...>`, `<YYYY-MM-dd ...>`, `<Python Version>`, `<Pip Version>`)
+   and append `pip list --format=freeze` output.
+4. If `conda` is on `PATH`: back up any existing
+   `conf/conda_environment_ci.yaml`, render
+   `notes/CONDA_DEPENDENCY_FILE_HEADER.md`, append the dependency block
+   extracted from `conda env export --no-builds` (using the awk-equivalent
+   logic that produces valid YAML), and validate the result with
+   `yaml.safe_load`.
+
+If conda is not available the conda step is skipped with a warning (matches
+the legacy bash script). If the generated YAML fails to parse, the command
+exits non-zero.
+
+### CLI options
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--repo-root` | cwd | Repo root containing `pyproject.toml` |
+| `--conf-dir` | `conf` | Output directory |
+| `--notes-dir` | `notes` | Directory containing header templates |
+| `--pip-header` | `PIP_DEPENDENCY_FILE_HEADER.md` | Pip header template filename |
+| `--conda-header` | `CONDA_DEPENDENCY_FILE_HEADER.md` | Conda header template filename |
+| `--pip-filename` | `requirements_ci.txt` | Pip output filename |
+| `--conda-filename` | `conda_environment_ci.yaml` | Conda output filename |
+| `--no-conda` | off | Skip conda generation even if conda is installed |
+| `--no-yaml-validation` | off | Skip `yaml.safe_load` on generated conda file |
+
+## Library API
+
+```python
+from juniper_ci_tools import generate_dep_docs
+
+result = generate_dep_docs(repo_root="/path/to/repo")
+print(result.pip_file, result.conda_file, result.yaml_validated)
+```
+
+See the package's `juniper_ci_tools/generate_dep_docs.py` docstring for the
+full surface.
+
+## Development
+
+```bash
+cd juniper-ci-tools
+pip install -e ".[test]"
+pytest
+```
+
+## License
+
+MIT. Copyright (c) 2024-2026 Paul Calnon.

juniper_ci_tools-0.1.0/juniper_ci_tools/__init__.py

@@ -0,0 +1,36 @@
+"""``juniper-ci-tools`` -- shared CI / build tooling for the Juniper ecosystem.
+
+Single-source-of-truth Python package for the dependency-documentation
+generator that historically lived as a standalone
+``scripts/generate_dep_docs.sh`` in every Juniper repo. Three variants drifted
+on origin/main; the cascor 2026-05-20 bug fix (sed -> awk for YAML extraction)
+shipped to 1 of 8 repos. This package replaces all of them with a single
+PyPI-distributed implementation that survives single-repo CI checkouts and
+cannot drift.
+
+The public API is:
+
+- :class:`GenerateResult` -- structured outcome of a generation run.
+- :func:`generate_dep_docs` -- ergonomic library entry point.
+
+For CLI usage, install the package and run :program:`juniper-generate-dep-docs`
+or ``python -m juniper_ci_tools``; the CLI surface is in :mod:`cli`.
+
+See ``notes/JUNIPER_CI_TOOLS_PYPI_MIGRATION_PLAN_2026-05-20.md`` in the
+juniper-ml repo for the design rationale, the incident-class motivation
+(mirroring the 2026-05-18 doc-link validator incident), and the wave plan.
+"""
+
+from juniper_ci_tools._version import __version__
+from juniper_ci_tools.generate_dep_docs import (
+    GenerateResult,
+    generate_dep_docs,
+    render_header,
+)
+
+__all__ = [
+    "__version__",
+    "GenerateResult",
+    "generate_dep_docs",
+    "render_header",
+]

juniper_ci_tools-0.1.0/juniper_ci_tools/__main__.py

@@ -0,0 +1,13 @@
+"""``python -m juniper_ci_tools`` entry point.
+
+Provides the module-form invocation alongside the
+``juniper-generate-dep-docs`` console script (mirrors the doc-tools pattern).
+Both route through :func:`cli.main` so they cannot diverge.
+"""
+
+import sys
+
+from juniper_ci_tools.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

juniper_ci_tools-0.1.0/juniper_ci_tools/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0"

juniper_ci_tools-0.1.0/juniper_ci_tools/cli.py

@@ -0,0 +1,118 @@
+"""Command-line entry point for :program:`juniper-generate-dep-docs`.
+
+Wraps :func:`juniper_ci_tools.generate_dep_docs.generate_dep_docs` with
+argparse and printed progress output that mirrors the legacy bash script's
+banner. Supports two invocation forms:
+
+- ``juniper-generate-dep-docs [args]`` (console script, see :file:`pyproject.toml`)
+- ``python -m juniper_ci_tools [args]`` (module form, see :mod:`__main__`)
+
+Both route through :func:`main`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from juniper_ci_tools._version import __version__
+from juniper_ci_tools.generate_dep_docs import (
+    GenerateDepDocsError,
+    YamlValidationError,
+    generate_dep_docs,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="juniper-generate-dep-docs",
+        description=("Generate conf/requirements_ci.txt and conf/conda_environment_ci.yaml for a Juniper repo. Replaces the legacy scripts/generate_dep_docs.sh that drifted across 8 repos."),
+    )
+    parser.add_argument("--repo-root", type=Path, default=None, help="Repo root containing pyproject.toml (default: cwd).")
+    parser.add_argument("--conf-dir", default="conf", help="Output directory for generated files (default: conf).")
+    parser.add_argument("--notes-dir", default="notes", help="Directory containing header templates (default: notes).")
+    parser.add_argument("--pip-header", default="PIP_DEPENDENCY_FILE_HEADER.md", help="Pip-requirements header template filename (in --notes-dir).")
+    parser.add_argument("--conda-header", default="CONDA_DEPENDENCY_FILE_HEADER.md", help="Conda-environment header template filename (in --notes-dir).")
+    parser.add_argument("--pip-filename", default="requirements_ci.txt", help="Output filename for pip requirements (in --conf-dir).")
+    parser.add_argument("--conda-filename", default="conda_environment_ci.yaml", help="Output filename for conda environment (in --conf-dir).")
+    parser.add_argument("--no-conda", action="store_true", help="Skip conda_environment_ci.yaml generation even if conda is available.")
+    parser.add_argument("--no-yaml-validation", action="store_true", help="Skip the post-write YAML validation of the conda environment file.")
+    parser.add_argument("--version", action="version", version="juniper-generate-dep-docs {}".format(__version__))
+    return parser
+
+
+def _print_banner(args: argparse.Namespace, *, repo_version: str, python_version: str, pip_version: str, timestamp: str) -> None:
+    bar = "═" * 60
+    print("╔{}╗".format(bar))
+    print("║       Juniper - Generate Dependency Documentation          ║")
+    print("╚{}╝".format(bar))
+    print()
+    print("  Repo Version:   {}".format(repo_version))
+    print("  Python Version: {}".format(python_version))
+    print("  Pip Version:    {}".format(pip_version))
+    print("  Timestamp:      {}".format(timestamp))
+    print()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        # Detect versions early so we can print the banner even if the
+        # generation step fails on something later. We re-detect inside
+        # generate_dep_docs() so the result remains the source of truth.
+        from juniper_ci_tools.generate_dep_docs import (
+            _detect_pip_version,
+            _detect_python_version,
+            _now,
+            _read_pyproject_version,
+        )
+
+        root = Path(args.repo_root) if args.repo_root is not None else Path.cwd()
+        repo_version = _read_pyproject_version(root)
+        python_version = _detect_python_version()
+        pip_version = _detect_pip_version()
+        ts = _now().strftime("%Y-%m-%d_%H-%M-%S")
+        _print_banner(args, repo_version=repo_version, python_version=python_version, pip_version=pip_version, timestamp=ts)
+
+        result = generate_dep_docs(
+            repo_root=args.repo_root,
+            conf_dir=args.conf_dir,
+            notes_dir=args.notes_dir,
+            pip_header_name=args.pip_header,
+            conda_header_name=args.conda_header,
+            pip_filename=args.pip_filename,
+            conda_filename=args.conda_filename,
+            include_conda=not args.no_conda,
+            validate_yaml=not args.no_yaml_validation,
+        )
+
+        if result.pip_backup is not None:
+            print("  Backing up existing pip requirements to: {}".format(result.pip_backup))
+        print("  Generated: {}".format(result.pip_file))
+
+        if result.conda_file is not None:
+            if result.conda_backup is not None:
+                print("  Backing up existing conda environment to: {}".format(result.conda_backup))
+            if result.yaml_validated:
+                print("  Validated: {} YAML syntax OK".format(result.conda_file))
+            print("  Generated: {}".format(result.conda_file))
+        elif result.conda_skipped_reason:
+            print("  WARNING: {}".format(result.conda_skipped_reason))
+            print("           Install miniforge/miniconda to generate conda_environment_ci.yaml")
+
+        print()
+        print("  Dependency documentation generation complete.")
+        return 0
+    except YamlValidationError as exc:
+        print("  ERROR: {}".format(exc), file=sys.stderr)
+        return 1
+    except GenerateDepDocsError as exc:
+        print("  ERROR: {}".format(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())