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

duty/_internal/tools/_yore.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from duty._internal.tools._base import Tool
+
+
+class yore(Tool):  # noqa: N801
+    """Call [Yore](https://github.com/pawamoy/yore)."""
+
+    cli_name = "yore"
+    """The name of the executable on PATH."""
+
+    @classmethod
+    def check(
+        cls,
+        *paths: str,
+        bump: str | None = None,
+        eol_within: str | None = None,
+        bol_within: str | None = None,
+    ) -> yore:
+        """Check Yore comments against Python EOL dates or the provided next version of your project.
+
+        Parameters:
+            paths: Path to files or directories to check.
+            bump: The next version of your project.
+            eol_within: The time delta to start checking before the End of Life of a Python version.
+                It is provided in a human-readable format, like `2 weeks` or `1 month`.
+                Spaces are optional, and the unit can be shortened to a single letter:
+                `d` for days, `w` for weeks, `m` for months, and `y` for years.
+            bol_within: The time delta to start checking before the Beginning of Life of a Python version.
+                It is provided in a human-readable format, like `2 weeks` or `1 month`.
+                Spaces are optional, and the unit can be shortened to a single letter:
+                `d` for days, `w` for weeks, `m` for months, and `y` for years.
+        """
+        cli_args = ["check", *paths]
+
+        if bump:
+            cli_args.append("--bump")
+            cli_args.append(bump)
+
+        if eol_within:
+            cli_args.append("--eol-within")
+            cli_args.append(eol_within)
+
+        if bol_within:
+            cli_args.append("--bol-within")
+            cli_args.append(bol_within)
+
+        return cls(cli_args)
+
+    @classmethod
+    def fix(
+        cls,
+        *paths: str,
+        bump: str | None = None,
+        eol_within: str | None = None,
+        bol_within: str | None = None,
+    ) -> yore:
+        """Fix your code by transforming it according to the Yore comments.
+
+        Parameters:
+            paths: Path to files or directories to fix.
+            bump: The next version of your project.
+            eol_within: The time delta to start fixing before the End of Life of a Python version.
+                It is provided in a human-readable format, like `2 weeks` or `1 month`.
+                Spaces are optional, and the unit can be shortened to a single letter:
+                `d` for days, `w` for weeks, `m` for months, and `y` for years.
+            bol_within: The time delta to start fixing before the Beginning of Life of a Python version.
+                It is provided in a human-readable format, like `2 weeks` or `1 month`.
+                Spaces are optional, and the unit can be shortened to a single letter:
+                `d` for days, `w` for weeks, `m` for months, and `y` for years.
+        """
+        cli_args = ["fix", *paths]
+
+        if bump:
+            cli_args.append("--bump")
+            cli_args.append(bump)
+
+        if eol_within:
+            cli_args.append("--eol-within")
+            cli_args.append(eol_within)
+
+        if bol_within:
+            cli_args.append("--bol-within")
+            cli_args.append(bol_within)
+
+        return cls(cli_args)
+
+    def __call__(self) -> int:
+        """Run the command.
+
+        Returns:
+            The exit code of the command.
+        """
+        from yore import main as run_yore  # noqa: PLC0415
+
+        return run_yore(self.cli_args)

duty/_internal/validation.py

@@ -0,0 +1,266 @@
+# This module contains logic used to validate parameters passed to duties.
+#
+# We validate the parameters before running the duties,
+# effectively checking all CLI arguments and failing early
+# if they are incorrect.
+
+from __future__ import annotations
+
+import sys
+import textwrap
+from contextlib import suppress
+from functools import cached_property, partial
+from inspect import Parameter, Signature, signature
+from typing import TYPE_CHECKING, Any, Callable, ForwardRef, Union, get_args, get_origin
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# YORE: EOL 3.9: Replace block with lines 6-13.
+if sys.version_info < (3, 10):
+    from eval_type_backport import eval_type_backport as _eval_type
+
+    _union_types = (Union,)
+else:
+    from types import UnionType
+    from typing import _eval_type  # type: ignore[attr-defined]
+
+    if sys.version_info >= (3, 13):
+        _eval_type = partial(_eval_type, type_params=None)
+    _union_types = (Union, UnionType)
+
+
+def to_bool(value: str) -> bool:
+    """Convert a string to a boolean.
+
+    Parameters:
+        value: The string to convert.
+
+    Returns:
+        True or False.
+    """
+    return value.lower() not in {"", "0", "no", "n", "false", "off"}
+
+
+def cast_arg(arg: Any, annotation: Any) -> Any:
+    """Cast an argument using a type annotation.
+
+    Parameters:
+        arg: The argument value.
+        annotation: A type annotation.
+
+    Returns:
+        The cast value.
+    """
+    if annotation is Parameter.empty:
+        return arg
+    if annotation is bool:
+        annotation = to_bool
+    if get_origin(annotation) in _union_types:
+        for sub_annotation in get_args(annotation):
+            if sub_annotation is type(None):
+                continue
+            with suppress(Exception):
+                return cast_arg(arg, sub_annotation)
+    try:
+        return annotation(arg)
+    except Exception:  # noqa: BLE001
+        return arg
+
+
+class ParamsCaster:
+    """A helper class to cast parameters based on a function's signature annotations."""
+
+    def __init__(self, signature: Signature) -> None:
+        """Initialize the object.
+
+        Parameters:
+            signature: The signature to use to cast arguments.
+        """
+        self.params_dict = signature.parameters
+        """A dictionary of parameters, indexed by their name."""
+        self.params_list = list(self.params_dict.values())
+        """A list of parameters, in the order they appear in the signature."""
+
+    @cached_property
+    def var_positional_position(self) -> int:
+        """Give the position of the variable positional parameter in the signature.
+
+        Returns:
+            The position of the variable positional parameter.
+        """
+        for pos, param in enumerate(self.params_list):
+            if param.kind is Parameter.VAR_POSITIONAL:
+                return pos
+        return -1
+
+    @cached_property
+    def has_var_positional(self) -> bool:
+        """Tell if there is a variable positional parameter.
+
+        Returns:
+            True or False.
+        """
+        return self.var_positional_position >= 0
+
+    @cached_property
+    def var_positional_annotation(self) -> Any:
+        """Give the variable positional parameter (`*args`) annotation if any.
+
+        Returns:
+            The variable positional parameter annotation.
+        """
+        return self.params_list[self.var_positional_position].annotation
+
+    @cached_property
+    def var_keyword_annotation(self) -> Any:
+        """Give the variable keyword parameter (`**kwargs`) annotation if any.
+
+        Returns:
+            The variable keyword parameter annotation.
+        """
+        for param in self.params_list:
+            if param.kind is Parameter.VAR_KEYWORD:
+                return param.annotation
+        return Parameter.empty
+
+    def annotation_at_pos(self, pos: int) -> Any:
+        """Give the annotation for the parameter at the given position.
+
+        Parameters:
+            pos: The position of the parameter.
+
+        Returns:
+            The positional parameter annotation.
+        """
+        return self.params_list[pos].annotation
+
+    def eaten_by_var_positional(self, pos: int) -> bool:
+        """Tell if the parameter at this position is eaten by a variable positional parameter.
+
+        Parameters:
+            pos: The position of the parameter.
+
+        Returns:
+            Whether the parameter is eaten.
+        """
+        return self.has_var_positional and pos >= self.var_positional_position
+
+    def cast_posarg(self, pos: int, arg: Any) -> Any:
+        """Cast a positional argument.
+
+        Parameters:
+            pos: The position of the argument in the signature.
+            arg: The argument value.
+
+        Returns:
+            The cast value.
+        """
+        if self.eaten_by_var_positional(pos):
+            return cast_arg(arg, self.var_positional_annotation)
+        return cast_arg(arg, self.annotation_at_pos(pos))
+
+    def cast_kwarg(self, name: str, value: Any) -> Any:
+        """Cast a keyword argument.
+
+        Parameters:
+            name: The name of the argument in the signature.
+            value: The argument value.
+
+        Returns:
+            The cast value.
+        """
+        if name in self.params_dict:
+            return cast_arg(value, self.params_dict[name].annotation)
+        return cast_arg(value, self.var_keyword_annotation)
+
+    def cast(self, *args: Any, **kwargs: Any) -> tuple[Sequence, dict[str, Any]]:
+        """Cast all positional and keyword arguments.
+
+        Parameters:
+            *args: The positional arguments.
+            **kwargs: The keyword arguments.
+
+        Returns:
+            The cast arguments.
+        """
+        positional = tuple(self.cast_posarg(pos, arg) for pos, arg in enumerate(args))
+        keyword = {name: self.cast_kwarg(name, value) for name, value in kwargs.items()}
+        return positional, keyword
+
+
+def _get_params_caster(func: Callable, *args: Any, **kwargs: Any) -> ParamsCaster:
+    duties_module = sys.modules[func.__module__]
+    exec_globals = dict(duties_module.__dict__)
+    eval_str = False
+    for name in list(exec_globals.keys()):
+        if exec_globals[name] is annotations:
+            eval_str = True
+            del exec_globals[name]
+            break
+    exec_globals["__context_above"] = {}
+
+    # Don't keep first parameter: context.
+    params = list(signature(func).parameters.values())[1:]
+    params_no_types = [Parameter(param.name, param.kind, default=param.default) for param in params]
+    code_sig = Signature(parameters=params_no_types)
+    if eval_str:
+        params_types = [
+            Parameter(
+                param.name,
+                param.kind,
+                default=param.default,
+                annotation=(
+                    _eval_type(
+                        ForwardRef(param.annotation) if isinstance(param.annotation, str) else param.annotation,
+                        exec_globals,
+                        {},
+                    )
+                    if param.annotation is not Parameter.empty
+                    else type(param.default)
+                ),
+            )
+            for param in params
+        ]
+    else:
+        params_types = params
+    cast_sig = Signature(parameters=params_types)
+
+    code = f"""
+        import inspect
+        def {func.__name__}{code_sig}: ...
+        __context_above['func'] = {func.__name__}
+    """
+
+    exec(textwrap.dedent(code), exec_globals)  # noqa: S102
+    func = exec_globals["__context_above"]["func"]
+
+    # Trigger TypeError early.
+    func(*args, **kwargs)
+
+    return ParamsCaster(cast_sig)
+
+
+def validate(
+    func: Callable,
+    *args: Any,
+    **kwargs: Any,
+) -> tuple[Sequence, dict[str, Any]]:
+    """Validate positional and keyword arguments against a function.
+
+    First we clone the function, removing the first parameter (the context)
+    and the body, to fail early with a `TypeError` if the arguments
+    are incorrect: not enough, too much, in the wrong order, etc.
+
+    Then we cast all the arguments using the function's signature
+    and we return them.
+
+    Parameters:
+        func: The function to copy.
+        *args: The positional arguments.
+        **kwargs: The keyword arguments.
+
+    Returns:
+        The casted arguments.
+    """
+    return _get_params_caster(func, *args, **kwargs).cast(*args, **kwargs)

duty/callables/__init__.py

@@ -3,13 +3,15 @@
 These callables are **deprecated** in favor of our new [tools][duty.tools].
 """
 
+# YORE: Bump 2: Remove file.
+
 from __future__ import annotations
 
 import warnings
 
-from failprint.lazy import lazy
+from failprint import lazy  # noqa: F401
 
-from duty.callables import (
+from duty._internal.callables import (
     autoflake,  # noqa: F401
     black,  # noqa: F401
     blacken_docs,  # noqa: F401
@@ -29,8 +31,6 @@ from duty.callables import (
     twine,  # noqa: F401
 )
 
-__all__ = ["lazy"]
-
 warnings.warn(
     "Callables are deprecated in favor of our new `duty.tools`. "
     "They are easier to use and provide more functionality "

duty/callables/autoflake.py

@@ -1,132 +1,17 @@
-"""Callable for [autoflake](https://github.com/PyCQA/autoflake)."""
+"""Deprecated. Use [`duty.tools.autoflake`][] instead."""
 
-from __future__ import annotations
+# YORE: Bump 2: Remove file.
 
-from failprint.lazy import lazy
+import warnings
+from typing import Any
 
-from duty.callables import _io
+from duty._internal.callables import autoflake as _autoflake
 
 
-@lazy(name="autoflake")
-def run(
-    *files: str,
-    config: str | None = None,
-    check: bool | None = None,
-    check_diff: bool | None = None,
-    imports: list[str] | None = None,
-    remove_all_unused_imports: bool | None = None,
-    recursive: bool | None = None,
-    jobs: int | None = None,
-    exclude: list[str] | None = None,
-    expand_star_imports: bool | None = None,
-    ignore_init_module_imports: bool | None = None,
-    remove_duplicate_keys: bool | None = None,
-    remove_unused_variables: bool | None = None,
-    remove_rhs_for_unused_variables: bool | None = None,
-    ignore_pass_statements: bool | None = None,
-    ignore_pass_after_docstring: bool | None = None,
-    quiet: bool | None = None,
-    verbose: bool | None = None,
-    stdin_display_name: str | None = None,
-    in_place: bool | None = None,
-    stdout: bool | None = None,
-) -> int:
-    r"""Run `autoflake`.
-
-    Parameters:
-        *files: Files to format.
-        config: Explicitly set the config file instead of auto determining based on file location.
-        check: Return error code if changes are needed.
-        check_diff: Return error code if changes are needed, also display file diffs.
-        imports: By default, only unused standard library imports are removed; specify a comma-separated list of additional modules/packages.
-        remove_all_unused_imports: Remove all unused imports (not just those from the standard library).
-        recursive: Drill down directories recursively.
-        jobs: Number of parallel jobs; match CPU count if value is 0 (default: 0).
-        exclude: Exclude file/directory names that match these comma-separated globs.
-        expand_star_imports: Expand wildcard star imports with undefined names; this only triggers if there is only one star import in the file; this is skipped if there are any uses of `__all__` or `del` in the file.
-        ignore_init_module_imports: Exclude `__init__.py` when removing unused imports.
-        remove_duplicate_keys: Remove all duplicate keys in objects.
-        remove_unused_variables: Remove unused variables.
-        remove_rhs_for_unused_variables: Remove RHS of statements when removing unused variables (unsafe).
-        ignore_pass_statements: Ignore all pass statements.
-        ignore_pass_after_docstring: Ignore pass statements after a newline ending on `\"\"\"`.
-        quiet: Suppress output if there are no issues.
-        verbose: Print more verbose logs (you can repeat `-v` to make it more verbose).
-        stdin_display_name: The name used when processing input from stdin.
-        in_place: Make changes to files instead of printing diffs.
-        stdout: Print changed text to stdout. defaults to true when formatting stdin, or to false otherwise.
-    """
-    from autoflake import _main as autoflake
-
-    cli_args = list(files)
-
-    if check:
-        cli_args.append("--check")
-
-    if check_diff:
-        cli_args.append("--check-diff")
-
-    if imports:
-        cli_args.append("--imports")
-        cli_args.append(",".join(imports))
-
-    if remove_all_unused_imports:
-        cli_args.append("--remove-all-unused-imports")
-
-    if recursive:
-        cli_args.append("--recursive")
-
-    if jobs:
-        cli_args.append("--jobs")
-        cli_args.append(str(jobs))
-
-    if exclude:
-        cli_args.append("--exclude")
-        cli_args.append(",".join(exclude))
-
-    if expand_star_imports:
-        cli_args.append("--expand-star-imports")
-
-    if ignore_init_module_imports:
-        cli_args.append("--ignore-init-module-imports")
-
-    if remove_duplicate_keys:
-        cli_args.append("--remove-duplicate-keys")
-
-    if remove_unused_variables:
-        cli_args.append("--remove-unused-variables")
-
-    if remove_rhs_for_unused_variables:
-        cli_args.append("remove-rhs-for-unused-variables")
-
-    if ignore_pass_statements:
-        cli_args.append("--ignore-pass-statements")
-
-    if ignore_pass_after_docstring:
-        cli_args.append("--ignore-pass-after-docstring")
-
-    if quiet:
-        cli_args.append("--quiet")
-
-    if verbose:
-        cli_args.append("--verbose")
-
-    if stdin_display_name:
-        cli_args.append("--stdin-display-name")
-        cli_args.append(stdin_display_name)
-
-    if config:
-        cli_args.append("--config")
-        cli_args.append(config)
-
-    if in_place:
-        cli_args.append("--in-place")
-
-    if stdout:
-        cli_args.append("--stdout")
-
-    return autoflake(
-        cli_args,
-        standard_out=_io._LazyStdout(),
-        standard_error=_io._LazyStderr(),
+def __getattr__(name: str) -> Any:
+    warnings.warn(
+        "Callables are deprecated in favor of tools, use `duty.tools.autoflake` instead of `duty.callables.autoflake`.",
+        DeprecationWarning,
+        stacklevel=2,
     )
+    return getattr(_autoflake, name)