docker-devtools 0.0.1__py3-none-win_amd64.whl

docker_devtools/__init__.py

@@ -0,0 +1,198 @@
+"""Work on the Dockerfiles, Compose files and build context in a repository.
+
+This package bundles the ``docker-devtools`` binary and wraps its JSON output in
+typed dataclasses. The work happens in Go, against the same libraries BuildKit
+uses, so the results match what ``docker build`` would do.
+
+    >>> from docker_devtools import image_ls
+    >>> for ref in image_ls("testdata").refs:
+    ...     print(ref.path, ref.line, ref.raw)
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from dataclasses import field
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Literal
+
+from docker_devtools._find import BINARY_ENV_VAR
+from docker_devtools._find import BINARY_NAME
+from docker_devtools._find import BinaryNotFoundError
+from docker_devtools._find import find_binary
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = [
+    "BINARY_ENV_VAR",
+    "BINARY_NAME",
+    "IMAGE_SCHEMA_VERSION",
+    "BinaryNotFoundError",
+    "Change",
+    "ImageRef",
+    "ImageResult",
+    "UpdateReport",
+    "find_binary",
+    "image_ls",
+    "image_update",
+]
+
+#: The image-scan schema this wrapper understands. A mismatch means the binary
+#: and the Python half are out of step.
+IMAGE_SCHEMA_VERSION = 1
+
+TagPolicy = Literal["same-pattern", "minor", "patch", "latest"]
+
+
+@dataclass(frozen=True)
+class ImageRef:
+    """One image reference and where it sits."""
+
+    path: str
+    line: int
+    kind: str
+    raw: str
+    resolved: bool
+    registry: str | None = None
+    repository: str | None = None
+    tag: str | None = None
+    digest: str | None = None
+    stage: str | None = None
+    note: str | None = None
+
+
+@dataclass(frozen=True)
+class ImageResult:
+    """Every reference found by a scan."""
+
+    schema: int
+    refs: tuple[ImageRef, ...]
+    warnings: tuple[str, ...] = ()
+
+    def resolved(self) -> tuple[ImageRef, ...]:
+        """Return only the references that name a real image."""
+        return tuple(r for r in self.refs if r.resolved)
+
+
+@dataclass(frozen=True)
+class Change:
+    """One reference an update would rewrite."""
+
+    path: str
+    line: int
+    old: str
+    new: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class UpdateReport:
+    """The plan an update produced."""
+
+    schema: int
+    changes: tuple[Change, ...]
+    skipped: int = 0
+    warnings: tuple[str, ...] = field(default=())
+
+
+def image_ls(*paths: str) -> ImageResult:
+    """List every image reference under ``paths``.
+
+    Args:
+        paths: files or directories. Defaults to the working directory.
+
+    Returns:
+        The parsed scan.
+    """
+    data = _run(["image", "ls", "--json", *paths])
+    _check_schema(data.get("schema"))
+    return ImageResult(
+        schema=data["schema"],
+        refs=tuple(
+            ImageRef(
+                path=r["path"],
+                line=r["line"],
+                kind=r["kind"],
+                raw=r["raw"],
+                resolved=r["resolved"],
+                registry=r.get("registry"),
+                repository=r.get("repository"),
+                tag=r.get("tag"),
+                digest=r.get("digest"),
+                stage=r.get("stage"),
+                note=r.get("note"),
+            )
+            for r in data["refs"]
+        ),
+        warnings=tuple(data.get("warnings") or ()),
+    )
+
+
+def image_update(
+    *paths: str,
+    pin_digest: bool = False,
+    tag_policy: TagPolicy | None = None,
+    dry_run: bool = True,
+) -> UpdateReport:
+    """Plan, and optionally apply, changes to image references.
+
+    ``dry_run`` defaults to True so that calling this by accident cannot
+    rewrite a repository.
+
+    Args:
+        paths: files or directories. Defaults to the working directory.
+        pin_digest: append or refresh the ``@sha256`` digest.
+        tag_policy: how far a tag may move. None leaves tags alone.
+        dry_run: report without writing.
+
+    Returns:
+        The plan, whether or not it was applied.
+    """
+    args = ["image", "update", "--json"]
+    if pin_digest:
+        args.append("--pin-digest")
+    if tag_policy is not None:
+        args += ["--tag-policy", tag_policy]
+    if dry_run:
+        args.append("--dry-run")
+    args += list(paths)
+
+    data = _run(args)
+    _check_schema(data.get("schema"))
+    return UpdateReport(
+        schema=data["schema"],
+        changes=tuple(
+            Change(path=c["path"], line=c["line"], old=c["old"], new=c["new"], reason=c["reason"])
+            for c in data["changes"]
+        ),
+        skipped=data.get("skipped", 0),
+        warnings=tuple(data.get("warnings") or ()),
+    )
+
+
+def _run(args: Sequence[str]) -> dict[str, Any]:
+    binary = find_binary()
+    proc = subprocess.run(  # noqa: S603
+        [binary, *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        msg = f"{BINARY_NAME} {' '.join(args)} failed: {proc.stderr.strip()}"
+        raise RuntimeError(msg)
+    result: dict[str, Any] = json.loads(proc.stdout)
+    return result
+
+
+def _check_schema(schema: object) -> None:
+    if schema != IMAGE_SCHEMA_VERSION:
+        msg = (
+            f"{BINARY_NAME} emitted schema {schema!r}, but this package understands "
+            f"{IMAGE_SCHEMA_VERSION}. The binary and the Python wrapper are out of step."
+        )
+        raise RuntimeError(msg)

docker_devtools/__main__.py

@@ -0,0 +1,33 @@
+"""Run the bundled binary via ``python -m docker_devtools``.
+
+The binary is normally on PATH already, since the wheel installs it into the
+environment's scripts directory. This module exists for the cases where it is
+not, such as an environment whose scripts directory is not on PATH.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+from docker_devtools._find import find_binary
+
+
+def _run() -> None:
+    binary = find_binary()
+    if sys.platform == "win32":
+        # Windows has no exec that replaces the process cleanly, and a
+        # KeyboardInterrupt here would print a traceback over the child's own
+        # output.
+        try:
+            completed = subprocess.run([binary, *sys.argv[1:]], check=False)  # noqa: S603
+        except KeyboardInterrupt:
+            sys.exit(130)
+        sys.exit(completed.returncode)
+    else:
+        os.execv(binary, [binary, *sys.argv[1:]])  # noqa: S606
+
+
+if __name__ == "__main__":
+    _run()

docker_devtools/_find.py

@@ -0,0 +1,116 @@
+"""Locate the bundled docker-devtools binary.
+
+The search order is adapted from Astral's ``uv`` package (``python/uv/_find_uv.py``,
+MIT OR Apache-2.0). The binary ships in the wheel's ``.data/scripts`` directory,
+which installs into the environment's scripts directory rather than next to this
+module, and that directory moves depending on how the wheel was installed --
+``pip install --target``, ``--prefix``, the user scheme, or ``uv run --with``.
+A naive ``os.path.dirname(__file__)`` lookup gets all of those wrong.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import sysconfig
+from fnmatch import fnmatch
+
+BINARY_NAME = "docker-devtools"
+
+#: Set this to an absolute path to use a specific binary instead of searching.
+#: Useful when running against a locally built binary, and as an escape hatch
+#: for install layouts the search below does not anticipate.
+BINARY_ENV_VAR = "DOCKER_DEVTOOLS_BINARY"
+
+
+class BinaryNotFoundError(FileNotFoundError):
+    """The bundled binary could not be located."""
+
+
+def find_binary() -> str:
+    """Return the path to the bundled docker-devtools binary.
+
+    Raises:
+        BinaryNotFoundError: if no candidate directory holds the binary.
+    """
+    override = os.environ.get(BINARY_ENV_VAR)
+    if override:
+        if not os.path.isfile(override):
+            msg = f"{BINARY_ENV_VAR} points at {override!r}, which is not a file"
+            raise BinaryNotFoundError(msg)
+        return override
+
+    exe = BINARY_NAME + (sysconfig.get_config_var("EXE") or "")
+
+    targets = [
+        # The scripts directory for the current interpreter.
+        sysconfig.get_path("scripts"),
+        # The scripts directory for the base prefix, for virtualenvs.
+        sysconfig.get_path("scripts", vars={"base": sys.base_prefix}),
+        # Above the package root, e.g. `pip install --prefix` or `uv run --with`.
+        (
+            _join(
+                _matching_parents(_module_path(), "Lib/site-packages/docker_devtools"),
+                "Scripts",
+            )
+            if sys.platform == "win32"
+            else _join(
+                _matching_parents(_module_path(), "lib/python*/site-packages/docker_devtools"),
+                "bin",
+            )
+        ),
+        # Adjacent to the package root, e.g. `pip install --target`.
+        _join(_matching_parents(_module_path(), "docker_devtools"), "bin"),
+        _matching_parents(_module_path(), "docker_devtools"),
+        # The user scheme's scripts directory, e.g. `~/.local/bin`.
+        sysconfig.get_path("scripts", scheme=_user_scheme()),
+    ]
+
+    seen: list[str] = []
+    for target in targets:
+        if not target or target in seen:
+            continue
+        seen.append(target)
+        path = os.path.join(target, exe)
+        if os.path.isfile(path):
+            return path
+
+    locations = "\n".join(f" - {target}" for target in seen)
+    msg = f"Could not find the {BINARY_NAME} binary in any of:\n{locations}\n"
+    raise BinaryNotFoundError(msg)
+
+
+def _module_path() -> str:
+    return os.path.dirname(__file__)
+
+
+def _matching_parents(path: str | None, match: str) -> str | None:
+    """Trim ``match`` off the end of ``path`` and return what is left.
+
+    ``match`` uses ``/`` separators and may contain ``*`` wildcards; ``path``
+    uses the platform separator. Components compare case-insensitively.
+    """
+    if not path:
+        return None
+    parts = path.split(os.sep)
+    match_parts = match.split("/")
+    if len(parts) < len(match_parts):
+        return None
+    if not all(
+        fnmatch(part, match_part)
+        for part, match_part in zip(reversed(parts), reversed(match_parts), strict=False)
+    ):
+        return None
+    return os.sep.join(parts[: -len(match_parts)])
+
+
+def _join(path: str | None, *parts: str) -> str | None:
+    if not path:
+        return None
+    return os.path.join(path, *parts)
+
+
+def _user_scheme() -> str:
+    # uv's original branches on sys.version_info here because it supports 3.8.
+    # This package requires 3.10, where get_preferred_scheme always exists.
+    return sysconfig.get_preferred_scheme("user")

docker_devtools/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

docker_devtools-0.0.1.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: docker-devtools
+Version: 0.0.1
+Summary: Work on the Dockerfiles, Compose files and build context in a repository.
+Project-URL: Documentation, https://github.com/FlavioAmurrioCS/docker-devtools#readme
+Project-URL: Issues, https://github.com/FlavioAmurrioCS/docker-devtools/issues
+Project-URL: Source, https://github.com/FlavioAmurrioCS/docker-devtools
+Author-email: Flavio Amurrio <25621374+FlavioAmurrioCS@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: build-context,buildkit,docker,docker-compose,dockerfile,dockerignore,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Go
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+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: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# docker-devtools
+
+Work on the Docker files in a repository: the build context a Dockerfile would
+send, and the image references it and your Compose files point at.
+
+```console
+$ docker-devtools image ls
+Dockerfile:1        python:3.11-slim
+compose.yaml:3      nginx:1.25-alpine
+
+$ docker-devtools image update --tag-policy same-pattern --dry-run
+Dockerfile:1     python:3.11-slim -> python:3.14-slim      (tag 3.11-slim -> 3.14-slim)
+compose.yaml:3   nginx:1.25-alpine -> nginx:1.31-alpine    (tag 1.25-alpine -> 1.31-alpine)
+```
+
+## Why another one
+
+Renovate and Dependabot already update image references, and they do it well.
+They run as bots against a repository and open pull requests. This one runs on
+your machine and edits the files in place. It is fast enough for a pre-commit
+hook, so a stale base image gets caught before it is ever committed.
+
+Where the semantics are Docker's, this defers to Docker's own code:
+
+| Step | Package |
+| --- | --- |
+| Parse Dockerfiles | `moby/buildkit/frontend/dockerfile/parser` and `instructions` |
+| Parse image references | `google/go-containerregistry/pkg/name` |
+| Talk to registries | `google/go-containerregistry/pkg/v1/remote` |
+| Match .dockerignore rules | `moby/patternmatcher` |
+| Walk a build context | `tonistiigi/fsutil`, the package BuildKit sends contexts with |
+
+None of the `.dockerignore` semantics are reimplemented here, and CI checks
+that rather than asserting it: for every fixture, `scripts/conformance.sh`
+builds `FROM scratch` with `COPY . /`, exports the image as a tarball, and
+diffs the tar members against what `context ls` reports.
+
+## Install
+
+```console
+$ uvx docker-devtools image ls          # no install
+$ pipx run docker-devtools image ls     # no install
+$ uv tool install docker-devtools
+$ pip install docker-devtools
+$ mise use ubi:FlavioAmurrioCS/docker-devtools
+```
+
+Prebuilt binaries are attached to each
+[release](https://github.com/FlavioAmurrioCS/docker-devtools/releases). With a
+Go toolchain:
+
+```console
+$ go install github.com/FlavioAmurrioCS/docker-devtools/cmd/docker-devtools@latest
+```
+
+Reading and updating files doesn't require a Docker installation or a running
+daemon.
+Registry lookups authenticate with the same `~/.docker/config.json` the docker
+CLI uses.
+
+## Usage
+
+```text
+docker-devtools context ls [PATH]        list the files Docker would send
+docker-devtools context explain PATH     show which .dockerignore rule decided a path
+docker-devtools image ls [PATH...]       list every image reference, with file and line
+docker-devtools image update [PATH...]   rewrite references in place
+docker-devtools install-docker-plugin    register as "docker devtools"
+```
+
+### Updating image references
+
+What changes is split by how much judgement it needs.
+
+`--pin-digest` resolves the current tag to a digest and appends it, turning
+`nginx:1.29` into `nginx:1.29@sha256:…`. It doesn't decide anything about versions, so it is
+reversible and safe to run anywhere.
+
+`--tag-policy` moves the tag. The default, `same-pattern`, moves only the last
+component and keeps the suffix, so how specific your tag is decides how far it
+may move:
+
+| Current tag | same-pattern | minor | patch | latest |
+| --- | --- | --- | --- | --- |
+| `3.12-slim` | `3.13-slim` | `3.13-slim` | no change | `4.0-slim` |
+| `3.12.1-slim` | `3.12.7-slim` | `3.13.0-slim` | `3.12.7-slim` | `4.0-slim` |
+| `latest` | no change | no change | no change | no change |
+
+No policy ever changes the suffix: `-alpine` and `-slim` are different images,
+and swapping them would change your base distribution without saying so. Tags
+with no version, such as `latest` or `bookworm`, are never moved, because there
+is no ordering to move along.
+
+Add `--dry-run` to see the plan without writing, and `--fail-on-diff` to exit
+non-zero when anything would change, which is what makes it useful in CI.
+
+### What it will not touch
+
+Some references cannot be resolved to an image, and those are reported rather
+than guessed at. Pass `--unresolved` to `image ls` to see them:
+
+- `FROM builder`, where `builder` is an earlier stage
+- `COPY --from=0`, which indexes a stage
+- `FROM $BASE`, which depends on a build argument
+- `FROM scratch`, which is the empty base rather than a registry image
+- Compose values built from variables, such as `${REGISTRY}/app:latest`
+
+### Editing in place
+
+An update splices the new reference into the exact byte range the parser
+reported. It never re-encodes the file, so comments, quoting style, anchors and
+whitespace all survive:
+
+```yaml
+    image: "nginx:1.29-alpine"   # keep this comment and the quotes
+```
+
+becomes
+
+```yaml
+    image: "nginx:1.31-alpine"   # keep this comment and the quotes
+```
+
+If a byte range no longer holds the text the parse said it held, the update
+fails instead of writing. A rewrite that has drifted from the parse is a bug,
+and corrupting the file would hide it.
+
+## Shell completion
+
+The binary emits a [usage](https://usage.jdx.dev) spec describing its own
+command tree, and the `usage` CLI turns that into completions for bash, zsh,
+fish, powershell and nushell:
+
+```console
+$ mise use usage
+$ usage g completion zsh docker-devtools --usage-cmd 'docker-devtools --usage-spec' --install
+```
+
+The generated scripts call back to `usage` at completion time, so it has to stay
+on your PATH. `mise run completions` regenerates all five, plus a markdown
+reference, into `build/`.
+
+## As a Docker CLI plugin
+
+```console
+$ docker-devtools install-docker-plugin
+$ docker devtools image ls
+```
+
+This symlinks the binary into `~/.docker/cli-plugins/`. Use `--system` to
+install it for every user.
+
+The subcommand is `devtools` because Docker validates plugin names against
+`^[a-z][a-z0-9]*$` and refuses to load anything else. Python wheels cannot do
+this step at install time: they have no post-install hook, and
+`~/.docker/cli-plugins/` sits outside every Python install path.
+
+## Python API
+
+The wheel bundles the binary and a typed wrapper.
+
+```python
+from docker_devtools import image_ls
+from docker_devtools import image_update
+
+for ref in image_ls(".").resolved():
+    print(f"{ref.path}:{ref.line}", ref.repository, ref.tag)
+
+report = image_update(".", pin_digest=True, dry_run=True)
+for change in report.changes:
+    print(change.old, "->", change.new, f"({change.reason})")
+```
+
+`image_update` defaults to `dry_run=True`, so calling it by accident cannot
+rewrite a repository.
+
+## Development
+
+`mise.toml` defines the tools and the tasks.
+
+```console
+$ mise run build         # compile into ./build
+$ mise run test          # go test + pytest
+$ mise run lint          # pre-commit across the repo
+$ mise run conformance   # diff context listing against real docker build
+$ mise run completions   # regenerate completions and docs
+$ mise run wheels        # every platform wheel into ./dist
+$ mise run test-clone    # verify a fresh clone in a container
+```
+
+Registry behaviour is tested against `go-containerregistry`'s in-process
+registry, so the suite doesn't touch the network or carry recorded fixtures.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+`src/docker_devtools/_find.py` adapts the binary-discovery search order from
+[uv](https://github.com/astral-sh/uv), which is MIT OR Apache-2.0.

docker_devtools-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+docker_devtools/__init__.py,sha256=9aT8SmaV-5c6agMYBr2V5Q484FnHJ4c_xOyHaXlgZ5I,5361
+docker_devtools/__main__.py,sha256=Z69rv0HFIRO51fDaDbkJGcVjKBU5xLJy5JwBVLlHicY,977
+docker_devtools/_find.py,sha256=05nOAAWz_wfte_oC2xgLAdbGibxK8Lh8x_HaXGlPP34,4098
+docker_devtools/_version.py,sha256=8OsTLsIVB9D0HdPTmt5rVwyVUBe9xTVGkRslXicxzkM,520
+docker_devtools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docker_devtools-0.0.1.data/scripts/docker-devtools.exe,sha256=jX9xCryrgtIrDGc52o7IGC8NT2blvNVrnkb0CM587_0,12755968
+docker_devtools-0.0.1.dist-info/METADATA,sha256=uuK1ZLszlCU6EPa0RCSPy931e-vFSS_mTK7FW5wshmw,8563
+docker_devtools-0.0.1.dist-info/WHEEL,sha256=OA-gEgWbLnh0Tf6JrLOMFR4vOWY4QbBMSZuN6osy-Q0,94
+docker_devtools-0.0.1.dist-info/licenses/LICENSE,sha256=fbYeK7h6gKfDaN_ycO18fIdTlYGsYJZypz-JAR_-ybA,1071
+docker_devtools-0.0.1.dist-info/RECORD,,

docker_devtools-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

docker_devtools-0.0.1.dist-info/licenses/LICENSE

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