docker-composer 2.79.7__tar.gz → 5.0.2__tar.gz

{docker_composer-2.79.7 → docker_composer-5.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-composer
-Version: 2.79.7
+Version: 5.0.2
 Summary: Use docker-compose (V2) from within Python
 Project-URL: Homepage, https://github.com/schollm/docker-composer
 Project-URL: Repository, https://github.com/schollm/docker-composer
@@ -16,9 +16,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: <4.0,>=3.9
-Requires-Dist: attrs>=20.3.0
-Requires-Dist: loguru>=0.5.3
-Requires-Dist: ruff>=0.11.10
 Description-Content-Type: text/markdown
 
 # Docker Composer
@@ -27,6 +24,8 @@ All commands and parameters are exposed as python classes and attributes
 to allow for full auto-completion of its parameters with IDEs
 that support it.
 
+**Runtime footprint:** This library is **stdlib-only** (zero third-party runtime dependencies).
+
 
 ## Install
 ```shell script
@@ -67,13 +66,24 @@ print(process.stdout.encode("UTF-8"))
 
 ## Develop
 
+### Development Setup
+
+When developing, the `_utils` module is available for generating the docker_composer
+module from the `docker compose`CLI help output.
+This is not required for normal package usage.
+
+```bash
+uv sync --group dev
+uv run poe generate
+```
+
 ### Coding Standards
 
-| **Type**       | Package  | Comment                         |
-| -------------- |----------| ------------------------------- |
-| **Linter**     | `black`  | Also for auto-formatted modules |
-| **Logging**    | `loguru` |                                 |
-| **Packaging**  | `uv`     |                                 |
-| **Tests**      | `pytest` |                                 |
-| **Typing**     | `mypy`   | Type all methods                |
-| **Imports**    | `isort`  |                                 |
+| **Type**       | Package   | Comment                         |
+| -------------- |-----------| ------------------------------- |
+| **Linter**     | `ruff`    | Also for auto-formatted modules |
+| **Logging**    | `logging` |                                 |
+| **Packaging**  | `uv`      |                                 |
+| **Tests**      | `pytest`  |                                 |
+| **Typing**     | `mypy`    | Type all methods                |
+| **Imports**    | `ruff`    |                                 |

{docker_composer-2.79.7 → docker_composer-5.0.2}/README.md

@@ -4,6 +4,8 @@ All commands and parameters are exposed as python classes and attributes
 to allow for full auto-completion of its parameters with IDEs
 that support it.
 
+**Runtime footprint:** This library is **stdlib-only** (zero third-party runtime dependencies).
+
 
 ## Install
 ```shell script
@@ -44,13 +46,24 @@ print(process.stdout.encode("UTF-8"))
 
 ## Develop
 
+### Development Setup
+
+When developing, the `_utils` module is available for generating the docker_composer
+module from the `docker compose`CLI help output.
+This is not required for normal package usage.
+
+```bash
+uv sync --group dev
+uv run poe generate
+```
+
 ### Coding Standards
 
-| **Type**       | Package  | Comment                         |
-| -------------- |----------| ------------------------------- |
-| **Linter**     | `black`  | Also for auto-formatted modules |
-| **Logging**    | `loguru` |                                 |
-| **Packaging**  | `uv`     |                                 |
-| **Tests**      | `pytest` |                                 |
-| **Typing**     | `mypy`   | Type all methods                |
-| **Imports**    | `isort`  |                                 |
+| **Type**       | Package   | Comment                         |
+| -------------- |-----------| ------------------------------- |
+| **Linter**     | `ruff`    | Also for auto-formatted modules |
+| **Logging**    | `logging` |                                 |
+| **Packaging**  | `uv`      |                                 |
+| **Tests**      | `pytest`  |                                 |
+| **Typing**     | `mypy`    | Type all methods                |
+| **Imports**    | `ruff`    |                                 |

{docker_composer-2.79.7 → docker_composer-5.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docker-composer"
-version = "2.79.7"
+version = "5.0.2"
 description = "Use docker-compose (V2) from within Python"
 authors = [{ name = "Micha", email = "schollm-git@gmx.com" }]
 requires-python = ">=3.9,<4.0"
@@ -16,11 +16,7 @@ classifiers = [
     "Operating System :: OS Independent",
     "Development Status :: 5 - Production/Stable",
 ]
-dependencies = [
-    "attrs>=20.3.0",
-    "loguru>=0.5.3",
-    "ruff>=0.11.10",
-]
+dependencies = []
 
 [project.urls]
 Homepage = "https://github.com/schollm/docker-composer"
@@ -29,10 +25,11 @@ Repository = "https://github.com/schollm/docker-composer"
 [dependency-groups]
 dev = [
     "black>=25.1.0",
-    "flake8>=6.0.0,<7",
     "isort>=6.0.1",
+    "poethepoet>=0.30.0",
     "pytest>=6.1.2",
     "pytest-cov>=6.1.1",
+    "ruff>=0.11.10",
 ]
 
 [tool.hatch.build.targets.sdist]
@@ -40,6 +37,7 @@ include = ["src/docker_composer"]
 
 [tool.hatch.build.targets.wheel]
 include = ["src/docker_composer"]
+exclude = ["src/docker_composer/_utils"]
 
 [tool.hatch.build.targets.wheel.sources]
 "src/docker_composer" = "docker_composer"
@@ -54,8 +52,20 @@ addopts = """
   --cov=src/docker_composer
   --cov-report=xml:.out/coverage.xml
   --cov-report=html:.out/coverage-html
-  --cov-report term-missing
+  --cov-report term-missing:skip-covered
   --cov-branch
   --doctest-modules
 """
 
+[tool.poe.tasks]
+ruff-check = { cmd = "uv run ruff check" }
+ruff-format-check = { cmd = "uv run ruff format --check" }
+pytest =  { cmd = "uv run pytest" }
+format = { cmd = "uv run ruff format" }
+build = { cmd = "uv build" }
+publish-dist = { cmd = "uv publish" }
+generate-code = { cmd = "uv run python -m docker_composer._utils.generate_class" }
+sync-version = { cmd = "uv run python -m docker_composer._utils.sync_version" }
+publish = { sequence = ["build", "publish-dist"] }
+test = { sequence = ["ruff-check", "ruff-format-check", "pytest $POE_EXTRA_ARGS"] }
+generate = { sequence = ["generate-code", "sync-version"] }

docker_composer-5.0.2/src/docker_composer/__init__.py

@@ -0,0 +1,6 @@
+try:
+    from docker_composer.runner.root import DockerComposeRoot as DockerCompose
+except ImportError:
+    pass
+
+__all__ = ["DockerCompose"]

{docker_composer-2.79.7 → docker_composer-5.0.2}/src/docker_composer/_utils/argument.py

@@ -1,8 +1,12 @@
-from typing import Iterable, Iterator, List, Tuple, Type
+"""Helper modules to parse docker compoose --help arguments"""
 
-import attr
-from loguru import logger
+from __future__ import annotations
+from typing import Iterable, Iterator
 
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
 OPTION = "OPTION"
 
 _TYPE_CONVERSIONS = {
@@ -16,7 +20,6 @@ _TYPE_CONVERSIONS = {
     "LEVEL": int,
     "MEM": int,
     "NAME": str,
-    OPTION: bool,
     "PATH": str,
     "SERVICE": str,
     "SIGNAL": int,
@@ -24,28 +27,34 @@ _TYPE_CONVERSIONS = {
     "TIMEOUT": int,
     "TLS_KEY_PATH": str,
     "USER": str,
-    "type": str,
-    "string": str,
+    "bytes": int,
+    "docker": bool,
+    "filter": str,
     "int": int,
     "list": list,
+    "scale": int,
     "str": str,
+    "string": str,
     "stringArray": list[str],
+    "type": str,
     "volumes": list[str],
-    "docker": bool,
+    OPTION: bool,
 }
 
 
-@attr.s(auto_attribs=True, frozen=True, eq=False)
+@dataclass(frozen=True)
 class Argument:
     arg: str
     type_desc: str
-    type: Type
+    type_: type
     description: str
     default: str = ""
 
     @property
     def type_str(self) -> str:
-        return "Any" if self.type is object else self.type.__name__
+        if self.type_ is object:
+            raise ValueError(self.type_)
+        return self.type_.__name__
 
     @property
     def is_option(self) -> bool:
@@ -55,28 +64,7 @@ class Argument:
     def from_line(line: str) -> "Argument":
         if "  " in line:
             return _from_line_has_sep(line)
-
-        words = iter(line.split())
-        has_more = True
-        while has_more:
-            arg, default_str, has_more = _parse_arg(next(words))
-        type_desc = next(words)
-        type_from_default = _get_type_name_from_default(default_str)
-        desc = " ".join(words)
-        if type_desc[1:].islower() and "=" not in type_desc:
-            desc = f"{type_desc} {desc}"
-            type_desc = type_from_default
-
-        type_ = _get_type(type_from_default if default_str else type_desc)
-        return Argument(arg, type_desc, type_, desc, default_str)
-
-    def __eq__(self, other) -> bool:
-        if not isinstance(other, type(self)):
-            return False
-        return self.arg == other.arg
-
-    def __hash__(self):
-        return hash(self.arg)
+        raise ValueError(line)
 
 
 def _collect_arguments(arguments: Iterable[str]) -> Iterator[str]:
@@ -91,7 +79,7 @@ def _collect_arguments(arguments: Iterable[str]) -> Iterator[str]:
         yield res.strip()
 
 
-def parse_dc_argument(lines: List[str]) -> List[Argument]:
+def parse_dc_argument(lines: list[str]) -> list[Argument]:
     """
     Parse arguments from lines of docker-compose specifications
     :param lines: Lines of the Options sections from `docker-compose --help`.
@@ -101,18 +89,18 @@ def parse_dc_argument(lines: List[str]) -> List[Argument]:
     return [Argument.from_line(line) for line in iter_lines if "--version" not in line]
 
 
-def _get_type(type_name) -> Type:
+def _get_type(type_name) -> type:
     res = _TYPE_CONVERSIONS.get(type_name, None)
     if res is None:
         if "=" in type_name:
             res = dict
         else:
-            logger.warning("Unknown type {}, use str", type_name)
+            logger.warning("Unknown type %s, use str", type_name)
             res = str
     return res
 
 
-def _parse_arg(arg: str) -> Tuple[str, str, bool]:
+def _parse_arg(arg: str) -> tuple[str, str, bool]:
     while arg.startswith("-"):
         arg = arg[1:]
     # if argument ends with a comma, it is followed by an alias. (usually -f, --foo)
@@ -138,11 +126,7 @@ def _get_type_name_from_default(default: str) -> str:
     elif default == "proto":
         return "str"
     else:
-        try:
-            return eval(default).__class__.__name__
-        except NameError:
-            logger.warning("Could not get type for value '{}'", default)
-            return "str"
+        raise NotImplementedError(default)
 
 
 def _from_line_has_sep(line) -> "Argument":
@@ -153,17 +137,18 @@ def _from_line_has_sep(line) -> "Argument":
     :param line: a single line with the description separated from the definition by at least two blanks
     :return: Argument
     """
-    desc_idx = line[4:].index("  ")
-    desc = line[desc_idx + 2 + 4 :].strip()
-    args = iter(line[: desc_idx + 4].split())
+    min_arg_chars = 2  #  Simple argument with single dash (e.g. -x)
+    min_full_chars = 4  # Named argument with double-dash (e.g. --xy)
+    desc_idx = line[min_arg_chars:].index("  ")
+    # Help output can wrap differently depending on terminal width.
+    # Normalize all whitespace so wrapped descriptions are stable.
+    desc = line[desc_idx + min_full_chars :].strip()
+    args = iter(line[: desc_idx + min_full_chars].split())
     arg, default, has_more = "", "", True
     while has_more:
         arg, default, has_more = _parse_arg(next(args))
     type_from_default = _get_type_name_from_default(default)
-    try:
-        type_desc = next(args)
-    except StopIteration:
-        type_desc = type_from_default
+    type_desc = next(args, type_from_default)
 
     type_ = _get_type(type_from_default if default else type_desc)
     return Argument(arg, type_desc, type_, desc, default=default)

{docker_composer-2.79.7 → docker_composer-5.0.2}/src/docker_composer/_utils/generate_class.py

@@ -3,54 +3,64 @@ from collections import defaultdict
 from functools import lru_cache, reduce
 from operator import add
 from pathlib import Path
-from typing import Iterable, Iterator, List, Mapping, Set, Tuple, Union
+from typing import Iterator, Mapping, Union
 
 import black
 import isort
 from isort.exceptions import ISortError
-from loguru import logger
+
 
 from docker_composer._utils.argument import Argument, parse_dc_argument
+import logging
+
+logger = logging.getLogger(__name__)
+
+# must be larger than 50 (otherwise it's ignored by docker compose)
+_DEFAULT_HELP_COLUMNS = 120
 
 
 @lru_cache()
 def project_root():
     for path in Path(__file__).parents:
         if "pyproject.toml" in (p.name for p in path.iterdir()):
-            logger.debug("Project Path root: {}", path)
+            logger.debug("Project Path root: %s", path)
             return path
     raise EnvironmentError("No pyproject.toml found in path hierarchy")
 
 
-@lru_cache(None)
-def _version(prog: str) -> str:
-    return (
-        subprocess.run((prog, "--version"), capture_output=True)
-        .stdout.strip()
-        .decode("UTF-8")
-    )
+@lru_cache()
+def _version() -> str:
+    return subprocess.run(
+        ("docker", "compose", "version"), capture_output=True, text=True
+    ).stdout.strip()
 
 
 @lru_cache()
 def get_help_message(subcommand: str = "") -> str:
     """Obtain the help message for subcommand from docker-compose."""
-    args = [arg for arg in ["docker-compose", subcommand, "--help"] if arg]
-    process = subprocess.run(args, capture_output=True, text=True)
-    if process.returncode:
-        logger.error(
-            "docker-compose {} --help exited with {}:", subcommand, process.returncode
+    cmd = " ".join(arg for arg in ["docker", "compose", subcommand, "--help"] if arg)
+    full_cmd = f"stty cols {_DEFAULT_HELP_COLUMNS}; {cmd}"
+    try:
+        process = subprocess.run(
+            ["script", "-q", "-c", full_cmd, "/dev/null"],
+            capture_output=True,
+            text=True,
         )
-        logger.error(process.stderr)
-
+    except Exception:
+        logger.error("FAILED to run %s.", full_cmd)
+        raise
+    if process.returncode:
+        logger.error("%s exited with %s:", cmd, process.returncode)
+        raise RuntimeError(process.stderr)
     return process.stdout
 
 
-def collect_help_lines(msg: str) -> Mapping[str, List[str]]:
+def collect_help_lines(msg: str) -> Mapping[str, list[str]]:
     """Collect help messages into sections.
     :param msg: Output from docker-compose <cmd> --help
     :returns Mapping from section header to lines as lists. First (unnamed) section gets name "general"
     """
-    parts: Mapping[str, List[str]] = defaultdict(list)
+    parts: Mapping[str, list[str]] = defaultdict(list)
     part = "general"
     for line in msg.split("\n"):
         if not line:
@@ -62,19 +72,14 @@ def collect_help_lines(msg: str) -> Mapping[str, List[str]]:
     return parts
 
 
-def parse_help(msg: str) -> Tuple[Mapping[str, List[str]], List[Argument]]:
+def parse_help(msg: str) -> tuple[Mapping[str, list[str]], list[Argument]]:
     """Helper function, get sections and arguments from docker-compose <cmd> --help text"""
     sections = collect_help_lines(msg)
     arguments = parse_dc_argument(sections["options"])
     return sections, arguments
 
 
-def _flatten(lists: Iterable[list]):
-    """Flatten an iterable of lists"""
-    return reduce(add, lists, [])
-
-
-def indent(lines: Union[str, List[str]], level: int = 4) -> str:
+def indent(lines: Union[str, list[str]], level: int = 4) -> str:
     """Indent lines by `level`.
     :param lines: List of strings or a single string. A single string is splt up into individual lines.
     :param level: number of spaces to indent
@@ -82,7 +87,7 @@ def indent(lines: Union[str, List[str]], level: int = 4) -> str:
     """
     if isinstance(lines, str):
         lines = lines.split("\n")
-    lines = _flatten([line.split("\n") for line in lines])
+    lines = reduce(add, (line.split("\n") for line in lines), [])
     prefix = " " * level
     if lines:
         return prefix + f"\n{prefix}".join(lines)
@@ -90,26 +95,26 @@ def indent(lines: Union[str, List[str]], level: int = 4) -> str:
         return ""
 
 
-def get_docstring(sections: Mapping[str, List[str]]) -> List[str]:
+def get_docstring(sections: Mapping[str, list[str]]) -> list[str]:
     """Get (unindeted) docstring from docker-compose <cmd> --help. Use general and usage section.
     :param sections: Output from `collect_help_lines`
     """
     lines = sections["general"]
     usages = sections.get("usage", [])
     if usages:
-        lines += ["Usage:"] + usages
+        return [*lines, "Usage:", *usages]
     return lines
 
 
-def type_arg(arg: Argument) -> Tuple[str, str]:
+def type_arg(arg: Argument) -> tuple[str, str]:
     """Generate the argument for docker-compose as a string, together with the doc-string"""
     type_str = f"Optional[{arg.type_str}]"
     return f"{arg.arg}: {type_str} = None", f'"""{arg.description}"""'
 
 
 def get_def_commands(
-    sections: Mapping[str, List[str]], level: int = 0
-) -> Iterator[Tuple[str, List[str]]]:
+    sections: Mapping[str, list[str]], level: int = 0
+) -> Iterator[tuple[str, list[str]]]:
     """Generate command functions as string"""
     commands = sections.get("commands", None)
     if not commands:
@@ -118,7 +123,7 @@ def get_def_commands(
         if not line.strip():
             continue
         cmd = line.split()[0]
-        logger.debug("Generate run for {}", cmd)
+        logger.debug("Generate run for %s", cmd)
         docker_lines = get_help_message(cmd)
         nl = level + 4
         sections, arguments = parse_help(docker_lines)
@@ -147,47 +152,47 @@ def {cmd}(self, {args}) -> {class_name}:
         )
 
 
-def generate_class(class_name: str, cmd: str, level=0) -> str:
+def generate_class(cmd: str) -> str:
+    class_name = f"DockerCompose{(cmd or 'Root').capitalize()}"
     docker_lines = get_help_message(cmd)
-    nl = level + 4
+    nl = 4
     sections, arguments = parse_help(docker_lines)
     _add_custom_arguments(cmd, arguments)
     cmd_fns = ""
-    add_imports: Set[str] = set()
+    add_imports: set[str] = set()
     if "commands" in sections:
-        logger.info("Found commands in section {}", cmd)
+        logger.info("Found commands in section %s", cmd)
         for cmd_fn, add_import in get_def_commands(sections):
             cmd_fns += cmd_fn
             add_imports = add_imports.union(add_import)
-    args: List[str] = _flatten(list(type_arg(arg)) for arg in arguments)
+    args: list[str] = reduce(add, (list(type_arg(arg)) for arg in arguments), [])
 
     # List of argument that are options only
     options = ", ".join([f'"{arg.arg}"' for arg in arguments if arg.is_option])
     if options:
         options = options + ","
-    new_line = "\n"
-    res = indent(
-        f'''
-# DO NOT EDIT: Autogenerated by {__file__}
-# for {_version("docker-compose")}
-
-import attr
-from typing import Optional, List
+    new_line = "\n"  # Python 3.9 does not support backslashes in format-strings.
+
+    res = f'''
+# DO NOT EDIT: Autogenerated by {"/".join(Path(__file__).parts[-3:])}
+# for {_version()}
+
+import dataclasses as _dc
+from typing import Optional
+
 from docker_composer.base import DockerBaseRunner
 {new_line.join(add_imports)}
 
-@attr.s(auto_attribs=True)
+@_dc.dataclass()
 class {class_name}(DockerBaseRunner):
     """
 {indent(get_docstring(sections), level=nl)}
     """
 {indent(args, level=nl)}
-    _cmd: str = "{cmd or ""}"
-    _options: List[str] = [{options}]
+    _cmd: str = _dc.field(default="{cmd or ""}", repr=False, init=False)
+    _options: list[str] = _dc.field(default_factory=lambda: [{options}], repr=False, init=False)
 {indent(cmd_fns, level=nl)}
-''',
-        level=level,
-    )
+        '''
     try:
         res = isort.code(
             res, config=isort.Config(settings_path=project_root().as_posix())
@@ -201,7 +206,7 @@ class {class_name}(DockerBaseRunner):
         return res
 
 
-def write_class(cmd: str) -> None:
+def write_class(cmd: str = "") -> None:
     """
     Generate a class for `cmd` and write it to `file_name`
 
@@ -210,17 +215,14 @@ def write_class(cmd: str) -> None:
     :return:
     """
     base_path = Path(__file__).parents[1] / "runner"
-    if cmd:
-        file_name = base_path / "cmd" / f"{cmd}.py"
-    else:
-        file_name = base_path / "root.py"
-
-    class_str = generate_class(f"DockerCompose{(cmd or 'Root').capitalize()}", cmd)
-    logger.info("Write {:<8s} -> {}", cmd, file_name)
+    file_name = (base_path / "cmd" / f"{cmd}.py") if cmd else (base_path / "root.py")
+    class_str = generate_class(cmd)
+    logger.info("Write %s -> %s", cmd, file_name)
     file_name.write_text(class_str, encoding="utf-8")
 
 
-def _add_custom_arguments(cmd: str, arguments: list[Argument]):
+def _add_custom_arguments(cmd: str, arguments: list[Argument]) -> None:
+    """Add the verbose option to arguments."""
     if cmd == "":
         verbose = Argument("verbose", "OPTION", bool, "Use verbose output")
         if verbose not in arguments:
@@ -228,8 +230,8 @@ def _add_custom_arguments(cmd: str, arguments: list[Argument]):
 
 
 def main() -> None:
-    write_class("")
-    docker_lines = get_help_message("")
+    write_class()
+    docker_lines = get_help_message()
     sections, _ = parse_help(docker_lines)
     for cmd_line in sections["commands"]:
         if not cmd_line:

docker_composer-5.0.2/src/docker_composer/_utils/sync_version.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import subprocess
+
+
+def docker_compose_version_short() -> str:
+    return subprocess.check_output(
+        ["docker", "compose", "version", "--short"],
+        text=True,
+    ).strip()
+
+
+def main() -> None:
+    version = docker_compose_version_short()
+    if not version:
+        raise RuntimeError("docker compose version --short returned an empty version")
+    subprocess.check_call(["uv", "version", version])
+
+
+if __name__ == "__main__":
+    main()  # pragma: no cover