uv-metadata 1.0.0__tar.gz

uv_metadata-1.0.0/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/pytest *)",
+      "Bash(.venv/bin/uv-metadata *)",
+      "Bash(uv pip *)",
+      "Bash(tox *)",
+      "Bash(ruff *)",
+      "Bash(.tox/typecheck/bin/pyright *)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git status *)",
+      "Bash(git branch *)",
+      "Bash(git show *)"
+    ]
+  }
+}

uv_metadata-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # mandatory for trusted publishing
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.14"
+
+    - uses: astral-sh/setup-uv@v8.0.0
+    - run: uvx --with tox-uv tox -e py,style
+    - run: uv build
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

uv_metadata-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,40 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+    - uses: astral-sh/setup-uv@v8.0.0
+    - run: uv venv
+    - run: uv pip install -U tox-uv
+    - run: .venv/bin/tox -e py
+
+  linters:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.14"
+    - uses: astral-sh/setup-uv@v8.0.0
+    - run: uv venv
+    - run: uv pip install -U tox-uv
+    - run: .venv/bin/tox -e style

uv_metadata-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# Various
+*~
+\#*#
+.\#*
+.*cache
+.DS_Store*
+*.lock
+.*version
+.idea/
+
+# Build artifacts
+__pycache__/
+*.py[cod]
+*.egg*
+.tox/
+.venv*/
+build/
+dist/

uv_metadata-1.0.0/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Single-file CLI tool (`uv_metadata.py`) that inspects Python package metadata without installing.
+Published on PyPI as `uv-metadata`, runnable via `uvx uv-metadata`. Requires `uv` on PATH.
+
+## Commands
+
+```shell
+# Run all checks (tests on py311+py314, coverage, ruff, pyright)
+tox
+
+# Run tests only (single Python version)
+tox -e py311
+
+# Run a single test
+.venv/bin/pytest tests/test_cli.py::test_package -xvs
+
+# Lint and format check
+tox -e style
+
+# Auto-fix lint/format
+tox -e reformat
+
+# Type check
+tox -e typecheck
+
+# Run the tool locally
+.venv/bin/uv-metadata requests
+.venv/bin/uv-metadata .
+```
+
+## Architecture
+
+All logic lives in `uv_metadata.py`. The flow is:
+
+1. **`main()`** — CLI entry point (argparse), calls `get_metadata_from_pip_spec()`
+2. **`get_metadata_from_pip_spec()`** — routes input to the right extraction strategy:
+   - Local files (.whl/.zip/.tar.gz) → `extract_metadata_from_file()` → `ZipReader`/`TarReader`
+   - Local dist-info/egg-info dir → `extract_metadata_from_dist_info()`
+   - Local project folder → `extract_metadata_from_project_folder()` (PEP 517 build)
+   - Git/URL refs → `extract_metadata_from_uv_install()` (temp install via uv)
+   - Plain package names → `extract_metadata_from_uv_resolve()` (fast: resolve + stream wheel metadata via HTTP range requests, fallback: download sdist)
+3. **All paths converge** on `extract_metadata_from_dist_info()` which uses `importlib.metadata.PathDistribution`
+
+Key design details:
+- Archive extraction uses a `MetadataReader` ABC with `ZipReader` and `TarReader` subclasses (context managers)
+- Two compiled regexes (`_INFO_DIR_RX`, `_ROOT_PKG_INFO_RX`) drive metadata file discovery, built from the `METADATA_FILES` tuple
+- `PKG-INFO` files are renamed to `METADATA` before reading so `PathDistribution` handles both formats
+- `UNKNOWN` sentinel values from old metadata are filtered out
+- `description` (long description) is stripped by default; `--full` flag preserves it
+- `canonical_git_url()` accepts plain GitHub HTTPS URLs and `git@` SSH shorthand
+
+## Testing
+
+Tests use the `runez` library's `ClickRunner` fixture (`cli`). The pattern is:
+```python
+def test_example(cli):
+    cli.run("requests", "-kversion")
+    assert cli.succeeded
+    payload = json.loads(cli.logged.stdout.contents())
+```
+
+Test fixtures in `tests/sample-dist/` include real archived packages (colorama, mock, uv-metadata itself).
+
+## Versioning
+
+Uses `setuptools-scm` with `local_scheme = "dirty-tag"`. Version is derived from git tags (`v*`).
+Release workflow triggers on tag push, publishes to PyPI via trusted publishing.

uv_metadata-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zoran Simic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uv_metadata-1.0.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: uv-metadata
+Version: 1.0.0
+Summary: Inspect any Python package metadata without installing
+Author: Zoran Simic
+Project-URL: Homepage, https://github.com/zsimic/uv-metadata
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: build
+Requires-Dist: pyproject-hooks
+Requires-Dist: seekablehttpfile
+Dynamic: license-file
+
+# uv-metadata
+
+Inspect any Python package metadata from any source without installing.
+
+```shell
+$ uvx uv-metadata requests -kversion
+2.32.4
+
+$ uvx uv-metadata requests -krequires_python
+>=3.10
+
+$ uvx uv-metadata 'pip<23' -kversion
+22.3.1
+```
+
+Works with published packages, local wheels/sdists, project folders, and git repos.
+For published packages, metadata is streamed directly from the remote wheel via HTTP range
+requests — typically a few KB, no full download needed.
+
+
+## Why this is useful
+
+Getting package metadata as JSON from a simple CLI opens up a lot of possibilities:
+
+- **Scripting**: what's the latest version of a package? What about the last 2.x release?
+  What's the latest version that still supports Python 3.7?
+  (`uvx uv-metadata -p3.7 setuptools -kversion`)
+- **Validation**: CI checks that verify your package metadata is complete before publishing —
+  are author, URL, license, classifiers all present?
+- **Verifying your own project**: after setting up dynamic versioning (e.g. `setuptools-scm`),
+  just run `uvx uv-metadata .` to confirm your metadata looks right — no need to build or install
+- **Dependency auditing**: quickly check what a package requires, what Python versions it supports,
+  or what entry points it exposes — all without installing anything
+
+This project also serves as a reference implementation for a proposed native
+[`uv metadata`](https://github.com/zsimic/uv-metadata/blob/main/uv-metadata-spec.md) subcommand
+(see [astral-sh/uv#6037](https://github.com/astral-sh/uv/issues/6037) and the [spec](https://github.com/zsimic/uv-metadata/blob/main/uv-metadata-spec.md)).
+
+Requires `uv` on `PATH`.
+
+
+## Installation
+
+```shell
+# Run directly (no install needed)
+uvx uv-metadata requests
+
+# Or install permanently
+uv tool install uv-metadata
+```
+
+
+## Quick examples
+
+```shell
+# Full metadata as JSON
+uvx uv-metadata flask
+
+# Single key
+uvx uv-metadata flask -kversion
+
+# Version constraint
+uvx uv-metadata 'flask<3' -kversion
+
+# Local project
+uvx uv-metadata .
+
+# Local wheel or sdist
+uvx uv-metadata ./dist/mypackage-1.0.0-py3-none-any.whl
+
+# Git repo
+uvx uv-metadata git+https://github.com/psf/requests@main
+
+# Target a specific Python version
+uvx uv-metadata numpy -p3.9 -kversion
+```
+
+
+## Input routing
+
+| Input | Strategy |
+|---|---|
+| `.`, `./path`, `/abs/path`, or any existing filesystem path | |
+| &emsp;directory with `pyproject.toml` or `setup.py` | Build metadata via PEP 517 |
+| &emsp;`*.dist-info` or `*.egg-info` directory | Read directly |
+| &emsp;`*.whl` or `*.zip` file | Extract from zip archive |
+| &emsp;`*.tar.gz` file | Extract from tarball |
+| `git+https://...`, `git@...`, or `pkg @ url` | Install to temp dir, read dist-info |
+| plain name or version constraint (`name`, `name>=x`, etc.) | Resolve via uv, stream dist-info from remote wheel; fall back to downloading sdist |
+
+
+## Output format
+
+JSON with sorted keys. The `description` (long description) field is omitted by default
+as it is typically very large; use `--full` to include it.
+
+```shell
+$ uvx uv-metadata pip
+{
+    "author_email": "The pip developers <distutils-sig@python.org>",
+    "classifiers": [
+        "Development Status :: 5 - Production/Stable",
+        ...
+    ],
+    "description_content_type": "text/x-rst",
+    "entry_points": {
+        "console_scripts": {
+            "pip": "pip._internal.cli.main:main",
+            "pip3": "pip._internal.cli.main:main"
+        }
+    },
+    "license_expression": "MIT",
+    "metadata_version": "2.4",
+    "name": "pip",
+    "project_url": [
+        "Documentation, https://pip.pypa.io",
+        "Source, https://github.com/pypa/pip"
+    ],
+    "requires_python": ">=3.9",
+    "summary": "The PyPA recommended tool for installing Python packages.",
+    "version": "26.0.1"
+}
+```
+
+Structural rules:
+- Keys are `lower_snake_case`
+- Single-occurrence fields: plain string
+- Multi-occurrence fields: list of strings
+- `entry_points`: `{"group": {"name": "module:attr"}}`
+- `top_level`: list of top-level importable names
+- `UNKNOWN` values are omitted
+
+
+## CLI reference
+
+```
+usage: uv-metadata [-h] [-p PYTHON] [-k KEY] [--full] [package]
+
+Output the metadata of a package, in machine-readable format
+
+positional arguments:
+  package              Package to inspect (default: current folder)
+
+options:
+  -h, --help           show this help message and exit
+  -p, --python PYTHON  Python version to target (e.g. 3.11)
+  -k, --key KEY        Show only this key from the metadata
+  --full               Include full description in output
+```
+
+
+## How it works
+
+### Fast path for published packages
+
+1. `uv pip compile --format pylock.toml` resolves to a concrete wheel URL without downloading
+2. `SeekableHttpFile` + `ZipFile` streams only the dist-info files via HTTP range requests
+3. Falls back to downloading the sdist when no wheel is available
+
+### Unified metadata reading
+
+All extraction strategies produce a dist-info folder which is read by
+`importlib.metadata.PathDistribution`. Both `METADATA` (wheels) and `PKG-INFO` (sdists)
+are handled transparently.
+
+### Archive extraction
+
+A `MetadataReader` base class with `ZipReader` and `TarReader` implementations provides
+uniform member discovery and extraction across archive formats.
+
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| [`build`](https://pypi.org/project/build/) | PEP 517 metadata building for local project folders |
+| [`pyproject-hooks`](https://pypi.org/project/pyproject-hooks/) | Quiet subprocess runner used by `build` |
+| [`seekablehttpfile`](https://pypi.org/project/seekablehttpfile/) | HTTP range requests for streaming dist-info from remote wheels |
+
+
+## Relevant PEPs
+
+- [PEP 241](https://peps.python.org/pep-0241/) – Metadata for Python Software Packages 1.0
+- [PEP 314](https://peps.python.org/pep-0314/) – Metadata for Python Software Packages 1.1
+- [PEP 345](https://peps.python.org/pep-0345/) – Metadata for Python Software Packages 1.2
+- [PEP 566](https://peps.python.org/pep-0566/) – Metadata for Python Software Packages 2.1
+- [PEP 508](https://peps.python.org/pep-0508/) – Dependency specification for Python Software Packages
+- [PEP 517](https://peps.python.org/pep-0517/) – A build-system independent format for source trees
+- [PEP 643](https://peps.python.org/pep-0643/) – Metadata for Package Source Distributions
+- [PEP 658](https://peps.python.org/pep-0658/) – Serve Distribution Metadata in the Simple Repository API
+- [PEP 639](https://peps.python.org/pep-0639/) – Improving License Clarity with Better Package Metadata

uv_metadata-1.0.0/README.md

@@ -0,0 +1,191 @@
+# uv-metadata
+
+Inspect any Python package metadata from any source without installing.
+
+```shell
+$ uvx uv-metadata requests -kversion
+2.32.4
+
+$ uvx uv-metadata requests -krequires_python
+>=3.10
+
+$ uvx uv-metadata 'pip<23' -kversion
+22.3.1
+```
+
+Works with published packages, local wheels/sdists, project folders, and git repos.
+For published packages, metadata is streamed directly from the remote wheel via HTTP range
+requests — typically a few KB, no full download needed.
+
+
+## Why this is useful
+
+Getting package metadata as JSON from a simple CLI opens up a lot of possibilities:
+
+- **Scripting**: what's the latest version of a package? What about the last 2.x release?
+  What's the latest version that still supports Python 3.7?
+  (`uvx uv-metadata -p3.7 setuptools -kversion`)
+- **Validation**: CI checks that verify your package metadata is complete before publishing —
+  are author, URL, license, classifiers all present?
+- **Verifying your own project**: after setting up dynamic versioning (e.g. `setuptools-scm`),
+  just run `uvx uv-metadata .` to confirm your metadata looks right — no need to build or install
+- **Dependency auditing**: quickly check what a package requires, what Python versions it supports,
+  or what entry points it exposes — all without installing anything
+
+This project also serves as a reference implementation for a proposed native
+[`uv metadata`](https://github.com/zsimic/uv-metadata/blob/main/uv-metadata-spec.md) subcommand
+(see [astral-sh/uv#6037](https://github.com/astral-sh/uv/issues/6037) and the [spec](https://github.com/zsimic/uv-metadata/blob/main/uv-metadata-spec.md)).
+
+Requires `uv` on `PATH`.
+
+
+## Installation
+
+```shell
+# Run directly (no install needed)
+uvx uv-metadata requests
+
+# Or install permanently
+uv tool install uv-metadata
+```
+
+
+## Quick examples
+
+```shell
+# Full metadata as JSON
+uvx uv-metadata flask
+
+# Single key
+uvx uv-metadata flask -kversion
+
+# Version constraint
+uvx uv-metadata 'flask<3' -kversion
+
+# Local project
+uvx uv-metadata .
+
+# Local wheel or sdist
+uvx uv-metadata ./dist/mypackage-1.0.0-py3-none-any.whl
+
+# Git repo
+uvx uv-metadata git+https://github.com/psf/requests@main
+
+# Target a specific Python version
+uvx uv-metadata numpy -p3.9 -kversion
+```
+
+
+## Input routing
+
+| Input | Strategy |
+|---|---|
+| `.`, `./path`, `/abs/path`, or any existing filesystem path | |
+| &emsp;directory with `pyproject.toml` or `setup.py` | Build metadata via PEP 517 |
+| &emsp;`*.dist-info` or `*.egg-info` directory | Read directly |
+| &emsp;`*.whl` or `*.zip` file | Extract from zip archive |
+| &emsp;`*.tar.gz` file | Extract from tarball |
+| `git+https://...`, `git@...`, or `pkg @ url` | Install to temp dir, read dist-info |
+| plain name or version constraint (`name`, `name>=x`, etc.) | Resolve via uv, stream dist-info from remote wheel; fall back to downloading sdist |
+
+
+## Output format
+
+JSON with sorted keys. The `description` (long description) field is omitted by default
+as it is typically very large; use `--full` to include it.
+
+```shell
+$ uvx uv-metadata pip
+{
+    "author_email": "The pip developers <distutils-sig@python.org>",
+    "classifiers": [
+        "Development Status :: 5 - Production/Stable",
+        ...
+    ],
+    "description_content_type": "text/x-rst",
+    "entry_points": {
+        "console_scripts": {
+            "pip": "pip._internal.cli.main:main",
+            "pip3": "pip._internal.cli.main:main"
+        }
+    },
+    "license_expression": "MIT",
+    "metadata_version": "2.4",
+    "name": "pip",
+    "project_url": [
+        "Documentation, https://pip.pypa.io",
+        "Source, https://github.com/pypa/pip"
+    ],
+    "requires_python": ">=3.9",
+    "summary": "The PyPA recommended tool for installing Python packages.",
+    "version": "26.0.1"
+}
+```
+
+Structural rules:
+- Keys are `lower_snake_case`
+- Single-occurrence fields: plain string
+- Multi-occurrence fields: list of strings
+- `entry_points`: `{"group": {"name": "module:attr"}}`
+- `top_level`: list of top-level importable names
+- `UNKNOWN` values are omitted
+
+
+## CLI reference
+
+```
+usage: uv-metadata [-h] [-p PYTHON] [-k KEY] [--full] [package]
+
+Output the metadata of a package, in machine-readable format
+
+positional arguments:
+  package              Package to inspect (default: current folder)
+
+options:
+  -h, --help           show this help message and exit
+  -p, --python PYTHON  Python version to target (e.g. 3.11)
+  -k, --key KEY        Show only this key from the metadata
+  --full               Include full description in output
+```
+
+
+## How it works
+
+### Fast path for published packages
+
+1. `uv pip compile --format pylock.toml` resolves to a concrete wheel URL without downloading
+2. `SeekableHttpFile` + `ZipFile` streams only the dist-info files via HTTP range requests
+3. Falls back to downloading the sdist when no wheel is available
+
+### Unified metadata reading
+
+All extraction strategies produce a dist-info folder which is read by
+`importlib.metadata.PathDistribution`. Both `METADATA` (wheels) and `PKG-INFO` (sdists)
+are handled transparently.
+
+### Archive extraction
+
+A `MetadataReader` base class with `ZipReader` and `TarReader` implementations provides
+uniform member discovery and extraction across archive formats.
+
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| [`build`](https://pypi.org/project/build/) | PEP 517 metadata building for local project folders |
+| [`pyproject-hooks`](https://pypi.org/project/pyproject-hooks/) | Quiet subprocess runner used by `build` |
+| [`seekablehttpfile`](https://pypi.org/project/seekablehttpfile/) | HTTP range requests for streaming dist-info from remote wheels |
+
+
+## Relevant PEPs
+
+- [PEP 241](https://peps.python.org/pep-0241/) – Metadata for Python Software Packages 1.0
+- [PEP 314](https://peps.python.org/pep-0314/) – Metadata for Python Software Packages 1.1
+- [PEP 345](https://peps.python.org/pep-0345/) – Metadata for Python Software Packages 1.2
+- [PEP 566](https://peps.python.org/pep-0566/) – Metadata for Python Software Packages 2.1
+- [PEP 508](https://peps.python.org/pep-0508/) – Dependency specification for Python Software Packages
+- [PEP 517](https://peps.python.org/pep-0517/) – A build-system independent format for source trees
+- [PEP 643](https://peps.python.org/pep-0643/) – Metadata for Package Source Distributions
+- [PEP 658](https://peps.python.org/pep-0658/) – Serve Distribution Metadata in the Simple Repository API
+- [PEP 639](https://peps.python.org/pep-0639/) – Improving License Clarity with Better Package Metadata

uv_metadata-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+local_scheme = "dirty-tag"
+
+[project]
+name = "uv-metadata"
+dynamic = ["version"]
+description = "Inspect any Python package metadata without installing"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "Zoran Simic"}]
+urls = {Homepage = "https://github.com/zsimic/uv-metadata"}
+dependencies = [
+  "build",
+  "pyproject-hooks",  # dependency of build but imported so stated here
+  "seekablehttpfile",  # HTTP range requests for streaming remote wheel metadata
+]
+
+[project.scripts]
+uv-metadata = "uv_metadata:main"
+
+[tool.ruff]
+cache-dir = ".tox/.ruff_cache"
+line-length = 140
+
+[tool.ruff.lint]
+extend-select = [
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "C90", # mccabe
+    "E",   # pycodestyle errors
+    "ERA", # eradicate
+    "EXE", # flake8-executable
+    "F",   # pyflakes
+    "FLY", # flynt
+    "G",   # flake8-logging-format
+    "I",   # isort
+    "INT", # flake8-gettext
+    "PGH", # pygrep-hooks
+    "PIE", # flake8-pie
+    "PT", # flake8-pytest
+    "PYI", # flake8-pyi
+    "Q",   # flake8-quotes
+    "RSE", # flake8-raise
+    "RUF", # ruff-specific
+    "SLOT", # flake8-slots
+    "T10", # flake8-debugger
+    "TID", # flake8-tidy-imports
+    "TCH", # flake8-type-checking
+    "W",   # pycodestyle warnings
+]
+
+[tool.ruff.lint.isort]
+order-by-type = false
+
+[tool.ruff.lint.mccabe]
+max-complexity = 20
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.pyright]
+include = ["uv_metadata.py", "tests"]

uv_metadata-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uv_metadata-1.0.0/tests/conftest.py

@@ -0,0 +1,7 @@
+from runez.conftest import cli, ClickRunner
+
+from uv_metadata import main
+
+__all__ = ["cli"]
+
+ClickRunner.default_main = main

uv_metadata-1.0.0/tests/requirements.txt

@@ -0,0 +1,2 @@
+pytest-cov
+runez