duty 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

duty/callables/__init__.py

@@ -1,33 +1,41 @@
 """Module containing callables for many tools.
 
-Tip: Call to developers!
-    If you are the author or maintainer of one of the tools we support
-    (or more generally if you are the author/maintainer of a Python CLI/library),
-    we kindly request that you add such a callable to your code base. Why?
-
-    - Most of the time, all `duty` can do is hook into the CLI entrypoint
-        for the lack of a better alternative. This is not ideal because
-        we have to translate function arguments to CLI arguments,
-        that are then parsed again and translated back to Python objects
-        by the tool itself. This is not efficient.
-    - It is not feasible for `duty` to maintain callables for different versions
-        of these tools. Having the callables maintained in the tools
-        themselves would make this support transparent.
-    - We believe it simply provides a better user- *and* developer-experience.
-        Clear separation of concerns: don't intertwine logic into the CLI parser.
-        Easy to maintain, easy to test. The CLI parser just has to translate CLI args
-        to their equivalent Python arguments.
-
-    Tips for writing such a library entry point:
-
-    - Make it equivalent to the CLI entry point: every flag and option must have an equivalent parameter.
-        Slight customizations can be made to support `--flag` / `--no-flag` with single parameters.
-    - Use only built-in types: don't make users import and use objects from your API.
-        For example, accept a list of strings, not a list of `MyCustomClass` instances.
+These callables are **deprecated** in favor of our new [tools][duty.tools].
 """
 
 from __future__ import annotations
 
+import warnings
+
 from failprint.lazy import lazy
 
+from duty.callables import (
+    autoflake,  # noqa: F401
+    black,  # noqa: F401
+    blacken_docs,  # noqa: F401
+    build,  # noqa: F401
+    coverage,  # noqa: F401
+    flake8,  # noqa: F401
+    git_changelog,  # noqa: F401
+    griffe,  # noqa: F401
+    interrogate,  # noqa: F401
+    isort,  # noqa: F401
+    mkdocs,  # noqa: F401
+    mypy,  # noqa: F401
+    pytest,  # noqa: F401
+    ruff,  # noqa: F401
+    safety,  # noqa: F401
+    ssort,  # noqa: F401
+    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 "
+    "like automatically computing `command` values in `ctx.run()` calls. "
+    "Old callables will be removed in a future version.",
+    DeprecationWarning,
+    stacklevel=1,
+)

duty/callables/build.py

@@ -0,0 +1,76 @@
+"""Callable for [build](https://github.com/pypa/build)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from failprint.lazy import lazy
+
+
+@lazy(name="build")
+def run(
+    srcdir: str | None = None,
+    *,
+    version: bool = False,
+    verbose: bool = False,
+    sdist: bool = False,
+    wheel: bool = False,
+    outdir: str | None = None,
+    skip_dependency_check: bool = False,
+    no_isolation: bool = False,
+    installer: Literal["pip", "uv"] | None = None,
+    config_setting: list[str] | None = None,
+) -> None:
+    """Run `build`.
+
+    Parameters:
+        srcdir: Source directory (defaults to current directory).
+        version: Show program's version number and exit.
+        verbose: Increase verbosity
+        sdist: Build a source distribution (disables the default behavior).
+        wheel: Build a wheel (disables the default behavior).
+        outdir: Output directory (defaults to `{srcdir}/dist`).
+        skip_dependency_check: Do not check that build dependencies are installed.
+        no_isolation: Disable building the project in an isolated virtual environment.
+            Build dependencies must be installed separately when this option is used.
+        installer: Python package installer to use (defaults to pip).
+        config_setting: Settings to pass to the backend. Multiple settings can be provided.
+    """
+    from build.__main__ import main as build
+
+    cli_args = []
+
+    if srcdir:
+        cli_args.append(srcdir)
+
+    if version:
+        cli_args.append("--version")
+
+    if verbose:
+        cli_args.append("--verbose")
+
+    if sdist:
+        cli_args.append("--sdist")
+
+    if wheel:
+        cli_args.append("--wheel")
+
+    if outdir:
+        cli_args.append("--outdir")
+        cli_args.append(outdir)
+
+    if skip_dependency_check:
+        cli_args.append("--skip-dependency-check")
+
+    if no_isolation:
+        cli_args.append("--no-isolation")
+
+    if installer:
+        cli_args.append("--installer")
+        cli_args.append(installer)
+
+    if config_setting:
+        for setting in config_setting:
+            cli_args.append(f"--config-setting={setting}")
+
+    build(cli_args)

duty/callables/git_changelog.py

@@ -0,0 +1,178 @@
+"""Callable for [git-changelog](https://github.com/pawamoy/git-changelog)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from failprint.lazy import lazy
+
+
+@lazy(name="git_changelog")
+def run(
+    repository: str | None = None,
+    *,
+    config_file: str | None = None,
+    bump: str | None = None,
+    versioning: Literal["semver", "pep440"] | None = None,
+    in_place: bool = False,
+    version_regex: str | None = None,
+    marker_line: str | None = None,
+    output: str | None = None,
+    provider: Literal["github", "gitlab", "bitbucket"] | None = None,
+    parse_refs: bool = False,
+    release_notes: bool = False,
+    input: str | None = None,  # noqa: A002
+    convention: Literal["basic", "angular", "conventional"] | None = None,
+    sections: list[str] | None = None,
+    template: str | None = None,
+    git_trailers: bool = False,
+    omit_empty_versions: bool = False,
+    no_zerover: bool = False,
+    filter_commits: str | None = None,
+    jinja_context: list[str] | None = None,
+    version: bool = False,
+    debug_info: bool = False,
+) -> None:
+    r"""Run `git-changelog`.
+
+    Parameters:
+        repository: The repository path, relative or absolute. Default: current working directory.
+        config_file: Configuration file(s).
+        bump: Specify the bump from latest version for the set of unreleased commits.
+            Can be one of `auto`, `major`, `minor`, `patch` or a valid SemVer version (eg. 1.2.3).
+            For both SemVer and PEP 440 versioning schemes (see -n), `auto` will bump the major number
+            if a commit contains breaking changes (or the minor number for 0.x versions, see -Z),
+            else the minor number if there are new features, else the patch number. Default: unset (false).
+        versioning: Versioning scheme to use when bumping and comparing versions.
+            The selected scheme will impact the values accepted by the `--bump` option.
+            Supported: `pep440`, `semver`.
+
+            PEP 440 provides the following bump strategies: `auto`, `epoch`, `release`, `major`, `minor`, `micro`, `patch`,
+            `pre`, `alpha`, `beta`, `candidate`, `post`, `dev`.
+            Values `auto`, `major`, `minor`, `micro` can be suffixed with one of `+alpha`, `+beta`, `+candidate`, and/or `+dev`.
+            Values `alpha`, `beta` and `candidate` can be suffixed with `+dev`.
+            Examples: `auto+alpha`, `major+beta+dev`, `micro+dev`, `candidate+dev`, etc..
+
+            SemVer provides the following bump strategies: `auto`, `major`, `minor`, `patch`, `release`.
+            See the docs for more information. Default: unset (`semver`).
+        in_place: Insert new entries (versions missing from changelog) in-place.
+            An output file must be specified. With custom templates, you can pass two additional
+            arguments: `--version-regex` and `--marker-line`.
+            When writing in-place, an `in_place` variable will be injected in the Jinja context,
+            allowing to adapt the generated contents (for example to skip changelog headers or footers).
+            Default: unset (false).
+        version_regex: A regular expression to match versions in the existing changelog
+            (used to find the latest release) when writing in-place.
+            The regular expression must be a Python regex with a `version` named group.
+            Default: `^## \[(?P<version>v?[^\]]+)`.
+        marker_line: A marker line at which to insert new entries (versions missing from changelog).
+            If two marker lines are present in the changelog, the contents between those two lines
+            will be overwritten (useful to update an 'Unreleased' entry for example). Default: `<!-- insertion marker -->`.
+        output: Output to given file. Default: standard output.
+        provider: Explicitly specify the repository provider. Default: unset.
+        parse_refs: Parse provider-specific references in commit messages (GitHub/GitLab/Bitbucket issues, PRs, etc.).
+            Default: unset (false).
+        release_notes: Output release notes to stdout based on the last entry in the changelog. Default: unset (false).
+        input: Read from given file when creating release notes. Default: `CHANGELOG.md`.
+        convention: The commit convention to match against. Default: `basic`.
+        sections: A comma-separated list of sections to render.
+            See the available sections for each supported convention in the description. Default: unset (None).
+        template: The Jinja2 template to use.
+            Prefix it with `path:` to specify the path to a Jinja templated file. Default: `keepachangelog`.
+        git_trailers: Parse Git trailers in the commit message.
+            See https://git-scm.com/docs/git-interpret-trailers. Default: unset (false).
+        omit_empty_versions: Omit empty versions from the output. Default: unset (false).
+        no_zerover: By default, breaking changes on a 0.x don't bump the major version, maintaining it at 0.
+            With this option, a breaking change will bump a 0.x version to 1.0.
+        filter_commits: The Git revision-range filter to use (e.g. `v1.2.0..`). Default: no filter.
+        jinja_context: Pass additional key/value pairs to the template.
+            Option can be used multiple times.
+            The key/value pairs are accessible as 'jinja_context' in the template.
+        version: Show the current version of the program and exit.
+        debug_info: Print debug information.
+    """
+    from git_changelog.cli import main as git_changelog
+
+    cli_args = []
+
+    if repository:
+        cli_args.append(repository)
+
+    if config_file:
+        cli_args.append("--config-file")
+        cli_args.append(config_file)
+
+    if bump:
+        cli_args.append("--bump")
+        cli_args.append(bump)
+
+    if versioning:
+        cli_args.append("--versioning")
+        cli_args.append(versioning)
+
+    if in_place:
+        cli_args.append("--in-place")
+
+    if version_regex:
+        cli_args.append("--version-regex")
+        cli_args.append(version_regex)
+
+    if marker_line:
+        cli_args.append("--marker-line")
+        cli_args.append(marker_line)
+
+    if output:
+        cli_args.append("--output")
+        cli_args.append(output)
+
+    if provider:
+        cli_args.append("--provider")
+        cli_args.append(provider)
+
+    if parse_refs:
+        cli_args.append("--parse-refs")
+
+    if release_notes:
+        cli_args.append("--release-notes")
+
+    if input:
+        cli_args.append("--input")
+        cli_args.append(input)
+
+    if convention:
+        cli_args.append("--convention")
+        cli_args.append(convention)
+
+    if sections:
+        cli_args.append("--sections")
+        cli_args.append(",".join(sections))
+
+    if template:
+        cli_args.append("--template")
+        cli_args.append(template)
+
+    if git_trailers:
+        cli_args.append("--git-trailers")
+
+    if omit_empty_versions:
+        cli_args.append("--omit-empty-versions")
+
+    if no_zerover:
+        cli_args.append("--no-zerover")
+
+    if filter_commits:
+        cli_args.append("--filter-commits")
+        cli_args.append(filter_commits)
+
+    if jinja_context:
+        for key_value in jinja_context:
+            cli_args.append("--jinja-context")
+            cli_args.append(key_value)
+
+    if version:
+        cli_args.append("--version")
+
+    if debug_info:
+        cli_args.append("--debug-info")
+
+    git_changelog(cli_args)

duty/callables/griffe.py

@@ -0,0 +1,227 @@
+"""Callable for [Griffe](https://github.com/mkdocstrings/griffe)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from failprint.lazy import lazy
+
+
+def run(*args: str, version: bool = False, debug_info: bool = False) -> None:
+    """Run `griffe`.
+
+    Parameters:
+        *args: CLI arguments.
+        version: Show program's version number and exit.
+        debug_info: Print debug information.
+    """
+    from griffe.cli import main as griffe
+
+    cli_args = []
+
+    # --version and --debug-info must appear first.
+    if version:
+        cli_args.append("--version")
+
+    if debug_info:
+        cli_args.append("--debug-info")
+
+    cli_args.extend(args)
+
+    griffe(cli_args)
+
+
+@lazy(name="griffe.check")
+def check(
+    package: str,
+    *,
+    against: str | None = None,
+    base_ref: str | None = None,
+    color: bool = False,
+    verbose: bool = False,
+    format: Literal["oneline", "verbose", "markdown", "github"] | None = None,  # noqa: A002
+    search: list[str] | None = None,
+    sys_path: bool = False,
+    find_stubs_packages: bool = False,
+    extensions: str | list[str] | None = None,
+    inspection: bool | None = None,
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+    version: bool = False,
+    debug_info: bool = False,
+) -> None:
+    """Check for API breakages or possible improvements.
+
+    Parameters:
+        package: Package to find, load and check, as path.
+        against: Older Git reference (commit, branch, tag) to check against. Default: load latest tag.
+        base_ref: Git reference (commit, branch, tag) to check. Default: load current code.
+        color: Force enable/disable colors in the output.
+        verbose: Verbose output.
+        format: Output format.
+        search: Paths to search packages into.
+        sys_path: Whether to append `sys.path` to search paths specified with `-s`.
+        find_stubs_packages: Whether to look for stubs-only packages and merge them with concrete ones.
+        extensions: A comma-separated list or a JSON list of extensions to load.
+        inspection: Whether to disallow or force inspection (dynamic analysis).
+            By default, Griffe tries to use static analysis and falls back to dynamic analysis when it can't.
+        log_level: Set the log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
+        version: Show program's version number and exit.
+        debug_info: Print debug information.
+    """
+    cli_args = []
+
+    if package:
+        cli_args.append(package)
+
+    if against:
+        cli_args.append("--against")
+        cli_args.append(against)
+
+    if base_ref:
+        cli_args.append("--base-ref")
+        cli_args.append(base_ref)
+
+    if color is True:
+        cli_args.append("--color")
+    elif color is False:
+        cli_args.append("--no-color")
+
+    if verbose:
+        cli_args.append("--verbose")
+
+    if format:
+        cli_args.append("--format")
+        cli_args.append(format)
+
+    if search:
+        for path in search:
+            cli_args.append("--search")
+            cli_args.append(path)
+
+    if sys_path:
+        cli_args.append("--sys-path")
+
+    if find_stubs_packages:
+        cli_args.append("--find-stubs-packages")
+
+    if extensions:
+        cli_args.append("--extensions")
+        if isinstance(extensions, str):
+            cli_args.append(extensions)
+        else:
+            cli_args.append(",".join(extensions))
+
+    if inspection is True:
+        cli_args.append("--force-inspection")
+    elif inspection is False:
+        cli_args.append("--no-inspection")
+
+    if log_level:
+        cli_args.append("--log-level")
+        cli_args.append(log_level)
+
+    run("check", *cli_args, version=version, debug_info=debug_info)
+
+
+@lazy(name="griffe.dump")
+def dump(
+    *packages: str,
+    full: bool = False,
+    output: str | None = None,
+    docstyle: str | None = None,
+    docopts: str | None = None,
+    resolve_aliases: bool = False,
+    resolve_implicit: bool = False,
+    resolve_external: bool | None = None,
+    stats: bool = False,
+    search: list[str] | None = None,
+    sys_path: bool = False,
+    find_stubs_packages: bool = False,
+    extensions: str | list[str] | None = None,
+    inspection: bool | None = None,
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+    version: bool = False,
+    debug_info: bool = False,
+) -> None:
+    """Load package-signatures and dump them as JSON.
+
+    Parameters:
+        packages: Packages to find, load and dump.
+        full: Whether to dump full data in JSON.
+        output: Output file. Supports templating to output each package in its own file, with `{package}`.
+        docstyle: The docstring style to parse.
+        docopts: The options for the docstring parser.
+        resolve_aliases: Whether to resolve aliases.
+        resolve_implicit: Whether to resolve implicitely exported aliases as well. Aliases are explicitely exported when defined in `__all__`.
+        resolve_external: Whether to resolve aliases pointing to external/unknown modules (not loaded directly).
+            Default is to resolve only from one module to its private sibling (`ast` -> `_ast`).
+        stats: Show statistics at the end.
+        search: Paths to search packages into.
+        sys_path: Whether to append `sys.path` to search paths specified with `-s`.
+        find_stubs_packages: Whether to look for stubs-only packages and merge them with concrete ones.
+        extensions: A comma-separated list or a JSON list of extensions to load.
+        inspection: Whether to disallow or force inspection (dynamic analysis).
+            By default, Griffe tries to use static analysis and falls back to dynamic analysis when it can't.
+        log_level: Set the log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
+        version: Show program's version number and exit.
+        debug_info: Print debug information.
+    """
+    cli_args = list(packages)
+
+    if full:
+        cli_args.append("--full")
+
+    if output:
+        cli_args.append("--output")
+        cli_args.append(output)
+
+    if docstyle:
+        cli_args.append("--docstyle")
+        cli_args.append(docstyle)
+
+    if docopts:
+        cli_args.append("--docopts")
+        cli_args.append(docopts)
+
+    if resolve_aliases:
+        cli_args.append("--resolve-aliases")
+
+    if resolve_implicit:
+        cli_args.append("--resolve-implicit")
+
+    if resolve_external is True:
+        cli_args.append("--resolve-external")
+    elif resolve_external is False:
+        cli_args.append("--no-resolve-external")
+
+    if stats:
+        cli_args.append("--stats")
+
+    if search:
+        for path in search:
+            cli_args.append("--search")
+            cli_args.append(path)
+
+    if sys_path:
+        cli_args.append("--sys-path")
+
+    if find_stubs_packages:
+        cli_args.append("--find-stubs-packages")
+
+    if extensions:
+        cli_args.append("--extensions")
+        if isinstance(extensions, str):
+            cli_args.append(extensions)
+        else:
+            cli_args.append(",".join(extensions))
+
+    if inspection is True:
+        cli_args.append("--force-inspection")
+    elif inspection is False:
+        cli_args.append("--no-inspection")
+
+    if log_level:
+        cli_args.append("--log-level")
+        cli_args.append(log_level)
+
+    run("check", *cli_args, version=version, debug_info=debug_info)