peta 0.1.0__py3-none-any.whl

peta/__init__.py

@@ -0,0 +1 @@
+"""peta - Human-friendly Python package metadata viewer."""

peta/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for ``python -m peta``."""
+
+from __future__ import annotations
+
+from peta.cli.app import run
+
+run()

peta/__metadata__.py

@@ -0,0 +1,6 @@
+"""Metadata for the project."""
+
+PROJECT_NAME: str = "peta"
+"""Name of the project."""
+
+__all__ = ["PROJECT_NAME"]

peta/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

peta/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface."""

peta/cli/app.py

@@ -0,0 +1,214 @@
+"""Typer application and command registration."""
+
+from __future__ import annotations
+
+import sys
+from importlib.metadata import Distribution, PackageNotFoundError
+from typing import Annotated, cast
+
+import typer
+
+from peta.__metadata__ import PROJECT_NAME
+from peta.cli.commands import (
+    compare as compare_mod,
+    deps as deps_mod,
+    files as files_mod,
+    info as info_mod,
+    versions as versions_mod,
+)
+from peta.cli.output.console import resolve_color
+from peta.cli.state import CliState
+
+__all__ = ["compare", "deps", "files", "info", "main", "run", "versions"]
+
+
+_SUBCOMMANDS = {
+    "info",
+    "deps",
+    "files",
+    "versions",
+    "compare",
+    "--help",
+    "-h",
+    "--version",
+    "-V",
+}
+
+app = typer.Typer(
+    name="peta",
+    help="Human-friendly Python package metadata viewer.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    try:
+        distribution = Distribution.from_name(PROJECT_NAME)
+    except PackageNotFoundError as exc:
+        typer.echo("Error: peta package metadata not found.", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"peta {distribution.version}")
+    raise typer.Exit
+
+
+def _color_from_ctx(ctx: typer.Context) -> bool:
+    """Read the resolved color setting stashed on the root context.
+
+    Returns:
+        The resolved color flag, or ``False`` if unavailable (e.g. the root
+        callback did not run, as can happen when invoking a command object
+        directly in tests).
+    """
+    obj = cast("object", ctx.obj)
+    return obj.color if isinstance(obj, CliState) else False
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+    no_color: Annotated[
+        bool, typer.Option("--no-color", help="Disable colored output.")
+    ] = False,
+) -> None:
+    """Human-friendly Python package metadata viewer."""
+    ctx.obj = CliState(color=resolve_color(no_color=no_color))
+
+
+@app.command()
+def info(
+    ctx: typer.Context,
+    package: Annotated[
+        str, typer.Argument(help="Package name (optionally name==version).")
+    ],
+    use_json: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+    local: Annotated[
+        bool, typer.Option("--local", "-l", help="Force local lookup.")
+    ] = False,
+    remote: Annotated[
+        bool, typer.Option("--remote", "-r", help="Force PyPI lookup.")
+    ] = False,
+    no_osv: Annotated[
+        bool, typer.Option("--no-osv", help="Skip the OSV vulnerability lookup.")
+    ] = False,
+    no_stats: Annotated[
+        bool, typer.Option("--no-stats", help="Skip download/dependent count lookups.")
+    ] = False,
+) -> None:
+    """Show detailed package metadata."""
+    info_mod.info(
+        package,
+        use_json=use_json,
+        local=local,
+        remote=remote,
+        color=_color_from_ctx(ctx),
+        no_osv=no_osv,
+        no_stats=no_stats,
+    )
+
+
+@app.command()
+def compare(
+    ctx: typer.Context,
+    a: Annotated[str, typer.Argument(help="First package name.")],
+    b: Annotated[str, typer.Argument(help="Second package name.")],
+    use_json: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+    local: Annotated[
+        bool, typer.Option("--local", "-l", help="Force local lookup.")
+    ] = False,
+    remote: Annotated[
+        bool, typer.Option("--remote", "-r", help="Force PyPI lookup.")
+    ] = False,
+    no_osv: Annotated[
+        bool, typer.Option("--no-osv", help="Skip the OSV vulnerability lookup.")
+    ] = False,
+    no_stats: Annotated[
+        bool, typer.Option("--no-stats", help="Skip download/dependent count lookups.")
+    ] = False,
+) -> None:
+    """Compare two packages' metadata side by side."""
+    compare_mod.compare(
+        a,
+        b,
+        use_json=use_json,
+        local=local,
+        remote=remote,
+        color=_color_from_ctx(ctx),
+        no_osv=no_osv,
+        no_stats=no_stats,
+    )
+
+
+@app.command()
+def deps(
+    ctx: typer.Context,
+    package: Annotated[str, typer.Argument(help="Package name.")],
+    use_json: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+    local: Annotated[
+        bool, typer.Option("--local", "-l", help="Force local lookup.")
+    ] = False,
+    remote: Annotated[
+        bool, typer.Option("--remote", "-r", help="Force PyPI lookup.")
+    ] = False,
+    why: Annotated[
+        str | None, typer.Option("--why", help="Show why TARGET is a dependency.")
+    ] = None,
+    depth: Annotated[
+        int, typer.Option("--depth", min=1, help="Max recursion depth.")
+    ] = 10,
+) -> None:
+    """Show a package's recursive dependency tree."""
+    deps_mod.deps(
+        package,
+        use_json=use_json,
+        local=local,
+        remote=remote,
+        color=_color_from_ctx(ctx),
+        why=why,
+        depth=depth,
+    )
+
+
+@app.command()
+def files(
+    ctx: typer.Context,
+    package: Annotated[str, typer.Argument(help="Package name.")],
+    use_json: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+) -> None:
+    """List files installed by a local package."""
+    files_mod.files(package, use_json=use_json, color=_color_from_ctx(ctx))
+
+
+@app.command()
+def versions(
+    ctx: typer.Context,
+    package: Annotated[str, typer.Argument(help="Package name.")],
+    use_json: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+    limit: Annotated[
+        int, typer.Option("--limit", "-n", min=1, help="Max versions to show.")
+    ] = 20,
+) -> None:
+    """Show published versions of a package from PyPI."""
+    versions_mod.versions(
+        package, use_json=use_json, limit=limit, color=_color_from_ctx(ctx)
+    )
+
+
+def run() -> None:
+    """Entry point; ``peta <package>`` is shorthand for ``peta info <package>``."""
+    args = sys.argv[1:]
+    if args and args[0] not in _SUBCOMMANDS and not args[0].startswith("-"):
+        sys.argv.insert(1, "info")
+    app()

peta/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command handlers."""

peta/cli/commands/compare.py

@@ -0,0 +1,70 @@
+"""The ``peta compare`` command."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+from peta.cli.output.json import format_compare as json_format
+from peta.cli.output.tables import render_compare as rich_format
+from peta.core.enrich import enrich
+from peta.core.local import PackageNotFoundError as LocalNotFound
+from peta.core.remote import NetworkError, PackageNotFoundError as RemoteNotFound
+from peta.core.resolve import resolve_package
+
+if TYPE_CHECKING:
+    from peta.core.models import PackageInfo
+
+__all__ = ["compare"]
+
+
+# Tuple constant (not an inline ``except (A, B)`` literal) so the ruff formatter
+# cannot strip the parentheses into Python-2-only ``except A, B`` syntax.
+_NOT_FOUND = (LocalNotFound, RemoteNotFound)
+
+
+def _resolve_and_enrich(
+    package: str, *, local: bool, remote: bool, no_osv: bool, no_stats: bool
+) -> PackageInfo:
+    pkg = resolve_package(package, local=local, remote=remote)
+    return enrich(pkg, no_osv=no_osv, no_stats=no_stats)
+
+
+def compare(
+    a: str,
+    b: str,
+    *,
+    use_json: bool = False,
+    local: bool = False,
+    remote: bool = False,
+    color: bool = False,
+    no_osv: bool = False,
+    no_stats: bool = False,
+) -> None:
+    """Compare two packages' metadata side by side.
+
+    Raises:
+        Exit: With code 1 if either package is not found, or code 2 on network
+            failure.
+    """
+    try:
+        a_pkg = _resolve_and_enrich(
+            a, local=local, remote=remote, no_osv=no_osv, no_stats=no_stats
+        )
+        b_pkg = _resolve_and_enrich(
+            b, local=local, remote=remote, no_osv=no_osv, no_stats=no_stats
+        )
+    except _NOT_FOUND as exc:
+        version = getattr(exc, "version", None)
+        target = f"{exc.name}=={version}" if version else exc.name
+        typer.echo(f"Package '{target}' not found.", err=True)
+        raise typer.Exit(code=1) from None
+    except NetworkError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from None
+    typer.echo(
+        json_format(a_pkg, b_pkg)
+        if use_json
+        else rich_format(a_pkg, b_pkg, color=color)
+    )

peta/cli/commands/deps.py

@@ -0,0 +1,81 @@
+"""The ``peta deps`` command."""
+
+from __future__ import annotations
+
+import typer
+
+from peta.cli.output.json import format_dep_tree, format_why
+from peta.cli.output.tables import render_dep_tree, render_why
+from peta.core.deptree import build_tree, find_why
+from peta.core.local import PackageNotFoundError as LocalNotFound
+from peta.core.remote import NetworkError, PackageNotFoundError as RemoteNotFound
+
+__all__ = ["deps"]
+
+
+# Tuple constant (not an inline ``except (A, B)`` literal) so the ruff formatter
+# cannot strip the parentheses into Python-2-only ``except A, B`` syntax.
+_NOT_FOUND = (LocalNotFound, RemoteNotFound)
+
+
+def _print_why(
+    package: str,
+    target: str,
+    paths: list[list[str]],
+    *,
+    use_json: bool,
+    color: bool,
+    depth: int,
+) -> None:
+    if not paths:
+        msg = (
+            f"'{target}' was not found in the dependency tree of "
+            f"'{package}' (depth {depth})."
+        )
+        typer.echo(msg, err=True)
+        raise typer.Exit(code=1)
+    typer.echo(
+        format_why(target, paths)
+        if use_json
+        else render_why(target, paths, color=color)
+    )
+
+
+def deps(
+    package: str,
+    *,
+    use_json: bool = False,
+    local: bool = False,
+    remote: bool = False,
+    color: bool = False,
+    why: str | None = None,
+    depth: int = 10,
+) -> None:
+    """Show a package's recursive dependency tree, or ``--why`` a target is pulled in.
+
+    Raises:
+        Exit: With code 1 if the package (or, with ``--why``, the target) is
+            not found, or code 2 on network failure.
+    """
+    try:
+        tree = build_tree(package, local=local, remote=remote, max_depth=depth)
+    except _NOT_FOUND:
+        typer.echo(f"Package '{package}' not found.", err=True)
+        raise typer.Exit(code=1) from None
+    except NetworkError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from None
+
+    if why is not None:
+        _print_why(
+            package,
+            why,
+            find_why(tree, why),
+            use_json=use_json,
+            color=color,
+            depth=depth,
+        )
+        return
+    typer.echo(
+        format_dep_tree(tree) if use_json else render_dep_tree(tree, color=color)
+    )

peta/cli/commands/files.py

@@ -0,0 +1,28 @@
+"""The ``peta files`` command."""
+
+from __future__ import annotations
+
+import typer
+
+from peta.cli.output.json import format_files as json_format
+from peta.cli.output.tables import render_files as rich_format
+from peta.core.local import (
+    PackageNotFoundError as LocalNotFound,
+    get_package as local_get_package,
+)
+
+__all__ = ["files"]
+
+
+def files(package: str, *, use_json: bool = False, color: bool = False) -> None:
+    """List files installed by a local package.
+
+    Raises:
+        Exit: With code 1 if the package is not installed locally.
+    """
+    try:
+        pkg = local_get_package(package)
+    except LocalNotFound:
+        typer.echo(f"Package '{package}' not found locally.", err=True)
+        raise typer.Exit(code=1) from None
+    typer.echo(json_format(pkg) if use_json else rich_format(pkg, color=color))

peta/cli/commands/info.py

@@ -0,0 +1,59 @@
+"""The ``peta info`` command."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+from peta.cli.output.json import format_info as json_format
+from peta.cli.output.tables import render_info as rich_format
+from peta.core.enrich import enrich
+from peta.core.local import PackageNotFoundError as LocalNotFound
+from peta.core.remote import NetworkError, PackageNotFoundError as RemoteNotFound
+from peta.core.resolve import resolve_package
+
+if TYPE_CHECKING:
+    from peta.core.models import PackageInfo
+
+__all__ = ["info"]
+
+
+# Tuple constant (not an inline ``except (A, B)`` literal) so the ruff formatter
+# cannot strip the parentheses into Python-2-only ``except A, B`` syntax.
+_NOT_FOUND = (LocalNotFound, RemoteNotFound)
+
+
+def _resolve_and_enrich(
+    package: str, *, local: bool, remote: bool, no_osv: bool, no_stats: bool
+) -> PackageInfo:
+    pkg = resolve_package(package, local=local, remote=remote)
+    return enrich(pkg, no_osv=no_osv, no_stats=no_stats)
+
+
+def info(
+    package: str,
+    *,
+    use_json: bool = False,
+    local: bool = False,
+    remote: bool = False,
+    color: bool = False,
+    no_osv: bool = False,
+    no_stats: bool = False,
+) -> None:
+    """Show detailed package metadata.
+
+    Raises:
+        Exit: With code 1 if the package is not found, or code 2 on network failure.
+    """
+    try:
+        pkg = _resolve_and_enrich(
+            package, local=local, remote=remote, no_osv=no_osv, no_stats=no_stats
+        )
+    except _NOT_FOUND:
+        typer.echo(f"Package '{package}' not found.", err=True)
+        raise typer.Exit(code=1) from None
+    except NetworkError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from None
+    typer.echo(json_format(pkg) if use_json else rich_format(pkg, color=color))

peta/cli/commands/versions.py

@@ -0,0 +1,161 @@
+"""The ``peta versions`` command."""
+
+from __future__ import annotations
+
+import operator
+from typing import TYPE_CHECKING, cast
+
+import httpx
+import typer
+from packaging.version import InvalidVersion, Version
+
+from peta.cli.output.json import format_versions as json_format
+from peta.cli.output.tables import render_versions as rich_format
+from peta.core.remote import DEFAULT_TIMEOUT, PYPI_BASE_URL, NetworkError
+
+if TYPE_CHECKING:
+    from peta.core.remote import PyPIReleaseFile
+
+__all__ = ["get_versions", "versions"]
+
+
+def _sorted_version_keys(releases: dict[str, list[PyPIReleaseFile]]) -> list[str]:
+    """Return release keys newest-first, tolerating non-PEP-440 keys.
+
+    ``packaging.version.Version`` raises ``InvalidVersion`` on legacy keys that
+    PyPI still serves, so parse defensively: PEP 440 versions sort newest-first,
+    and any unparsable keys are kept (sorted after) rather than letting one bad
+    key abort the whole listing with a traceback.
+
+    Returns:
+        Release keys, PEP 440 versions newest-first, then non-PEP-440 keys.
+    """
+    valid: list[tuple[Version, str]] = []
+    invalid: list[str] = []
+    for ver in releases:
+        try:
+            valid.append((Version(ver), ver))
+        except InvalidVersion:
+            invalid.append(ver)
+    valid.sort(key=operator.itemgetter(0), reverse=True)
+    return [ver for _, ver in valid] + sorted(invalid, reverse=True)
+
+
+def _extract_releases(body: object) -> dict[str, list[PyPIReleaseFile]]:
+    """Validate and pull the ``releases`` mapping out of a decoded PyPI body.
+
+    Returns:
+        The release mapping, with any non-list release values dropped.
+
+    Raises:
+        NetworkError: If the body, or its ``releases`` field, is not a dict.
+    """
+    if not isinstance(body, dict):
+        msg = "malformed response from PyPI"
+        raise NetworkError(msg)
+    mapping = cast("dict[str, object]", body)
+    releases = mapping.get("releases", {})
+    if not isinstance(releases, dict):
+        msg = "malformed response from PyPI"
+        raise NetworkError(msg)
+    releases_map = cast("dict[str, object]", releases)
+    return {
+        ver: cleaned
+        for ver, raw in releases_map.items()
+        if (cleaned := _clean_files(raw)) is not None
+    }
+
+
+def _clean_files(raw: object) -> list[PyPIReleaseFile] | None:
+    """Coerce one release's file list, dropping non-dict members.
+
+    Returns:
+        The list of file dicts, or ``None`` if ``raw`` is not a list at all.
+    """
+    if not isinstance(raw, list):
+        return None
+    items = cast("list[object]", raw)
+    return cast("list[PyPIReleaseFile]", [f for f in items if isinstance(f, dict)])
+
+
+def _decode_body(response: httpx.Response) -> object:
+    """Decode a JSON response body, mapping a decode failure to NetworkError.
+
+    Returns:
+        The decoded body as an untyped object.
+
+    Raises:
+        NetworkError: If the body is not valid JSON.
+    """
+    try:
+        return cast("object", response.json())
+    except ValueError as exc:  # includes json.JSONDecodeError
+        msg = "malformed response from PyPI"
+        raise NetworkError(msg) from exc
+
+
+def get_versions(name: str) -> list[dict[str, str]]:
+    """Fetch all published versions for a package from PyPI.
+
+    Returns:
+        A list of ``{"version", "upload_time"}`` dicts, newest first; empty
+        if the package is not found (HTTP 404).
+
+    Raises:
+        NetworkError: If the request fails, returns a non-success status, or
+            the decoded body is malformed (not a dict, or ``releases`` is not
+            a dict).
+    """
+    url = f"{PYPI_BASE_URL}/{name}/json"
+    try:
+        response = httpx.get(url, timeout=DEFAULT_TIMEOUT)
+    except httpx.RequestError as exc:
+        raise NetworkError(str(exc)) from exc
+
+    if response.status_code == 404:  # noqa: PLR2004
+        return []
+
+    try:
+        _ = response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        msg = f"PyPI returned HTTP {exc.response.status_code}"
+        raise NetworkError(msg) from exc
+
+    # The PyPI JSON API is untyped and its shape is not guaranteed, so
+    # validate the decoded body before casting into our typed view.
+    releases = _extract_releases(_decode_body(response))
+    result: list[dict[str, str]] = []
+    for ver in _sorted_version_keys(releases):
+        files = releases[ver]
+        raw_time: object = files[0].get("upload_time", "") if files else ""
+        upload_time = raw_time[:10] if isinstance(raw_time, str) else ""
+        result.append({"version": ver, "upload_time": upload_time})
+    return result
+
+
+# Patch target used by tests.
+remote_get_versions = get_versions
+
+
+def versions(
+    package: str, *, use_json: bool = False, limit: int = 20, color: bool = False
+) -> None:
+    """Show published versions of a package from PyPI.
+
+    Raises:
+        Exit: With code 2 on network failure, or code 1 if the package is absent.
+    """
+    try:
+        vers = remote_get_versions(package)
+    except NetworkError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from None
+    if not vers:
+        typer.echo(f"Package '{package}' not found on PyPI.", err=True)
+        raise typer.Exit(code=1) from None
+    shown = vers[:limit]
+    typer.echo(
+        json_format(package, shown)
+        if use_json
+        else rich_format(package, shown, color=color)
+    )

peta/cli/output/__init__.py

@@ -0,0 +1 @@
+"""Output formatters."""