duty 1.6.0__py3-none-any.whl → 1.6.2__py3-none-any.whl

duty/_internal/collection.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import inspect
+import sys
+from copy import deepcopy
+from importlib import util as importlib_util
+from typing import Any, Callable, ClassVar, Union
+
+from duty._internal.context import Context
+
+DutyListType = list[Union[str, Callable, "Duty"]]
+"""Type of a list of duties, which can be a list of strings, callables, or Duty instances."""
+default_duties_file = "duties.py"
+"""Default path to the duties file, relative to the current working directory."""
+
+
+class Duty:
+    """The main duty class."""
+
+    default_options: ClassVar[dict[str, Any]] = {}
+    """Default options used to create the context instance."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        function: Callable,
+        collection: Collection | None = None,
+        aliases: set | None = None,
+        pre: DutyListType | None = None,
+        post: DutyListType | None = None,
+        opts: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the duty.
+
+        Parameters:
+            name: The duty name.
+            description: The duty description.
+            function: The duty function.
+            collection: The collection on which to attach this duty.
+            aliases: A list of aliases for this duty.
+            pre: A list of duties to run before this one.
+            post: A list of duties to run after this one.
+            opts: Options used to create the context instance.
+        """
+        self.name = name
+        """The duty name."""
+        self.description = description
+        """The duty description."""
+        self.function = function
+        """The duty function."""
+        self.aliases = aliases or set()
+        """A set of aliases for this duty."""
+        self.pre = pre or []
+        """A list of duties to run before this one."""
+        self.post = post or []
+        """A list of duties to run after this one."""
+        self.options = opts or self.default_options
+        """Options used to create the context instance."""
+        self.options_override: dict = {}
+        """Options that override `run` and `@duty` options."""
+
+        self.collection: Collection | None = None
+        """The collection on which this duty is attached."""
+        if collection:
+            collection.add(self)
+
+    @property
+    def context(self) -> Context:
+        """Return a new context instance.
+
+        Returns:
+            A new context instance.
+        """
+        return Context(self.options, self.options_override)
+
+    def run(self, *args: Any, **kwargs: Any) -> None:
+        """Run the duty.
+
+        This is just a shortcut for `duty(duty.context, *args, **kwargs)`.
+
+        Parameters:
+            args: Positional arguments passed to the function.
+            kwargs: Keyword arguments passed to the function.
+        """
+        self(self.context, *args, **kwargs)
+
+    def run_duties(self, context: Context, duties_list: DutyListType) -> None:
+        """Run a list of duties.
+
+        Parameters:
+            context: The context to use.
+            duties_list: The list of duties to run.
+
+        Raises:
+            RuntimeError: When a duty name is given to pre or post duties.
+                Indeed, without a parent collection, it is impossible
+                to find another duty by its name.
+        """
+        for duty_item in duties_list:
+            if callable(duty_item):
+                # Item is a proper duty, or a callable: run it.
+                duty_item(context)
+            elif isinstance(duty_item, str):
+                # Item is a reference to a duty.
+                if self.collection is None:
+                    raise RuntimeError(f"Can't find duty by name without a collection ({duty_item})")
+                # Get the duty and run it.
+                self.collection.get(duty_item)(context)
+
+    def __call__(self, context: Context, *args: Any, **kwargs: Any) -> None:
+        """Run the duty function.
+
+        Parameters:
+            context: The context to use.
+            args: Positional arguments passed to the function.
+            kwargs: Keyword arguments passed to the function.
+        """
+        self.run_duties(context, self.pre)
+        self.function(context, *args, **kwargs)
+        self.run_duties(context, self.post)
+
+
+class Collection:
+    """A collection of duties.
+
+    Attributes:
+        path: The path to the duties file.
+        duties: The list of duties.
+        aliases: A dictionary of aliases pointing to their respective duties.
+    """
+
+    def __init__(self, path: str = default_duties_file) -> None:
+        """Initialize the collection.
+
+        Parameters:
+            path: The path to the duties file.
+        """
+        self.path = path
+        """The path to the duties file."""
+        self.duties: dict[str, Duty] = {}
+        """The list of duties."""
+        self.aliases: dict[str, Duty] = {}
+        """A dictionary of aliases pointing to their respective duties."""
+
+    def clear(self) -> None:
+        """Clear the collection."""
+        self.duties.clear()
+        self.aliases.clear()
+
+    def names(self) -> list[str]:
+        """Return the list of duties names and aliases.
+
+        Returns:
+            The list of duties names and aliases.
+        """
+        return list(self.duties.keys()) + list(self.aliases.keys())
+
+    def completion_candidates(self, args: tuple[str, ...]) -> list[str]:
+        """Find shell completion candidates within this collection.
+
+        Returns:
+            The list of shell completion candidates, sorted alphabetically.
+        """
+        # Find last duty name in args.
+        name = None
+        names = set(self.names())
+        for arg in reversed(args):
+            if arg in names:
+                name = arg
+                break
+
+        completion_names = sorted(names)
+
+        # If no duty found, return names.
+        if name is None:
+            return completion_names
+
+        params = [
+            f"{param.name}="
+            for param in inspect.signature(self.get(name).function).parameters.values()
+            if param.kind is not param.VAR_POSITIONAL
+        ][1:]
+
+        # If duty found, return names *and* duty parameters.
+        return completion_names + sorted(params)
+
+    def get(self, name_or_alias: str) -> Duty:
+        """Get a duty by its name or alias.
+
+        Parameters:
+            name_or_alias: The name or alias of the duty.
+
+        Returns:
+            A duty.
+        """
+        try:
+            return self.duties[name_or_alias]
+        except KeyError:
+            return self.aliases[name_or_alias]
+
+    def format_help(self) -> str:
+        """Format a message listing the duties.
+
+        Returns:
+            A string listing the duties and their summary.
+        """
+        lines = []
+        # 20 makes the summary aligned with options description
+        longest_name = max(*(len(name) for name in self.duties), 20)
+        for name, duty in self.duties.items():
+            description = duty.description.split("\n")[0]
+            lines.append(f"{name:{longest_name}}  {description}")
+        return "\n".join(lines)
+
+    def add(self, duty: Duty) -> None:
+        """Add a duty to the collection.
+
+        Parameters:
+            duty: The duty to add.
+        """
+        if duty.collection is not None:
+            # we must copy the duty to be able to add it
+            # in multiple collections
+            duty = deepcopy(duty)
+        duty.collection = self
+        self.duties[duty.name] = duty
+        for alias in duty.aliases:
+            self.aliases[alias] = duty
+
+    def load(self, path: str | None = None) -> None:
+        """Load duties from a Python file.
+
+        Parameters:
+            path: The path to the Python file to load.
+                Uses the collection's path by default.
+        """
+        path = path or self.path
+        spec = importlib_util.spec_from_file_location("duty.duties", path)
+        if spec:
+            duties = importlib_util.module_from_spec(spec)
+            sys.modules["duty.duties"] = duties
+            spec.loader.exec_module(duties)  # type: ignore[union-attr]
+            declared_duties = inspect.getmembers(duties, lambda member: isinstance(member, Duty))
+            for _, duty in declared_duties:
+                self.add(duty)

duty/_internal/context.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager, suppress
+from typing import TYPE_CHECKING, Any, Callable, Union
+
+from failprint import run as failprint_run
+
+from duty._internal.exceptions import DutyFailure
+from duty._internal.tools._base import Tool
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+CmdType = Union[str, list[str], Callable]
+"""Type of a command that can be run in a subprocess or as a Python callable."""
+
+
+class Context:
+    """A simple context class.
+
+    Context instances are passed to functions decorated with `duty`.
+    """
+
+    def __init__(self, options: dict[str, Any], options_override: dict[str, Any] | None = None) -> None:
+        """Initialize the context.
+
+        Parameters:
+            options: Base options specified in `@duty(**options)`.
+            options_override: Options that override `run` and `@duty` options.
+                This argument is used to allow users to override options from the CLI or environment.
+        """
+        self._options = options
+        self._option_stack: list[dict[str, Any]] = []
+        self._options_override = options_override or {}
+
+    @contextmanager
+    def cd(self, directory: str) -> Iterator:
+        """Change working directory as a context manager.
+
+        Parameters:
+            directory: The directory to go into.
+
+        Yields:
+            Nothing.
+        """
+        if not directory:
+            yield
+            return
+        old_wd = os.getcwd()
+        os.chdir(directory)
+        try:
+            yield
+        finally:
+            os.chdir(old_wd)
+
+    def run(self, cmd: CmdType, **options: Any) -> str:
+        """Run a command in a subprocess or a Python callable.
+
+        Parameters:
+            cmd: A command or a Python callable.
+            options: Options passed to `failprint` functions.
+
+        Raises:
+            DutyFailure: When the exit code / function result is greather than 0.
+
+        Returns:
+            The output of the command.
+        """
+        final_options = dict(self._options)
+        final_options.update(options)
+
+        if "command" not in final_options and isinstance(cmd, Tool):
+            with suppress(ValueError):
+                final_options["command"] = cmd.cli_command
+
+        allow_overrides = final_options.pop("allow_overrides", True)
+        workdir = final_options.pop("workdir", None)
+
+        if allow_overrides:
+            final_options.update(self._options_override)
+
+        with self.cd(workdir):
+            try:
+                result = failprint_run(cmd, **final_options)
+            except KeyboardInterrupt as ki:
+                raise DutyFailure(130) from ki
+
+        if result.code:
+            raise DutyFailure(result.code)
+
+        return result.output
+
+    @contextmanager
+    def options(self, **opts: Any) -> Iterator:
+        """Change options as a context manager.
+
+        Can be nested as will, previous options will pop once out of the with clause.
+
+        Parameters:
+            **opts: Options used in `run`.
+
+        Yields:
+            Nothing.
+        """
+        self._option_stack.append(self._options)
+        self._options = {**self._options, **opts}
+        try:
+            yield
+        finally:
+            self._options = self._option_stack.pop()

duty/{debug.py → _internal/debug.py}

@@ -1,5 +1,3 @@
-"""Debugging utilities."""
-
 from __future__ import annotations
 
 import os
@@ -10,7 +8,7 @@ from importlib import metadata
 
 
 @dataclass
-class Variable:
+class _Variable:
     """Dataclass describing an environment variable."""
 
     name: str
@@ -20,7 +18,7 @@ class Variable:
 
 
 @dataclass
-class Package:
+class _Package:
     """Dataclass describing a Python package."""
 
     name: str
@@ -30,7 +28,7 @@ class Package:
 
 
 @dataclass
-class Environment:
+class _Environment:
     """Dataclass to store environment information."""
 
     interpreter_name: str
@@ -41,9 +39,9 @@ class Environment:
     """Path to Python executable."""
     platform: str
     """Operating System."""
-    packages: list[Package]
+    packages: list[_Package]
     """Installed packages."""
-    variables: list[Variable]
+    variables: list[_Variable]
     """Environment variables."""
 
 
@@ -58,7 +56,7 @@ def _interpreter_name_version() -> tuple[str, str]:
     return "", "0.0.0"
 
 
-def get_version(dist: str = "duty") -> str:
+def _get_version(dist: str = "duty") -> str:
     """Get version of the given distribution.
 
     Parameters:
@@ -73,7 +71,7 @@ def get_version(dist: str = "duty") -> str:
         return "0.0.0"
 
 
-def get_debug_info() -> Environment:
+def _get_debug_info() -> _Environment:
     """Get debug/environment information.
 
     Returns:
@@ -82,19 +80,19 @@ def get_debug_info() -> Environment:
     py_name, py_version = _interpreter_name_version()
     packages = ["duty"]
     variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("DUTY")]]
-    return Environment(
+    return _Environment(
         interpreter_name=py_name,
         interpreter_version=py_version,
         interpreter_path=sys.executable,
         platform=platform.platform(),
-        variables=[Variable(var, val) for var in variables if (val := os.getenv(var))],
-        packages=[Package(pkg, get_version(pkg)) for pkg in packages],
+        variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))],  # ty: ignore[invalid-argument-type]
+        packages=[_Package(pkg, _get_version(pkg)) for pkg in packages],
     )
 
 
-def print_debug_info() -> None:
+def _print_debug_info() -> None:
     """Print debug/environment information."""
-    info = get_debug_info()
+    info = _get_debug_info()
     print(f"- __System__: {info.platform}")
     print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
     print("- __Environment variables__:")
@@ -106,4 +104,4 @@ def print_debug_info() -> None:
 
 
 if __name__ == "__main__":
-    print_debug_info()
+    _print_debug_info()

duty/_internal/decorator.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import inspect
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, overload
+
+from duty._internal.collection import Duty, DutyListType
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from duty._internal.context import Context
+
+
+def _skip(func: Callable, reason: str) -> Callable:
+    @wraps(func)
+    def wrapper(ctx: Context, *args, **kwargs) -> None:  # noqa: ARG001,ANN002,ANN003
+        ctx.run(lambda: True, title=reason)
+
+    return wrapper
+
+
+def create_duty(
+    func: Callable,
+    *,
+    name: str | None = None,
+    aliases: Iterable[str] | None = None,
+    pre: DutyListType | None = None,
+    post: DutyListType | None = None,
+    skip_if: bool = False,
+    skip_reason: str | None = None,
+    **opts: Any,
+) -> Duty:
+    """Register a duty in the collection.
+
+    Parameters:
+        func: The callable to register as a duty.
+        name: The duty name.
+        aliases: A set of aliases for this duty.
+        pre: Pre-duties.
+        post: Post-duties.
+        skip_if: Skip running the duty if the given condition is met.
+        skip_reason: Custom message when skipping.
+        opts: Options passed to the context.
+
+    Returns:
+        The registered duty.
+    """
+    aliases = set(aliases) if aliases else set()
+    name = name or func.__name__
+    dash_name = name.replace("_", "-")
+    if name != dash_name:
+        aliases.add(name)
+        name = dash_name
+    description = inspect.getdoc(func) or ""
+    if skip_if:
+        func = _skip(func, skip_reason or f"{dash_name}: skipped")
+    duty = Duty(name, description, func, aliases=aliases, pre=pre, post=post, opts=opts)
+    duty.__name__ = name  # type: ignore[attr-defined]
+    duty.__doc__ = description
+    duty.__wrapped__ = func  # type: ignore[attr-defined]
+    return duty
+
+
+@overload
+def duty(**kwargs: Any) -> Callable[[Callable], Duty]: ...
+
+
+@overload
+def duty(func: Callable) -> Duty: ...
+
+
+def duty(*args: Any, **kwargs: Any) -> Callable | Duty:
+    """Decorate a callable to transform it and register it as a duty.
+
+    Parameters:
+        args: One callable.
+        kwargs: Context options.
+
+    Raises:
+        ValueError: When the decorator is misused.
+
+    Examples:
+        Decorate a function:
+
+        ```python
+        @duty
+        def clean(ctx):
+            ctx.run("rm -rf build", silent=True)
+        ```
+
+        Pass options to the context:
+
+        ```python
+        @duty(silent=True)
+        def clean(ctx):
+            ctx.run("rm -rf build")  # silent=True is implied
+        ```
+
+    Returns:
+        A duty when used without parentheses, a decorator otherwise.
+    """
+    if args:
+        if len(args) > 1:
+            raise ValueError("The duty decorator accepts only one positional argument")
+        return create_duty(args[0], **kwargs)
+
+    def decorator(func: Callable) -> Duty:
+        return create_duty(func, **kwargs)
+
+    return decorator

duty/_internal/exceptions.py

@@ -0,0 +1,12 @@
+class DutyFailure(Exception):  # noqa: N818
+    """An exception raised when a duty fails."""
+
+    def __init__(self, code: int) -> None:
+        """Initialize the object.
+
+        Parameters:
+            code: The exit code of a command.
+        """
+        super().__init__(self)
+        self.code = code
+        """The exit code of the command that failed."""

duty/_internal/tools/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from duty._internal.tools._autoflake import autoflake
+from duty._internal.tools._black import black
+from duty._internal.tools._blacken_docs import blacken_docs
+from duty._internal.tools._build import build
+from duty._internal.tools._coverage import coverage
+from duty._internal.tools._flake8 import flake8
+from duty._internal.tools._git_changelog import git_changelog
+from duty._internal.tools._griffe import griffe
+from duty._internal.tools._interrogate import interrogate
+from duty._internal.tools._isort import isort
+from duty._internal.tools._mkdocs import mkdocs
+from duty._internal.tools._mypy import mypy
+from duty._internal.tools._pytest import pytest
+from duty._internal.tools._ruff import ruff
+from duty._internal.tools._safety import safety
+from duty._internal.tools._ssort import ssort
+from duty._internal.tools._twine import twine
+from duty._internal.tools._yore import yore
+
+__all__ = [
+    "autoflake",
+    "black",
+    "blacken_docs",
+    "build",
+    "coverage",
+    "flake8",
+    "git_changelog",
+    "griffe",
+    "interrogate",
+    "isort",
+    "mkdocs",
+    "mypy",
+    "pytest",
+    "ruff",
+    "safety",
+    "ssort",
+    "twine",
+    "yore",
+]

duty/{tools → _internal/tools}/_autoflake.py

@@ -1,14 +1,13 @@
-"""Callable for [autoflake](https://github.com/PyCQA/autoflake)."""
-
 from __future__ import annotations
 
-from duty.tools._base import LazyStderr, LazyStdout, Tool
+from duty._internal.tools._base import LazyStderr, LazyStdout, Tool
 
 
 class autoflake(Tool):  # noqa: N801
     """Call [autoflake](https://github.com/PyCQA/autoflake)."""
 
     cli_name = "autoflake"
+    """The name of the executable on PATH."""
 
     def __init__(
         self,
@@ -129,7 +128,12 @@ class autoflake(Tool):  # noqa: N801
         super().__init__(cli_args)
 
     def __call__(self) -> int:
-        from autoflake import _main as run_autoflake
+        """Run the command.
+
+        Returns:
+            The exit code of the command.
+        """
+        from autoflake import _main as run_autoflake  # noqa: PLC0415
 
         return run_autoflake(
             self.cli_args,

duty/{tools → _internal/tools}/_base.py

@@ -1,4 +1,4 @@
-"""Utilities for creating tools."""
+# Utilities for creating tools.
 
 from __future__ import annotations
 
@@ -21,6 +21,7 @@ class LazyStdout(StringIO):
     """
 
     def write(self, value: str) -> int:
+        """Write a string to the stdout buffer."""
         return sys.stdout.write(value)
 
     def __repr__(self) -> str:
@@ -35,6 +36,7 @@ class LazyStderr(StringIO):
     """
 
     def write(self, value: str) -> int:
+        """Write a string to the stderr buffer."""
         return sys.stderr.write(value)
 
     def __repr__(self) -> str:
@@ -45,22 +47,33 @@ class Tool:
     """Base class for tools."""
 
     cli_name: str = ""
+    """The name of the executable on PATH."""
 
     def __init__(
         self,
         cli_args: list[str] | None = None,
         py_args: dict[str, Any] | None = None,
     ) -> None:
+        """Initialize the tool.
+
+        Parameters:
+            cli_args: Initial command-line arguments. Use `add_args()` to add more.
+            py_args: Python arguments. Your `__call__` method will be able to access
+                these arguments as `self.py_args`.
+        """
         self.cli_args: list[str] = cli_args or []
+        """Registered command-line arguments."""
         self.py_args: dict[str, Any] = py_args or {}
+        """Registered Python arguments."""
 
     def add_args(self, *args: str) -> Self:
-        """Add arguments."""
+        """Append CLI arguments."""
         self.cli_args.extend(args)
         return self
 
     @property
     def cli_command(self) -> str:
+        """The equivalent CLI command."""
         if not self.cli_name:
             raise ValueError("This tool does not provide a CLI.")
         return shlex.join([self.cli_name, *self.cli_args])