Metadata-Version: 2.4
Name: cargo-metadata
Version: 1.0.0
Summary: Pydantic types for cargo metadata output
Author: Crystal Durham
Author-email: Crystal Durham <crystal.durham@canonical.com>
License-Expression: MIT OR Apache-2.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: pydantic>=2.13.4
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/canonical/py-cargo-metadata
Project-URL: Issues, https://github.com/canonical/py-cargo-metadata/issues
Description-Content-Type: text/markdown

# cargo-metadata

`cargo-metadata` provides Pydantic models for the JSON output of
`cargo metadata --format-version 1`, plus a small runner function that invokes
the command and returns validated data.

## Installation

```bash
pip install cargo-metadata
```

## What it includes

- `Metadata` and related model types (`Package`, `Dependency`, `Target`, `Resolve`, ...)
- `run(...)` helper to execute `cargo metadata` and parse the result

Unknown fields from Cargo are allowed and preserved on parsed model instances,
which helps with forward compatibility when Cargo adds fields. Refer to the
Pydantic documentation for how to interact with unknown fields.

## Quick start

Run `cargo metadata` and parse directly:

```python
from cargo_metadata import run

meta = run(no_deps=True)

print(meta.version)
print(meta.workspace_root)
print([pkg.name for pkg in meta.packages])
```

Parse existing JSON data:

```python
import json
from cargo_metadata import Metadata

data = json.loads(raw_json)
meta = Metadata.model_validate(data)

for pkg in meta.packages:
    print(pkg.name, pkg.version)
```

## Scope

This package focuses on typed parsing and a thin command wrapper.

It does not provide:

- project mutation APIs
- custom Cargo invocation strategies beyond the exposed flags
- higher-level dependency analysis helpers

## Snapshot tests

This repository includes a snapshot test for the Pydantic JSON schema of
`cargo_metadata.Metadata` at `tests/snapshots/metadata.schema.json`.

Run snapshot tests only:

```bash
uv run pytest tests/test_schema_snapshot.py
```

Accept and update snapshots when running tests:

```bash
uv run pytest --snapshot-update
```

When the schema changes, the snapshot diff appears in git, making the change
reviewable.

## Requirements

- Python 3.10+
- `cargo` available on `PATH` when using `run(...)`

All versions of Cargo should work. However, we do not regularly test compatibility
with old versions of Cargo.

## LLM disclosure

LLMs were used to generate code used in this package. All code has been fully
signed off, owned, and tested by the human(s) running the LLM tooling. 
