ptr727-projecttemplate-library 0.0.0__tar.gz

ptr727_projecttemplate_library-0.0.0/.gitignore

@@ -0,0 +1,20 @@
+[Dd]ebug/
+[Rr]elease/
+[Bb]in/
+[Oo]bj/
+
+.idea
+.vs
+.artifacts
+.DS_Store
+*.user
+.claude
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+.pyright/

ptr727_projecttemplate_library-0.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: ptr727-projecttemplate-library
+Version: 0.0.0
+Summary: Python PyPI template library — companion to the .NET NuGetLibrary in this template repo.
+Project-URL: Homepage, https://github.com/ptr727/ProjectTemplate
+Project-URL: Source, https://github.com/ptr727/ProjectTemplate
+Project-URL: Issues, https://github.com/ptr727/ProjectTemplate/issues
+Author: Pieter Viljoen
+License: MIT
+Keywords: library,pypi,template
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# PyPiLibrary
+
+Python PyPI template — companion to the .NET `NuGetLibrary` in this repo. Published to PyPI as [`ptr727-projecttemplate-library`](https://pypi.org/project/ptr727-projecttemplate-library/).
+
+## Stack
+
+- **Build backend** — [`hatchling`](https://hatch.pypa.io/latest/) via `pyproject.toml`
+- **Env / deps / publish** — [`uv`](https://docs.astral.sh/uv/) (Astral)
+- **Lint + format** — [`ruff`](https://docs.astral.sh/ruff/)
+- **Type checker** — [`pyright`](https://microsoft.github.io/pyright/)
+- **Tests** — [`pytest`](https://docs.pytest.org/)
+- **Publish** — [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) via `pypa/gh-action-pypi-publish` (no API token in repo secrets)
+
+## Layout
+
+```text
+PyPiLibrary/
+    pyproject.toml
+    README.md
+    src/
+        ptr727_projecttemplate_library/
+            __init__.py
+            _version.py
+            example.py
+    tests/
+        __init__.py
+        test_example.py
+```
+
+## Local Development
+
+The repo's [devcontainer](../docs/devcontainer.md) installs `uv` automatically and runs `uv sync` for this project on first open. To work outside the devcontainer:
+
+```shell
+# from the repo root
+cd PyPiLibrary
+uv sync                          # creates .venv, installs deps + dev group
+uv run ruff check                # lint
+uv run ruff format --check       # formatting check
+uv run pyright                   # type check
+uv run pytest                    # tests
+uv build                         # wheel + sdist into ./dist
+```
+
+## Publishing
+
+Releases are produced by `.github/workflows/build-pypilibrary-task.yml` (called from `build-release-task.yml` to build, lint, type-check, test, and upload the wheel + sdist as a workflow-run artifact). Publishing is a separate top-level `publish-pypi` job in `publish-release.yml` that downloads the artifact by name and runs [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no `PYPI_API_TOKEN` secret is involved. The publish job has `id-token: write` only at that single job level, so the test-pull-request flow (which calls the same build task during PR validation) doesn't need to propagate that permission through the reusable workflow chain.
+
+First-time setup (one-time, on PyPI):
+
+1. PyPI → **Account settings** → **Publishing** → **Add a new pending publisher**.
+2. Project name: `ptr727-projecttemplate-library`. Owner: `ptr727`. Repo: `ProjectTemplate`. Workflow: `publish-release.yml`. Environment: `pypi`.
+3. GitHub repo → **Settings** → **Environments** → create `pypi` environment (optionally with required reviewers).
+4. The first successful release converts the pending publisher to a real publisher.
+
+## Template Adoption
+
+When deriving a new project from this template:
+
+- Replace the package name `ptr727-projecttemplate-library` (in `pyproject.toml`, this README, and CI) with your name.
+- Rename `src/ptr727_projecttemplate_library/` to your import name.
+- Re-register the trusted publisher on PyPI under the new project name.
+- **Wire up a versioning scheme before the first publish.** `_version.py` ships with `__version__ = "0.0.0"` as a placeholder. The publish workflow uses `skip-existing: true` so the workflow won't fail on duplicate uploads — but **no new versions will land on PyPI** until you replace `0.0.0` with something that increments. Common options:
+  - [`hatch-vcs`](https://github.com/ofek/hatch-vcs) — derive the version from git tags. Add it to `[build-system].requires` and switch `[tool.hatch.version]` to `source = "vcs"`. Pairs well with tag-driven releases.
+  - **Read from `version.json`** — the .NET side uses Nerdbank.GitVersioning which reads from `version.json`. A small custom Hatchling plugin or a CI step can pull the version into `_version.py` so .NET and Python ship with matching versions.
+  - **Manual bumps** — edit `_version.py` in each release PR. Simplest, but easy to forget.
+
+If you don't want a Python project at all, delete the `PyPiLibrary/` folder, the `build-pypilibrary-task.yml` workflow, the `build-pypilibrary` job in `build-release-task.yml`, the `publish-pypi` job in `publish-release.yml`, and the `uv` block in `.github/dependabot.yml`.

ptr727_projecttemplate_library-0.0.0/README.md

@@ -0,0 +1,68 @@
+# PyPiLibrary
+
+Python PyPI template — companion to the .NET `NuGetLibrary` in this repo. Published to PyPI as [`ptr727-projecttemplate-library`](https://pypi.org/project/ptr727-projecttemplate-library/).
+
+## Stack
+
+- **Build backend** — [`hatchling`](https://hatch.pypa.io/latest/) via `pyproject.toml`
+- **Env / deps / publish** — [`uv`](https://docs.astral.sh/uv/) (Astral)
+- **Lint + format** — [`ruff`](https://docs.astral.sh/ruff/)
+- **Type checker** — [`pyright`](https://microsoft.github.io/pyright/)
+- **Tests** — [`pytest`](https://docs.pytest.org/)
+- **Publish** — [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) via `pypa/gh-action-pypi-publish` (no API token in repo secrets)
+
+## Layout
+
+```text
+PyPiLibrary/
+    pyproject.toml
+    README.md
+    src/
+        ptr727_projecttemplate_library/
+            __init__.py
+            _version.py
+            example.py
+    tests/
+        __init__.py
+        test_example.py
+```
+
+## Local Development
+
+The repo's [devcontainer](../docs/devcontainer.md) installs `uv` automatically and runs `uv sync` for this project on first open. To work outside the devcontainer:
+
+```shell
+# from the repo root
+cd PyPiLibrary
+uv sync                          # creates .venv, installs deps + dev group
+uv run ruff check                # lint
+uv run ruff format --check       # formatting check
+uv run pyright                   # type check
+uv run pytest                    # tests
+uv build                         # wheel + sdist into ./dist
+```
+
+## Publishing
+
+Releases are produced by `.github/workflows/build-pypilibrary-task.yml` (called from `build-release-task.yml` to build, lint, type-check, test, and upload the wheel + sdist as a workflow-run artifact). Publishing is a separate top-level `publish-pypi` job in `publish-release.yml` that downloads the artifact by name and runs [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no `PYPI_API_TOKEN` secret is involved. The publish job has `id-token: write` only at that single job level, so the test-pull-request flow (which calls the same build task during PR validation) doesn't need to propagate that permission through the reusable workflow chain.
+
+First-time setup (one-time, on PyPI):
+
+1. PyPI → **Account settings** → **Publishing** → **Add a new pending publisher**.
+2. Project name: `ptr727-projecttemplate-library`. Owner: `ptr727`. Repo: `ProjectTemplate`. Workflow: `publish-release.yml`. Environment: `pypi`.
+3. GitHub repo → **Settings** → **Environments** → create `pypi` environment (optionally with required reviewers).
+4. The first successful release converts the pending publisher to a real publisher.
+
+## Template Adoption
+
+When deriving a new project from this template:
+
+- Replace the package name `ptr727-projecttemplate-library` (in `pyproject.toml`, this README, and CI) with your name.
+- Rename `src/ptr727_projecttemplate_library/` to your import name.
+- Re-register the trusted publisher on PyPI under the new project name.
+- **Wire up a versioning scheme before the first publish.** `_version.py` ships with `__version__ = "0.0.0"` as a placeholder. The publish workflow uses `skip-existing: true` so the workflow won't fail on duplicate uploads — but **no new versions will land on PyPI** until you replace `0.0.0` with something that increments. Common options:
+  - [`hatch-vcs`](https://github.com/ofek/hatch-vcs) — derive the version from git tags. Add it to `[build-system].requires` and switch `[tool.hatch.version]` to `source = "vcs"`. Pairs well with tag-driven releases.
+  - **Read from `version.json`** — the .NET side uses Nerdbank.GitVersioning which reads from `version.json`. A small custom Hatchling plugin or a CI step can pull the version into `_version.py` so .NET and Python ship with matching versions.
+  - **Manual bumps** — edit `_version.py` in each release PR. Simplest, but easy to forget.
+
+If you don't want a Python project at all, delete the `PyPiLibrary/` folder, the `build-pypilibrary-task.yml` workflow, the `build-pypilibrary` job in `build-release-task.yml`, the `publish-pypi` job in `publish-release.yml`, and the `uv` block in `.github/dependabot.yml`.

ptr727_projecttemplate_library-0.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ptr727-projecttemplate-library"
+description = "Python PyPI template library — companion to the .NET NuGetLibrary in this template repo."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Pieter Viljoen" }]
+requires-python = ">=3.14"
+keywords = ["template", "pypi", "library"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dynamic = ["version"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ptr727/ProjectTemplate"
+Source = "https://github.com/ptr727/ProjectTemplate"
+Issues = "https://github.com/ptr727/ProjectTemplate/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "ruff>=0.9",
+    "pyright>=1.1.390",
+]
+
+[tool.hatch.version]
+path = "src/ptr727_projecttemplate_library/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ptr727_projecttemplate_library"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "UP",   # pyupgrade
+    "N",    # pep8-naming
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.14"
+typeCheckingMode = "standard"
+# Per-path strictness: `strict` accepts directory paths and applies
+# strict-mode type checking to everything under them — equivalent to
+# placing `# pyright: strict` at the top of every file in those dirs.
+# Public library surface (`src/`) needs tight types; tests inherit the
+# standard mode set above (fixtures, mocks, and parametrize args are
+# commonly looser).
+strict = ["src"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]

ptr727_projecttemplate_library-0.0.0/src/ptr727_projecttemplate_library/__init__.py

@@ -0,0 +1,6 @@
+"""Python PyPI template library."""
+
+from ptr727_projecttemplate_library._version import __version__
+from ptr727_projecttemplate_library.example import greet
+
+__all__ = ["__version__", "greet"]

ptr727_projecttemplate_library-0.0.0/src/ptr727_projecttemplate_library/_version.py

@@ -0,0 +1,8 @@
+"""Single-source-of-truth for the package version.
+
+Hatchling reads ``__version__`` from this module via ``[tool.hatch.version]``.
+For tag-driven versioning, swap this for ``hatch-vcs`` and configure the build
+backend to derive the version from git tags.
+"""
+
+__version__ = "0.0.0"

ptr727_projecttemplate_library-0.0.0/src/ptr727_projecttemplate_library/example.py

@@ -0,0 +1,6 @@
+"""Trivial example module — replace with your library code."""
+
+
+def greet(name: str) -> str:
+    """Return a friendly greeting for ``name``."""
+    return f"Hello, {name}!"

ptr727_projecttemplate_library-0.0.0/tests/test_example.py

@@ -0,0 +1,16 @@
+"""Tests for ``ptr727_projecttemplate_library.example``."""
+
+from ptr727_projecttemplate_library import __version__, greet
+
+
+def test_version_is_string() -> None:
+    assert isinstance(__version__, str)
+    assert len(__version__) > 0
+
+
+def test_greet_uses_name() -> None:
+    assert greet("world") == "Hello, world!"
+
+
+def test_greet_with_empty_name() -> None:
+    assert greet("") == "Hello, !"