esys-lpip 0.1.1__tar.gz

esys_lpip-0.1.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: esys-lpip
+Version: 0.1.1
+Summary: Git-backed, name-oriented front end to pip for internal Python packages
+Author: Project maintainers
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: tomlkit>=0.11
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+
+# lpip
+
+Git-backed, name-oriented front end to `pip` for internal Python packages —
+no internal PyPI registry required.
+
+Install from PyPI as **`esys-lpip`** (`pip install esys-lpip`); the command
+and import remain **`lpip`**.
+
+## Status
+
+| Item | Value |
+|------|-------|
+| Workflow | A2C 0.10.0 ([ADR-0000](docs/adr/0000-adopt-a2c-workflow.md)) |
+| Profile | `python-pypi` |
+| Product | Architecture, ADRs, ASRs, and ACs are Accepted; CLI not implemented yet (`src/lpip` is a version stub) |
+
+## What this is
+
+`lpip` (**local-pip**) resolves a logical package name from a TOML catalog
+(`lpip-sources.toml`), validates configuration and prerequisites, and delegates
+installation to `python -m pip install ...`. The catalog may be a local file
+or a Git-backed checkout in a persistent user cache.
+
+It is a small client, not a package manager replacement, registry, or service
+([ADR-0001](docs/adr/0001-pip-delegation.md),
+[ADR-0004](docs/adr/0004-cli-first-no-service.md)).
+
+## Non-goals (v1)
+
+- Internal package index or hosted registry
+- A dependency resolver other than pip
+- Background daemons, lockfile solving, or workspace orchestration
+
+## Quick start
+
+The installable CLI is not available yet. After clone:
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# Unix: source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Re-run `scripts/setup-dev` after clone if you need pre-commit and gitlint
+hooks (see [docs/workflow/adoption.md](docs/workflow/adoption.md)).
+
+## Intended configuration
+
+Local catalog:
+
+```toml
+[source]
+type = "file"
+path = "~/company/lpip-sources.toml"
+```
+
+Git-backed catalog:
+
+```toml
+[source]
+type = "git"
+url = "ssh://git.company/dev/lpip-catalog.git"
+revision = "main"
+path = "lpip-sources.toml"
+refresh = "auto"
+```
+
+Example catalog entry:
+
+```toml
+[packages.libfoo]
+url = "git+ssh://git.company/libs/libfoo.git"
+revision = "main"
+subdirectory = "python"
+```
+
+Intended commands (not implemented): `lpip install`, `lpip list`,
+`lpip show`, `lpip validate`, `lpip doctor`, `lpip catalog …`,
+`lpip config …` (including `config init`). Details:
+[docs/architecture/cli-and-configuration.md](docs/architecture/cli-and-configuration.md).
+
+## Documentation
+
+| Topic | Location |
+|-------|----------|
+| Architecture | [docs/architecture/overview.md](docs/architecture/overview.md) |
+| Artifact chain | [docs/workflow/documentation-structure.md](docs/workflow/documentation-structure.md) |
+| ASRs | [docs/asr/](docs/asr/) |
+| ADRs | [docs/adr/INDEX.md](docs/adr/INDEX.md) |
+| Acceptance criteria | [docs/ac/](docs/ac/) |
+| A2C adoption | [docs/workflow/adoption.md](docs/workflow/adoption.md) |
+| Release | [docs/release-pipeline.md](docs/release-pipeline.md) |
+| Publishing | [docs/package-publishing.md](docs/package-publishing.md) |
+| GitLab CI | [docs/gitlab-ci.md](docs/gitlab-ci.md) |
+| Agent entry | [AGENTS.md](AGENTS.md) |
+
+## License
+
+MIT (`pyproject.toml`).

esys_lpip-0.1.1/README.md

@@ -0,0 +1,101 @@
+# lpip
+
+Git-backed, name-oriented front end to `pip` for internal Python packages —
+no internal PyPI registry required.
+
+Install from PyPI as **`esys-lpip`** (`pip install esys-lpip`); the command
+and import remain **`lpip`**.
+
+## Status
+
+| Item | Value |
+|------|-------|
+| Workflow | A2C 0.10.0 ([ADR-0000](docs/adr/0000-adopt-a2c-workflow.md)) |
+| Profile | `python-pypi` |
+| Product | Architecture, ADRs, ASRs, and ACs are Accepted; CLI not implemented yet (`src/lpip` is a version stub) |
+
+## What this is
+
+`lpip` (**local-pip**) resolves a logical package name from a TOML catalog
+(`lpip-sources.toml`), validates configuration and prerequisites, and delegates
+installation to `python -m pip install ...`. The catalog may be a local file
+or a Git-backed checkout in a persistent user cache.
+
+It is a small client, not a package manager replacement, registry, or service
+([ADR-0001](docs/adr/0001-pip-delegation.md),
+[ADR-0004](docs/adr/0004-cli-first-no-service.md)).
+
+## Non-goals (v1)
+
+- Internal package index or hosted registry
+- A dependency resolver other than pip
+- Background daemons, lockfile solving, or workspace orchestration
+
+## Quick start
+
+The installable CLI is not available yet. After clone:
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# Unix: source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Re-run `scripts/setup-dev` after clone if you need pre-commit and gitlint
+hooks (see [docs/workflow/adoption.md](docs/workflow/adoption.md)).
+
+## Intended configuration
+
+Local catalog:
+
+```toml
+[source]
+type = "file"
+path = "~/company/lpip-sources.toml"
+```
+
+Git-backed catalog:
+
+```toml
+[source]
+type = "git"
+url = "ssh://git.company/dev/lpip-catalog.git"
+revision = "main"
+path = "lpip-sources.toml"
+refresh = "auto"
+```
+
+Example catalog entry:
+
+```toml
+[packages.libfoo]
+url = "git+ssh://git.company/libs/libfoo.git"
+revision = "main"
+subdirectory = "python"
+```
+
+Intended commands (not implemented): `lpip install`, `lpip list`,
+`lpip show`, `lpip validate`, `lpip doctor`, `lpip catalog …`,
+`lpip config …` (including `config init`). Details:
+[docs/architecture/cli-and-configuration.md](docs/architecture/cli-and-configuration.md).
+
+## Documentation
+
+| Topic | Location |
+|-------|----------|
+| Architecture | [docs/architecture/overview.md](docs/architecture/overview.md) |
+| Artifact chain | [docs/workflow/documentation-structure.md](docs/workflow/documentation-structure.md) |
+| ASRs | [docs/asr/](docs/asr/) |
+| ADRs | [docs/adr/INDEX.md](docs/adr/INDEX.md) |
+| Acceptance criteria | [docs/ac/](docs/ac/) |
+| A2C adoption | [docs/workflow/adoption.md](docs/workflow/adoption.md) |
+| Release | [docs/release-pipeline.md](docs/release-pipeline.md) |
+| Publishing | [docs/package-publishing.md](docs/package-publishing.md) |
+| GitLab CI | [docs/gitlab-ci.md](docs/gitlab-ci.md) |
+| Agent entry | [AGENTS.md](AGENTS.md) |
+
+## License
+
+MIT (`pyproject.toml`).

esys_lpip-0.1.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "esys-lpip"
+version = "0.1.1"
+description = "Git-backed, name-oriented front end to pip for internal Python packages"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Project maintainers" }]
+dependencies = [
+  "platformdirs>=4.0",
+  "tomlkit>=0.11",
+  "typer>=0.12",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.8",
+  "pre-commit>=3.0",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+lpip = "lpip.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+markers = [
+  "integration: live venv + pip (network/build isolation)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

esys_lpip-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

esys_lpip-0.1.1/src/esys_lpip.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: esys-lpip
+Version: 0.1.1
+Summary: Git-backed, name-oriented front end to pip for internal Python packages
+Author: Project maintainers
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: tomlkit>=0.11
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+
+# lpip
+
+Git-backed, name-oriented front end to `pip` for internal Python packages —
+no internal PyPI registry required.
+
+Install from PyPI as **`esys-lpip`** (`pip install esys-lpip`); the command
+and import remain **`lpip`**.
+
+## Status
+
+| Item | Value |
+|------|-------|
+| Workflow | A2C 0.10.0 ([ADR-0000](docs/adr/0000-adopt-a2c-workflow.md)) |
+| Profile | `python-pypi` |
+| Product | Architecture, ADRs, ASRs, and ACs are Accepted; CLI not implemented yet (`src/lpip` is a version stub) |
+
+## What this is
+
+`lpip` (**local-pip**) resolves a logical package name from a TOML catalog
+(`lpip-sources.toml`), validates configuration and prerequisites, and delegates
+installation to `python -m pip install ...`. The catalog may be a local file
+or a Git-backed checkout in a persistent user cache.
+
+It is a small client, not a package manager replacement, registry, or service
+([ADR-0001](docs/adr/0001-pip-delegation.md),
+[ADR-0004](docs/adr/0004-cli-first-no-service.md)).
+
+## Non-goals (v1)
+
+- Internal package index or hosted registry
+- A dependency resolver other than pip
+- Background daemons, lockfile solving, or workspace orchestration
+
+## Quick start
+
+The installable CLI is not available yet. After clone:
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# Unix: source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Re-run `scripts/setup-dev` after clone if you need pre-commit and gitlint
+hooks (see [docs/workflow/adoption.md](docs/workflow/adoption.md)).
+
+## Intended configuration
+
+Local catalog:
+
+```toml
+[source]
+type = "file"
+path = "~/company/lpip-sources.toml"
+```
+
+Git-backed catalog:
+
+```toml
+[source]
+type = "git"
+url = "ssh://git.company/dev/lpip-catalog.git"
+revision = "main"
+path = "lpip-sources.toml"
+refresh = "auto"
+```
+
+Example catalog entry:
+
+```toml
+[packages.libfoo]
+url = "git+ssh://git.company/libs/libfoo.git"
+revision = "main"
+subdirectory = "python"
+```
+
+Intended commands (not implemented): `lpip install`, `lpip list`,
+`lpip show`, `lpip validate`, `lpip doctor`, `lpip catalog …`,
+`lpip config …` (including `config init`). Details:
+[docs/architecture/cli-and-configuration.md](docs/architecture/cli-and-configuration.md).
+
+## Documentation
+
+| Topic | Location |
+|-------|----------|
+| Architecture | [docs/architecture/overview.md](docs/architecture/overview.md) |
+| Artifact chain | [docs/workflow/documentation-structure.md](docs/workflow/documentation-structure.md) |
+| ASRs | [docs/asr/](docs/asr/) |
+| ADRs | [docs/adr/INDEX.md](docs/adr/INDEX.md) |
+| Acceptance criteria | [docs/ac/](docs/ac/) |
+| A2C adoption | [docs/workflow/adoption.md](docs/workflow/adoption.md) |
+| Release | [docs/release-pipeline.md](docs/release-pipeline.md) |
+| Publishing | [docs/package-publishing.md](docs/package-publishing.md) |
+| GitLab CI | [docs/gitlab-ci.md](docs/gitlab-ci.md) |
+| Agent entry | [AGENTS.md](AGENTS.md) |
+
+## License
+
+MIT (`pyproject.toml`).

esys_lpip-0.1.1/src/esys_lpip.egg-info/SOURCES.txt

@@ -0,0 +1,34 @@
+README.md
+pyproject.toml
+src/esys_lpip.egg-info/PKG-INFO
+src/esys_lpip.egg-info/SOURCES.txt
+src/esys_lpip.egg-info/dependency_links.txt
+src/esys_lpip.egg-info/entry_points.txt
+src/esys_lpip.egg-info/requires.txt
+src/esys_lpip.egg-info/top_level.txt
+src/lpip/__init__.py
+src/lpip/cache.py
+src/lpip/catalog.py
+src/lpip/cli.py
+src/lpip/config.py
+src/lpip/errors.py
+src/lpip/gitutils.py
+src/lpip/models.py
+src/lpip/pipwrap.py
+src/lpip/validation.py
+tests/test_cache.py
+tests/test_catalog.py
+tests/test_cli.py
+tests/test_cli_catalog.py
+tests/test_cli_config.py
+tests/test_cli_doctor.py
+tests/test_config.py
+tests/test_errors.py
+tests/test_gitutils.py
+tests/test_install_git_catalog_integration.py
+tests/test_install_integration.py
+tests/test_models.py
+tests/test_pipwrap.py
+tests/test_registry_publish.py
+tests/test_smoke.py
+tests/test_url_normalize.py

esys_lpip-0.1.1/src/esys_lpip.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

esys_lpip-0.1.1/src/esys_lpip.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lpip = lpip.cli:main

esys_lpip-0.1.1/src/esys_lpip.egg-info/requires.txt

@@ -0,0 +1,8 @@
+platformdirs>=4.0
+tomlkit>=0.11
+typer>=0.12
+
+[dev]
+pytest>=8.0
+ruff>=0.8
+pre-commit>=3.0

esys_lpip-0.1.1/src/esys_lpip.egg-info/top_level.txt

@@ -0,0 +1 @@
+lpip

esys_lpip-0.1.1/src/lpip/__init__.py

@@ -0,0 +1,3 @@
+"""lpip — installable package."""
+
+__version__ = "0.1.1"

esys_lpip-0.1.1/src/lpip/cache.py

@@ -0,0 +1,164 @@
+"""Persistent Git catalog cache and auto-refresh TTL (ADR-0003, ADR-0012)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import stat
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from lpip.config import default_user_cache_dir
+from lpip.gitutils import git_checkout, git_clone, git_fetch
+from lpip.models import RefreshMode
+
+AUTO_REFRESH_TTL = timedelta(hours=24)
+_METADATA_NAME = "metadata.json"
+_LAST_SUCCESS_KEY = "last_success"
+
+
+@dataclass(frozen=True)
+class CatalogCachePaths:
+    root: Path
+    repo: Path
+    metadata: Path
+
+
+def catalog_identity_hash(url: str, revision: str | None) -> str:
+    payload = f"{url}\n{revision or ''}".encode()
+    return hashlib.sha256(payload).hexdigest()
+
+
+def catalog_cache_paths(
+    url: str,
+    revision: str | None,
+    *,
+    cache_home: Path | None = None,
+) -> CatalogCachePaths:
+    home = cache_home if cache_home is not None else default_user_cache_dir()
+    root = home / "catalogs" / catalog_identity_hash(url, revision)
+    return CatalogCachePaths(root=root, repo=root / "repo", metadata=root / _METADATA_NAME)
+
+
+def read_last_success(paths: CatalogCachePaths) -> datetime | None:
+    if not paths.metadata.is_file():
+        return None
+    try:
+        data = json.loads(paths.metadata.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    raw = data.get(_LAST_SUCCESS_KEY)
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed
+
+
+def write_last_success(paths: CatalogCachePaths, when: datetime | None = None) -> None:
+    """Record last successful clone/fetch. Call only after Git succeeds."""
+    stamp = when or datetime.now(UTC)
+    if stamp.tzinfo is None:
+        stamp = stamp.replace(tzinfo=UTC)
+    payload: dict[str, object] = {}
+    if paths.metadata.is_file():
+        try:
+            loaded = json.loads(paths.metadata.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                payload = loaded
+        except (OSError, json.JSONDecodeError):
+            payload = {}
+    payload[_LAST_SUCCESS_KEY] = stamp.isoformat()
+    paths.root.mkdir(parents=True, exist_ok=True)
+    paths.metadata.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def needs_auto_refresh(
+    paths: CatalogCachePaths,
+    *,
+    now: datetime | None = None,
+) -> bool:
+    """True if timestamp is missing or older than 24 hours (ADR-0012)."""
+    last = read_last_success(paths)
+    if last is None:
+        return True
+    clock = now or datetime.now(UTC)
+    if clock.tzinfo is None:
+        clock = clock.replace(tzinfo=UTC)
+    return clock - last >= AUTO_REFRESH_TTL
+
+
+def should_fetch(
+    paths: CatalogCachePaths,
+    refresh: RefreshMode,
+    *,
+    force: bool = False,
+    now: datetime | None = None,
+) -> bool:
+    """Whether to fetch an existing checkout. Absent cache is always cloned."""
+    if force or refresh is RefreshMode.ALWAYS:
+        return True
+    if refresh is RefreshMode.NEVER:
+        return False
+    return needs_auto_refresh(paths, now=now)
+
+
+def _repo_ready(repo: Path) -> bool:
+    git_dir = repo / ".git"
+    return git_dir.is_dir() or git_dir.is_file()
+
+
+def ensure_catalog_checkout(
+    url: str,
+    revision: str | None,
+    *,
+    cache_home: Path | None = None,
+    refresh: RefreshMode = RefreshMode.AUTO,
+    force_refresh: bool = False,
+    now: datetime | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> CatalogCachePaths:
+    """Clone if missing; fetch per refresh policy; stamp only on Git success."""
+    paths = catalog_cache_paths(url, revision, cache_home=cache_home)
+    if not _repo_ready(paths.repo):
+        git_clone(url, paths.repo, environ=environ)
+        write_last_success(paths, now)
+        if revision:
+            git_checkout(paths.repo, revision, environ=environ)
+        return paths
+
+    if should_fetch(paths, refresh, force=force_refresh, now=now):
+        git_fetch(paths.repo, environ=environ)
+        write_last_success(paths, now)
+    if revision:
+        git_checkout(paths.repo, revision, environ=environ)
+    return paths
+
+
+def _rmtree(path: Path) -> None:
+    def _onerror(func: object, name: str, _exc: object) -> None:
+        os.chmod(name, stat.S_IWRITE)
+        func(name)  # type: ignore[operator]
+
+    shutil.rmtree(path, onerror=_onerror)
+
+
+def purge_catalog_cache(
+    url: str,
+    revision: str | None,
+    *,
+    cache_home: Path | None = None,
+) -> CatalogCachePaths:
+    """Remove the cache directory for this catalog identity."""
+    paths = catalog_cache_paths(url, revision, cache_home=cache_home)
+    if paths.root.exists():
+        _rmtree(paths.root)
+    return paths