pypi-sdk 1.0.0__tar.gz

pypi_sdk-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install locked development dependencies
+        run: uv sync --locked --group dev --group docs
+      - name: Check formatting and lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+      - name: Check types
+        run: |
+          uv run mypy src
+          uv run basedpyright
+      - name: Run tests
+        run: uv run pytest
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+      - name: Build distributions
+        run: uv build

pypi_sdk-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: startsWith(github.ref, 'refs/tags/v')
+    name: Build and validate distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Build distributions
+        run: uv build
+      - name: Validate built wheel
+        run: |
+          python -m pip install dist/*.whl
+          python - <<'PY'
+          import os
+          from importlib.metadata import version
+
+          import pypi_sdk
+
+          package_version = version("pypi-sdk")
+          tag_version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          assert pypi_sdk.__version__ == package_version == tag_version
+          print(package_version)
+          PY
+      - name: Store distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    name: Publish distribution to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pypi-sdk/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pypi_sdk-1.0.0/AGENTS.MD

@@ -0,0 +1,39 @@
+# Repository Instructions for Coding Agents
+
+## Project
+
+This repository builds `pypi-sdk`, an unofficial typed Python client for PyPI's
+documented APIs. Python imports use `pypi_sdk`. Code, docs, examples, benchmark
+names, and commit messages are in English; communicate with the user in their
+preferred language.
+
+## Boundaries
+
+- Keep the client synchronous and use the shared HTTPX client.
+- Model documented API responses with Pydantic v2, preserving additive fields.
+- Do not add account-management endpoints PyPI does not document as public APIs.
+- Do not wrap deprecated XML-RPC, partner-only secret reporting, or BigQuery as
+  PyPI HTTP endpoints.
+- Publishing uploads built artifacts through Twine. Do not rebuild its upload
+  protocol or claim that an existing release can be overwritten.
+- Keep credentials explicit, out of logs/arguments, and scoped to upload.
+- Avoid automatic retries, redirects, or network access in normal tests.
+
+## Validation
+
+Use the workspace `.venv` and locked uv dependencies. Before committing, run:
+
+```console
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run basedpyright
+uv run pytest
+uv run --group docs mkdocs build --strict
+uv build
+```
+
+BenchCore is optional and requires Python 3.12+. Never commit benchmark output.
+Read `CONTRIBUTING.md`, `SECURITY.md`, and the `docs/` pages for release and
+security requirements. Preserve unrelated work and do not claim remote
+publication when only local commits or tags exist.

pypi_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+User-visible changes are recorded here. This project follows semantic
+versioning; compatibility changes are called out explicitly.
+
+## 1.0.0
+
+### Added
+
+- Typed synchronous clients for PyPI project/release JSON, the PEP 691 JSON
+  Simple Index, PEP 740 provenance, storage statistics, and RSS feeds.
+- Optional Twine-backed publishing to PyPI or TestPyPI, plus a GitHub Actions
+  Trusted Publishing example.
+- Python 3.11+ support, strict BasedPyright and Mypy checks, coverage-enforced
+  tests, pytest-benchmark, and optional BenchCore measurements.
+- English API, publishing, development, compatibility, security, and release
+  documentation.
+
+### Changed
+
+- Preserve the JSON and RSS fields returned by PyPI while typing stable fields.
+- Keep account administration, the partner-only secret API, BigQuery, and
+  deprecated XML-RPC outside the HTTP SDK surface.

pypi_sdk-1.0.0/CLAUDE.md

@@ -0,0 +1,14 @@
+# Claude Repository Guide
+
+Read and follow [AGENTS.MD](AGENTS.MD), the canonical repository instructions.
+Keep shared project rules there so this guide does not drift.
+
+The distribution is `pypi-sdk`; the import package is `pypi_sdk`. This is an
+unofficial synchronous client for PyPI's documented public APIs. The supported
+surface and release boundaries are documented in `docs/api.md` and
+`docs/compatibility.md`.
+
+Use the workspace `.venv` and locked uv dependencies. Run the validation commands
+from `AGENTS.MD`. Optional BenchCore runs only on Python 3.12+. Keep source,
+documentation, and commit messages in English; answer the user in their preferred
+language. Report only checks and releases actually completed.

pypi_sdk-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+We welcome contributors with different backgrounds and experience levels. Be
+respectful, explain technical disagreements constructively, and give others
+room to learn.
+
+Harassment, threats, discrimination, unwanted personal attention, and
+publication of private information are not acceptable in project issues,
+pull requests, reviews, or other project spaces.
+
+Report concerns privately to the maintainer at
+ramirez.ruiz.eliezer.reuven@gmail.com. Reports will be handled with care for the
+privacy of those involved. The maintainer may remove harmful content or limit
+participation to protect the community.

pypi_sdk-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+Thanks for helping improve this unofficial PyPI SDK. Keep source code,
+documentation, examples, and commit messages in English.
+
+## Development setup
+
+Install Python 3.11+ and uv, then create the locked development environment:
+
+```console
+uv sync --locked --group dev --group docs
+```
+
+Runtime dependencies belong in `[project.dependencies]`. Keep test, docs,
+benchmark, and publishing tools in their corresponding optional groups. Update
+`uv.lock` with uv; do not edit it by hand.
+
+## Validation
+
+Run the full offline checks before committing:
+
+```console
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run basedpyright
+uv run pytest
+uv run --group docs mkdocs build --strict
+uv build
+```
+
+Tests use HTTPX `MockTransport`; normal test runs do not contact PyPI or upload
+files. Never test a write against production. Keep tests focused on observable
+behavior and cover credential-sensitive code without real credentials.
+
+Optional performance checks are opt-in:
+
+```console
+uv run --group benchmark pytest benchmarks --no-cov --benchmark-only
+```
+
+BenchCore requires Python 3.12+:
+
+```console
+uv run --group benchcore pytest benchmarks/benchcore_cases.py --no-cov --benchcore-save=.benchcore
+```
+
+Benchmark results are local artifacts and should not be committed.
+
+## Changes and commits
+
+Keep changes cohesive, preserve unrelated work, and use Conventional Commits,
+for example:
+
+```text
+feat(api): add release metadata lookup
+fix(publish): reject missing distributions
+docs(publishing): explain Trusted Publishing
+chore(release): prepare 1.0.0
+```
+
+Update the changelog and directly related docs for user-visible changes. Do not
+create a version tag until the version in `pyproject.toml`, package constants,
+and release notes agree and the validation above passes. Tags are release
+markers, not placeholders for future versions.
+
+Commits created by Copilot include this trailer:
+
+```text
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
+```
+
+## Publishing
+
+Use the repository release workflow and PyPI Trusted Publishing once a remote
+and trusted publisher are configured. Do not put long-lived PyPI tokens in
+workflow files or command-line arguments. Test releases on TestPyPI first.

pypi_sdk-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli-ezer Reuven Ramirez Ruiz
+
+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.

pypi_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: pypi-sdk
+Version: 1.0.0
+Summary: Typed Python client for PyPI's public APIs and package publishing
+Keywords: pypi,python-packaging,sdk,publishing
+Author: Eli-ezer Reuven Ramirez Ruiz
+Author-email: Eli-ezer Reuven Ramirez Ruiz <ramirez.ruiz.eliezer.reuven@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.0,<3
+Requires-Dist: twine>=6.0 ; extra == 'publish'
+Requires-Python: >=3.11
+Provides-Extra: publish
+Description-Content-Type: text/markdown
+
+# PyPI SDK
+
+An unofficial, typed Python SDK for PyPI's documented public APIs. It provides
+one synchronous client for package metadata, the PEP 691 index, provenance,
+statistics, RSS feeds, and a Twine-backed distribution publisher.
+
+The SDK requires Python 3.11 or later. It is not affiliated with or endorsed by
+the Python Software Foundation or the PyPI maintainers.
+
+## What this SDK covers
+
+| PyPI feature | SDK interface |
+| --- | --- |
+| Project and release JSON | `client.projects.get()` / `get_release()` |
+| PEP 691 JSON Simple Index | `client.index.list_projects()` / `get_project()` |
+| PEP 740 file provenance | `client.integrity.get_provenance()` |
+| Package storage statistics | `client.stats.get()` |
+| New package and release RSS feeds | `client.feeds` |
+| Legacy upload endpoint | `client.publisher.upload()` via Twine |
+
+It intentionally does not wrap the deprecated XML-RPC API, the partner-only
+secret reporting API, or Google BigQuery datasets as if they were normal PyPI
+HTTP endpoints. PyPI also does not provide a public general-purpose REST API to
+manage accounts, collaborators, or edit an existing release. Add a new version
+to publish an update; an existing release cannot be overwritten.
+
+## Installation
+
+Python 3.11 or later is required. From this checkout:
+
+```console
+uv sync --group dev --group docs
+```
+
+After publishing, install the SDK from PyPI:
+
+```console
+python -m pip install pypi-sdk
+```
+
+For uploads, install the optional Twine dependency:
+
+```console
+python -m pip install "pypi-sdk[publish]"
+```
+
+## Quick start
+
+```python
+from pypi_sdk import PypiClient
+
+with PypiClient() as client:
+    project = client.projects.get("sampleproject")
+    release = client.projects.get_release("sampleproject", project.info.version)
+    files = client.index.get_project("sampleproject").files
+    print(project.info.summary, len(files), len(release.urls))
+```
+
+Responses are Pydantic models that preserve additional fields returned by PyPI.
+The client uses anonymous GET requests by default, follows no redirects, and
+does not retry automatically.
+
+## Publish built distributions
+
+Build and validate artifacts with the standard Python packaging tools, then
+explicitly choose TestPyPI or PyPI. TestPyPI is a separate service, useful for
+testing the release process before publishing to production.
+
+```python
+from pathlib import Path
+
+from pypi_sdk import PypiClient
+
+artifacts = Path("dist").glob("*")
+with PypiClient() as client:
+    result = client.publisher.upload(artifacts, repository="testpypi")
+print(result.files)
+```
+
+Twine reads `TWINE_USERNAME` and `TWINE_PASSWORD` from the environment, or can
+receive a token explicitly without placing it in process arguments:
+
+```python
+import os
+from pathlib import Path
+
+from pypi_sdk import PypiClient
+
+token = os.environ["PYPI_API_TOKEN"]
+with PypiClient() as client:
+    client.publisher.upload(
+        Path("dist").glob("*"),
+        repository="pypi",
+        token=token,
+    )
+```
+
+The equivalent CLI command is:
+
+```console
+pypi-sdk upload --repository testpypi dist\your_package-1.0.0-py3-none-any.whl
+```
+
+The publisher delegates metadata handling and the upload protocol to Twine.
+It does not build distributions; use `python -m build` or your project's
+existing build backend first.
+
+## Automated publishing with Trusted Publishing
+
+For CI, prefer PyPI Trusted Publishing over long-lived API tokens. Configure
+the GitHub repository and workflow as a trusted publisher in the PyPI project
+settings using the GitHub repository owner, repository name, `publish.yml`, and
+the `pypi` environment. Configure the matching GitHub Environment (add
+protection rules if desired), then copy
+[`examples/publish.yml`](examples/publish.yml) to
+`.github/workflows/publish.yml` in the package being released. The workflow
+builds and validates distributions, then publishes them through PyPI's official
+GitHub Action using OIDC.
+See the [Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/).
+
+## API policies and boundaries
+
+- The SDK identifies itself with a `User-Agent` and honors PyPI's JSON
+  representations. The Simple Index HTML representation is not wrapped; the
+  docs recommend its JSON form for new integrations.
+- If polling for updates, prefer RSS feeds and avoid bursts of thousands of
+  requests. The current client does not yet expose conditional ETag requests.
+- Use the Simple Index for distribution files and verify their advertised
+  hashes after downloading.
+- File upload creates releases one file at a time. The first file for a
+  version creates that release and fixes its metadata. To correct a release,
+  publish a new version.
+- Project administration and Trusted Publisher setup happen in PyPI's web
+  interface; this SDK does not claim unsupported account-management endpoints.
+
+See the [PyPI API documentation](https://docs.pypi.org/api/) and the
+[Python Packaging User Guide](https://packaging.python.org/).
+
+## Development
+
+```console
+uv sync --group dev --group docs
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run basedpyright
+uv run pytest
+uv run --group docs mkdocs build --strict
+uv build
+```
+
+Tests use mocked HTTP and do not upload packages or contact PyPI. Optional CPU
+benchmarks are available with pytest-benchmark:
+
+```console
+uv run --group benchmark pytest benchmarks --no-cov --benchmark-only
+```
+
+BenchCore measurements require Python 3.12 or later:
+
+```console
+uv run --group benchcore pytest benchmarks/benchcore_cases.py --no-cov --benchcore-save=.benchcore
+```
+
+See [Getting started](docs/quickstart.md), [API reference](docs/api.md),
+[publishing guide](docs/publishing.md), [development guide](docs/development.md),
+[contributing](CONTRIBUTING.md), and the [changelog](CHANGELOG.md).

pypi_sdk-1.0.0/README.md

@@ -0,0 +1,167 @@
+# PyPI SDK
+
+An unofficial, typed Python SDK for PyPI's documented public APIs. It provides
+one synchronous client for package metadata, the PEP 691 index, provenance,
+statistics, RSS feeds, and a Twine-backed distribution publisher.
+
+The SDK requires Python 3.11 or later. It is not affiliated with or endorsed by
+the Python Software Foundation or the PyPI maintainers.
+
+## What this SDK covers
+
+| PyPI feature | SDK interface |
+| --- | --- |
+| Project and release JSON | `client.projects.get()` / `get_release()` |
+| PEP 691 JSON Simple Index | `client.index.list_projects()` / `get_project()` |
+| PEP 740 file provenance | `client.integrity.get_provenance()` |
+| Package storage statistics | `client.stats.get()` |
+| New package and release RSS feeds | `client.feeds` |
+| Legacy upload endpoint | `client.publisher.upload()` via Twine |
+
+It intentionally does not wrap the deprecated XML-RPC API, the partner-only
+secret reporting API, or Google BigQuery datasets as if they were normal PyPI
+HTTP endpoints. PyPI also does not provide a public general-purpose REST API to
+manage accounts, collaborators, or edit an existing release. Add a new version
+to publish an update; an existing release cannot be overwritten.
+
+## Installation
+
+Python 3.11 or later is required. From this checkout:
+
+```console
+uv sync --group dev --group docs
+```
+
+After publishing, install the SDK from PyPI:
+
+```console
+python -m pip install pypi-sdk
+```
+
+For uploads, install the optional Twine dependency:
+
+```console
+python -m pip install "pypi-sdk[publish]"
+```
+
+## Quick start
+
+```python
+from pypi_sdk import PypiClient
+
+with PypiClient() as client:
+    project = client.projects.get("sampleproject")
+    release = client.projects.get_release("sampleproject", project.info.version)
+    files = client.index.get_project("sampleproject").files
+    print(project.info.summary, len(files), len(release.urls))
+```
+
+Responses are Pydantic models that preserve additional fields returned by PyPI.
+The client uses anonymous GET requests by default, follows no redirects, and
+does not retry automatically.
+
+## Publish built distributions
+
+Build and validate artifacts with the standard Python packaging tools, then
+explicitly choose TestPyPI or PyPI. TestPyPI is a separate service, useful for
+testing the release process before publishing to production.
+
+```python
+from pathlib import Path
+
+from pypi_sdk import PypiClient
+
+artifacts = Path("dist").glob("*")
+with PypiClient() as client:
+    result = client.publisher.upload(artifacts, repository="testpypi")
+print(result.files)
+```
+
+Twine reads `TWINE_USERNAME` and `TWINE_PASSWORD` from the environment, or can
+receive a token explicitly without placing it in process arguments:
+
+```python
+import os
+from pathlib import Path
+
+from pypi_sdk import PypiClient
+
+token = os.environ["PYPI_API_TOKEN"]
+with PypiClient() as client:
+    client.publisher.upload(
+        Path("dist").glob("*"),
+        repository="pypi",
+        token=token,
+    )
+```
+
+The equivalent CLI command is:
+
+```console
+pypi-sdk upload --repository testpypi dist\your_package-1.0.0-py3-none-any.whl
+```
+
+The publisher delegates metadata handling and the upload protocol to Twine.
+It does not build distributions; use `python -m build` or your project's
+existing build backend first.
+
+## Automated publishing with Trusted Publishing
+
+For CI, prefer PyPI Trusted Publishing over long-lived API tokens. Configure
+the GitHub repository and workflow as a trusted publisher in the PyPI project
+settings using the GitHub repository owner, repository name, `publish.yml`, and
+the `pypi` environment. Configure the matching GitHub Environment (add
+protection rules if desired), then copy
+[`examples/publish.yml`](examples/publish.yml) to
+`.github/workflows/publish.yml` in the package being released. The workflow
+builds and validates distributions, then publishes them through PyPI's official
+GitHub Action using OIDC.
+See the [Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/).
+
+## API policies and boundaries
+
+- The SDK identifies itself with a `User-Agent` and honors PyPI's JSON
+  representations. The Simple Index HTML representation is not wrapped; the
+  docs recommend its JSON form for new integrations.
+- If polling for updates, prefer RSS feeds and avoid bursts of thousands of
+  requests. The current client does not yet expose conditional ETag requests.
+- Use the Simple Index for distribution files and verify their advertised
+  hashes after downloading.
+- File upload creates releases one file at a time. The first file for a
+  version creates that release and fixes its metadata. To correct a release,
+  publish a new version.
+- Project administration and Trusted Publisher setup happen in PyPI's web
+  interface; this SDK does not claim unsupported account-management endpoints.
+
+See the [PyPI API documentation](https://docs.pypi.org/api/) and the
+[Python Packaging User Guide](https://packaging.python.org/).
+
+## Development
+
+```console
+uv sync --group dev --group docs
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run basedpyright
+uv run pytest
+uv run --group docs mkdocs build --strict
+uv build
+```
+
+Tests use mocked HTTP and do not upload packages or contact PyPI. Optional CPU
+benchmarks are available with pytest-benchmark:
+
+```console
+uv run --group benchmark pytest benchmarks --no-cov --benchmark-only
+```
+
+BenchCore measurements require Python 3.12 or later:
+
+```console
+uv run --group benchcore pytest benchmarks/benchcore_cases.py --no-cov --benchcore-save=.benchcore
+```
+
+See [Getting started](docs/quickstart.md), [API reference](docs/api.md),
+[publishing guide](docs/publishing.md), [development guide](docs/development.md),
+[contributing](CONTRIBUTING.md), and the [changelog](CHANGELOG.md).

pypi_sdk-1.0.0/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes target the latest supported release. Before a stable release,
+the project has no older supported release lines or service-level guarantees.
+
+## Reporting a vulnerability
+
+Report suspected vulnerabilities privately to
+ramirez.ruiz.eliezer@gmail.com. Include the affected version, impact,
+and a minimal reproduction using synthetic credentials. Do not publish tokens,
+personal data, or exploit details in public issues. No response-time commitment
+is currently offered.
+
+## Publishing credentials
+
+Prefer PyPI Trusted Publishing in CI. For local publishing, use a project-scoped
+API token and pass it through the SDK's `token` parameter or Twine's
+`TWINE_PASSWORD` environment variable. Never commit tokens, print them, or place
+them in command-line arguments. Revoke exposed tokens in PyPI; deleting a token
+from a later commit does not revoke it.
+
+The SDK keeps upload credentials out of read requests and subprocess arguments.
+It cannot protect secrets that an application logs or passes to unrelated
+processes. Uploading is an external side effect; use TestPyPI to validate a
+workflow before production.