duty 1.5.0__py3-none-any.whl → 1.6.1__py3-none-any.whl

duty/collection.py

@@ -1,233 +1,17 @@
-"""Module containing all the logic."""
+"""Deprecated. Import from `duty` directly."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
-import inspect
-import sys
-from copy import deepcopy
-from importlib import util as importlib_util
-from typing import Any, Callable, ClassVar, Union
+import warnings
+from typing import Any
 
-from duty.context import Context
+from duty._internal import collection
 
-DutyListType = list[Union[str, Callable, "Duty"]]
-default_duties_file = "duties.py"
 
-
-class Duty:
-    """The main duty class."""
-
-    default_options: ClassVar[dict[str, Any]] = {}
-
-    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
-        self.description = description
-        self.function = function
-        self.aliases = aliases or set()
-        self.pre = pre or []
-        self.post = post or []
-        self.options = opts or self.default_options
-        self.options_override: dict = {}
-
-        self.collection: Collection | None = None
-        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
-        self.duties: dict[str, Duty] = {}
-        self.aliases: dict[str, Duty] = {}
-
-    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)
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `duty.collection` is deprecated. Import from `duty` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(collection, name)

duty/completions.bash

@@ -1,18 +1,18 @@
-# Invoke tab-completion script to be sourced with Bash shell.
-# Known to work on Bash 3.x, untested on 4.x.
+# Taken and adapted from pyinvoke:
+# Copyright (c) 2020 Jeff Forcier.
+# All rights reserved.
 
 _complete_duty() {
     local candidates
 
-    # COMP_WORDS contains the entire command string up til now (including
-    # program name).
-    # We hand it to Invoke so it can figure out the current context: spit back
-    # core options, task names, the current task's options, or some combo.
+    # COMP_WORDS contains the entire command string up til now (including # program name).
+    # We hand it to Invoke so it can figure out the current context:
+    # spit back core options, task names, the current task's options, or some combo.
     candidates=$(duty --complete -- "${COMP_WORDS[@]}")
 
-    # `compgen -W` takes list of valid options & a partial word & spits back
-    # possible matches. Necessary for any partial word completions (vs
-    # completions performed when no partial words are present).
+    # `compgen -W` takes list of valid options & a partial word & spits back possible matches.
+    # Necessary for any partial word completions
+    # (vs. completions performed when no partial words are present).
     #
     # $2 is the current word or token being tabbed on, either empty string or a
     # partial word, and thus wants to be compgen'd to arrive at some subset of

duty/context.py

@@ -1,112 +1,17 @@
-"""Module containing the context definition."""
+"""Deprecated. Import from `duty` directly."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
-import os
-from contextlib import contextmanager, suppress
-from typing import TYPE_CHECKING, Any, Callable, Union
+import warnings
+from typing import Any
 
-from failprint.runners import run as failprint_run
+from duty._internal import context
 
-from duty.exceptions import DutyFailure
-from duty.tools import Tool
 
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-
-CmdType = Union[str, list[str], 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()
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `duty.context` is deprecated. Import from `duty` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(context, name)

duty/decorator.py

@@ -1,113 +1,17 @@
-"""Module containing the decorator provided to users."""
+"""Deprecated. Import from `duty` directly."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
-import inspect
-from functools import wraps
-from typing import TYPE_CHECKING, Any, Callable, overload
+import warnings
+from typing import Any
 
-from duty.collection import Duty, DutyListType
+from duty._internal import decorator
 
-if TYPE_CHECKING:
-    from collections.abc import Iterable
 
-    from duty.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
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `duty.decorator` is deprecated. Import from `duty` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(decorator, name)

duty/exceptions.py

@@ -1,14 +1,17 @@
-"""Module containing the project's exceptions."""
+"""Deprecated. Import from `duty` directly."""
 
+# YORE: Bump 2: Remove file.
 
-class DutyFailure(Exception):  # noqa: N818
-    """An exception raised when a duty fails."""
+import warnings
+from typing import Any
 
-    def __init__(self, code: int) -> None:
-        """Initialize the object.
+from duty._internal import exceptions
 
-        Parameters:
-            code: The exit code of a command.
-        """
-        super().__init__(self)
-        self.code = code
+
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Importing from `duty.exceptions` is deprecated. Import from `duty` directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return getattr(exceptions, name)

duty/tools.py

@@ -0,0 +1,63 @@
+"""Our collection of tools."""
+
+import warnings
+from typing import Any
+
+from duty._internal.tools import (
+    autoflake,
+    black,
+    blacken_docs,
+    build,
+    coverage,
+    flake8,
+    git_changelog,
+    griffe,
+    interrogate,
+    isort,
+    mkdocs,
+    mypy,
+    pytest,
+    ruff,
+    safety,
+    ssort,
+    twine,
+    yore,
+)
+
+__all__ = [
+    "autoflake",
+    "black",
+    "blacken_docs",
+    "build",
+    "coverage",
+    "flake8",
+    "git_changelog",
+    "griffe",
+    "interrogate",
+    "isort",
+    "mkdocs",
+    "mypy",
+    "pytest",
+    "ruff",
+    "safety",
+    "ssort",
+    "twine",
+    "yore",
+]
+
+
+# YORE: Bump 2: Remove block.
+def __getattr__(name: str) -> Any:
+    """Return the tool or lazy object by name."""
+    from failprint import lazy  # noqa: F401,PLC0415
+
+    from duty._internal.tools._base import LazyStderr, LazyStdout, Tool  # noqa: F401,PLC0415
+
+    if name in locals():
+        warnings.warn(
+            f"Importing `{name}` from `duty.tools` is deprecated, import directly from `duty` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return locals()[name]
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")