Modules¶

An overview of the packages that make up peta. The API reference below is generated automatically from the source docstrings.

Core (`peta.core`)¶

Core data models for peta.

class peta.core.models.DependencyNode(name, version_spec, installed_version=None, children=<factory>, circular=False)[source]¶

Bases: object

A node in a package’s recursive dependency tree.

Parameters:

name (str)
version_spec (str)
installed_version (str | None)
children (list[DependencyNode])
circular (bool)

class peta.core.models.PackageInfo(name, version, source, summary=None, author=None, author_email=None, maintainer=None, license=None, python_requires=None, homepage=None, project_urls=<factory>, dependencies=<factory>, classifiers=<factory>, keywords=<factory>, files=None, vulnerabilities=<factory>, download_count=None, dependent_count=None)[source]¶

Bases: object

Package metadata from a local installation or PyPI.

Parameters:

name (str)
version (str)
source (str)
summary (str | None)
author (str | None)
author_email (str | None)
maintainer (str | None)
license (str | None)
python_requires (str | None)
homepage (str | None)
project_urls (dict[str, str])
dependencies (list[str])
classifiers (list[str])
keywords (list[str])
files (list[str] | None)
vulnerabilities (list[Vulnerability])
download_count (int | None)
dependent_count (int | None)

class peta.core.models.Vulnerability(id, aliases, summary, fixed_in, severity=None)[source]¶

Bases: object

A known security vulnerability for a package.

Parameters:

id (str)
aliases (list[str])
summary (str)
fixed_in (list[str])
severity (str | None)

Local package metadata fetcher using importlib.metadata.

exception peta.core.local.PackageNotFoundError(name)[source]¶

Bases: Exception

Raised when a package is not installed locally.

Store the missing package name.

Parameters:: name (str)
Return type:: None

peta.core.local.get_package(name)[source]¶

Get metadata for a locally installed package.

Parameters:

name¶ – Package name to look up.
name (str)

Returns:

A PackageInfo with source="local".

Raises:

PackageNotFoundError – If the package is not installed.

Return type:

PackageInfo

PyPI JSON API client for remote package metadata.

exception peta.core.remote.NetworkError(message)[source]¶

Bases: Exception

Raised when a network request fails.

Wrap a network failure message.

Parameters:: message (str)
Return type:: None

exception peta.core.remote.PackageNotFoundError(name, version=None)[source]¶

Bases: Exception

Raised when a package is not found on PyPI.

Store the missing package name and optional version.

Parameters:

name (str)
version (str | None)

Return type:

None

class peta.core.remote.PyPIInfo[source]¶

Bases: TypedDict

The info object of a PyPI package payload.

class peta.core.remote.PyPIReleaseFile[source]¶

Bases: TypedDict

A single distribution file within a release entry.

class peta.core.remote.PyPIResponse[source]¶

Bases: TypedDict

The top-level PyPI JSON payload for a package.

class peta.core.remote.PyPIVulnerability[source]¶

Bases: TypedDict

A single entry of the vulnerabilities array.

peta.core.remote.get_package(name, version=None)[source]¶

Get metadata for a package from PyPI.

Parameters:

name¶ – Package name to look up.
version¶ – Optional specific version; if None the latest is fetched.
name (str)
version (str | None)

Returns:

A PackageInfo with source="remote". Not-found and network failures propagate from _fetch().

Return type:

PackageInfo

CLI (`peta.cli`)¶

Typer application and command registration.

peta.cli.app.compare(ctx, a, b, use_json=False, local=False, remote=False, no_osv=False, no_stats=False)[source]¶

Compare two packages’ metadata side by side.

Parameters:

ctx (Context)
a (Annotated[str, <typer.models.ArgumentInfo object at 0x7f01f92c74d0>])
b (Annotated[str, <typer.models.ArgumentInfo object at 0x7f01f92c7610>])
use_json (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f92c7750>])
local (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f92c7890>])
remote (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f92c79d0>])
no_osv (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f92c7b10>])
no_stats (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f92c7c50>])

Return type:

None

peta.cli.app.deps(ctx, package, use_json=False, local=False, remote=False, why=None, depth=10)[source]¶

Show a package’s recursive dependency tree.

Parameters:

ctx (Context)
package (Annotated[str, <typer.models.ArgumentInfo object at 0x7f01f9184550>])
use_json (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9184690>])
local (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f91847d0>])
remote (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9184910>])
why (Annotated[str | None, <typer.models.OptionInfo object at 0x7f01f9184a50>])
depth (Annotated[int, <typer.models.OptionInfo object at 0x7f01f9184b90>])

Return type:

None

peta.cli.app.files(ctx, package, use_json=False)[source]¶

List files installed by a local package.

Parameters:

ctx (Context)
package (Annotated[str, <typer.models.ArgumentInfo object at 0x7f01f9184f50>])
use_json (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9185090>])

Return type:

None

peta.cli.app.info(ctx, package, use_json=False, local=False, remote=False, no_osv=False, no_stats=False)[source]¶

Show detailed package metadata.

Parameters:

ctx (Context)
package (Annotated[str, <typer.models.ArgumentInfo object at 0x7f01f9185950>])
use_json (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9185a90>])
local (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9185bd0>])
remote (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9185d10>])
no_osv (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9185e50>])
no_stats (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9185f90>])

Return type:

None

peta.cli.app.main(ctx, _version=False, no_color=False)[source]¶

Human-friendly Python package metadata viewer.

Parameters:

ctx (Context)
_version (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9186350>])
no_color (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9186490>])

Return type:

None

peta.cli.app.run()[source]¶

Entry point; peta <package> is shorthand for peta info <package>.

Return type:: None

peta.cli.app.versions(ctx, package, use_json=False, limit=20)[source]¶

Show published versions of a package from PyPI.

Parameters:

ctx (Context)
package (Annotated[str, <typer.models.ArgumentInfo object at 0x7f01f9186990>])
use_json (Annotated[bool, <typer.models.OptionInfo object at 0x7f01f9186ad0>])
limit (Annotated[int, <typer.models.OptionInfo object at 0x7f01f9186c10>])

Return type:

None

Rich text output formatters.

peta.cli.output.tables.render_compare(a, b, *, color)[source]¶

Render two PackageInfo objects as a side-by-side Rich table.

Returns:

The comparison table rendered as text.

Parameters:

a (PackageInfo)
b (PackageInfo)
color (bool)

Return type:

str

peta.cli.output.tables.render_dep_tree(node, *, color)[source]¶

Render a recursive dependency tree as a Rich tree string.

Returns:

The dependency tree rendered as text.

Parameters:

node (DependencyNode)
color (bool)

Return type:

str

peta.cli.output.tables.render_files(pkg, *, color)[source]¶

Render a package’s file listing as a string.

color is accepted for signature parity with the other renderers but unused: this output is plain lines, not a Rich renderable.

Returns:

The file listing rendered as text.

Parameters:

pkg (PackageInfo)
color (bool)

Return type:

str

peta.cli.output.tables.render_info(pkg, *, color)[source]¶

Render PackageInfo as a Rich panel string.

Returns:

The formatted panel text, with any vulnerability block appended.

Parameters:

pkg (PackageInfo)
color (bool)

Return type:

str

peta.cli.output.tables.render_versions(name, versions, *, color)[source]¶

Render a version list as a Rich table string.

Returns:

The version table rendered as text.

Parameters:

name (str)
versions (list[dict[str, str]])
color (bool)

Return type:

str

peta.cli.output.tables.render_why(target, paths, *, color)[source]¶

Render root-to-target dependency chains as arrow-joined lines.

color is accepted for signature parity with the other renderers but unused: this output is plain lines, not a Rich renderable.

Returns:

Each path rendered as a -> b -> target, one per line.

Parameters:

target (str)
paths (list[list[str]])
color (bool)

Return type:

str

JSON output formatters.

peta.cli.output.json.format_compare(a, b)[source]¶

Format two PackageInfo objects as a JSON comparison string.

Returns:

A {"packages": [a, b]} JSON string, each package in the same format as format_info().

Parameters:

a (PackageInfo)
b (PackageInfo)

Return type:

str

peta.cli.output.json.format_dep_tree(node)[source]¶

Format a recursive dependency tree as a JSON string.

Returns:: The dependency tree serialized as an indented JSON string.
Parameters:: node (DependencyNode)
Return type:: str

peta.cli.output.json.format_files(pkg)[source]¶

Format a package’s file list as a JSON string.

Returns:: The file list serialized as an indented JSON string.
Parameters:: pkg (PackageInfo)
Return type:: str

peta.cli.output.json.format_info(pkg)[source]¶

Format PackageInfo as a JSON string.

Returns:: The metadata serialized as an indented JSON string.
Parameters:: pkg (PackageInfo)
Return type:: str

peta.cli.output.json.format_versions(name, versions)[source]¶

Format a version list as a JSON string.

Returns:

The version list serialized as an indented JSON string.

Parameters:

name (str)
versions (list[dict[str, str]])

Return type:

str

peta.cli.output.json.format_why(target, paths)[source]¶

Format root-to-target dependency chains as a JSON string.

Returns:

A {"target": ..., "paths": [[...], ...]} JSON string.

Parameters:

target (str)
paths (list[list[str]])

Return type:

str

The peta info command.

peta.cli.commands.info.info(package, *, use_json=False, local=False, remote=False, color=False, no_osv=False, no_stats=False)[source]¶

Show detailed package metadata.

Raises:

Exit – With code 1 if the package is not found, or code 2 on network failure.

Parameters:

package (str)
use_json (bool)
local (bool)
remote (bool)
color (bool)
no_osv (bool)
no_stats (bool)

Return type:

None

The peta deps command.

peta.cli.commands.deps.deps(package, *, use_json=False, local=False, remote=False, color=False, why=None, depth=10)[source]¶

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.

Parameters:

package (str)
use_json (bool)
local (bool)
remote (bool)
color (bool)
why (str | None)
depth (int)

Return type:

None

The peta files command.

peta.cli.commands.files.files(package, *, use_json=False, color=False)[source]¶

List files installed by a local package.

Raises:

Exit – With code 1 if the package is not installed locally.

Parameters:

package (str)
use_json (bool)
color (bool)

Return type:

None

The peta versions command.

peta.cli.commands.versions.get_versions(name)[source]¶

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).
Parameters:: name (str)
Return type:: list[dict[str, str]]

peta.cli.commands.versions.versions(package, *, use_json=False, limit=20, color=False)[source]¶

Show published versions of a package from PyPI.

Raises:

Exit – With code 2 on network failure, or code 1 if the package is absent.

Parameters:

package (str)
use_json (bool)
limit (int)
color (bool)

Return type:

None

Modules¶

Core (peta.core)¶

CLI (peta.cli)¶

Core (`peta.core`)¶

CLI (`peta.cli`)¶