pyprefab 0.3.2__tar.gz → 0.4.0__tar.gz

pyprefab-0.4.0/.github/workflows/ci.yaml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+env:
+  FORCE_COLOR: "1"
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  PIP_NO_PYTHON_VERSION_WARNING: "1"
+
+jobs:
+
+  lint:
+    name: Run linter
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv 🌟
+        uses: astral-sh/setup-uv@v5
+        with:
+            version: ">=0.0.1"
+
+      - name: Lint 🧹
+        run: |
+          uv tool install ruff
+          ruff check
+
+  tests:
+    name: Run tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv 🌟
+        uses: astral-sh/setup-uv@v5
+        with:
+            python-version: ${{ matrix.python-version }}
+            version: ">=0.0.1"
+
+      - name: Test with python ${{ matrix.python-version }} 🧪
+        run: |
+          uv run --frozen coverage run \
+            --data-file .coverage.${{ matrix.python-version }} \
+            -m pytest
+
+      - name: Upload coverage data 📤
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-data-${{ matrix.python-version }}
+          path: .coverage.*
+          include-hidden-files: true
+          if-no-files-found: ignore
+
+  coverage:
+    # https://hynek.me/articles/ditch-codecov-python/
+    name: Combine coverage reports & fail if below threshold
+    runs-on: ubuntu-latest
+    needs: tests
+    if: always()
+
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv 🌟
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: '>=0.0.1'
+
+      - name: Download coverage data 📥
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-data-*
+          merge-multiple: true
+
+      - name: Generate coverage report 📊
+        run: |
+          uv tool install 'coverage[toml]'
+
+          coverage combine
+          coverage html --skip-covered --skip-empty
+          coverage report --format=markdown >> $GITHUB_STEP_SUMMARY
+
+          # Generate report again, this time with a fail-under threshold
+          coverage report --fail-under=80
+
+      - name: Upload HTML report if coverage check fails
+        uses: actions/upload-artifact@v4
+        with:
+            name: html-cov-report
+            path: htmlcov
+        if: ${{ failure() }}

pyprefab-0.3.2/.github/workflows/publish-pypi.yml → pyprefab-0.4.0/.github/workflows/publish-pypi.yaml

@@ -8,7 +8,7 @@ on:
   push:
     tags:
       # only run workflow for tags in release format
-      - "v[0-9].[0-9].[0-9]"
+      - "v[0-9]+.[0-9]+.[0-9]+"
 
 jobs:
   build:

pyprefab-0.4.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to `pyprefab` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com), and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.4.0] - [2025-01-26]
+
+### Added
+
+- New templates for GitHub workflows: ci (linting, tests, and coverage), publishing to TestPyPI, and publishing to PyPI
+- Project changelog
+- New CHANGELOG.md template
+- New CONTRIBUTING.md template
+
+### Changed
+
+- Add CLI prompts as an alternate to passing command options
+- `--directory` option renamed to `--dir`
+- Prompt user when specified project directory is not empty
+- List created package components on README.md
+
+### Fixed
+
+- Correct CLI example on README.md
+
+## [0.3.2] - [2025-01-13](https://github.com/bsweger/pyprefab/compare/v0.3.1...v0.3.2)
+
+### Changed
+
+- Rename CLI command to `pyprefab`
+
+## [0.3.1] - [2025-01-13](https://github.com/bsweger/pyprefab/compare/v0.3.0...v0.3.1)
+
+### Added
+
+- New templates for generating Python package boilerplate: .gitignore, README.md, app.py
+
+### Changed
+
+- Rename project to `pyprefab`
+
+### Removed
+
+- Removed sample `hello_world` module in favor of template-driven boilerplate
+
+## [0.3.0] - [2025-01-12](https://github.com/bsweger/pyprefab/compare/v0.2.1...v0.3.0)
+
+### Added
+
+- Added `pyproject.toml` template as the first piece of template-driven Python boilerplate
+
+### Removed
+
+- Removed artifacts from prior iteration of `pyprefab` that pre-dates the template-drive approach

pyprefab-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,151 @@
+# Contributing to pyprefab
+
+This is a personal, very-part-time project, largely driven by my own opinions
+about how best to configure a Python code base.
+
+Contributions as described below are welcome.
+
+## Reporting bugs
+
+If something isn't working as described, or if you find a mistake in the
+documentation, please feel free to report a bug by
+[opening an issue](https://github.com/bsweger/pyprefab/issues).
+
+## Contributing to the code base
+
+Contributions to the code base are welcome. If you want to add a new feature,
+please open an issue first. Because `pyprefab` is an opinion-drive personal
+project, it's best to make sure our opinions are aligned before doing any work!
+
+If you'd like to tackle an existing issue, please leave a comment on it.
+
+### Creating your local development environment
+
+For contributing to this code base, you'll need:
+
+- A [GitHub account](https://github.com/)
+- [Git](https://git-scm.com/) installed on your machine
+- **optional**: [uv](https://docs.astral.sh/uv/getting-started/installation/)
+(the Python-based directions below use `uv`, but if you
+already have a preferred Python toolset, that should work too)
+
+> [!IMPORTANT]
+> If you have an active Python virtual environment (for example, conda's
+> base environment), you'll need to deactivate it before following the
+> instructions below.
+
+#### Configure git
+
+1. On GitHub, [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) this repository.
+
+2. Clone the forked repository to your machine:
+
+    ```script
+    git clone https://github.com/<username>/pyprefab.git
+    cd pyprefab
+    ```
+
+3. **optional:** Set the `upstream` remote to sync your fork with the `pyprefab`
+repository:
+
+    ```script
+    git remote add upstream https://github.com/bsweger/pyprefab.git
+    git fetch upstream
+    ```
+
+#### Install project and dependencies
+
+1. From the root of the repo, create a virtual environment and install the
+project dependencies. The
+[`uv sync` command](https://docs.astral.sh/uv/reference/cli/#uv-sync) handles
+installing Python, creating a virtual environment, and installing project
+dependencies.
+
+    ```script
+    uv sync
+    ```
+
+   (More information about how uv
+    [finds or downloads a Python interpreter](https://docs.astral.sh/uv/reference/cli/#uv-python))
+
+2. Run the test suite to check that everything works correctly:
+
+    > [!TIP]
+    > Prefixing python commands with `uv run` instructs uv to run the command
+    > in the project's virtual environment, even if you haven't explicitly
+    > activated it.
+
+    ```script
+    uv run pytest
+    ```
+
+3. Install the `pre-commit` hooks used for linting and other checks (this may
+take a few minutes but only needs to be done once).
+
+    ```script
+    uv run pre-commit install
+    ```
+
+4. Make sure the `pre-commit` checks are working correctly:
+
+    ```script
+    uv run pre-commit install
+    ```
+
+### Updating your development environment
+
+If time has passed between your initial project setup and when you make changes
+to the code, make sure your fork and development environment are up-to-date.
+
+1. Sync your fork to the upstream repository:
+
+    ```script
+    git checkout main
+    git fetch upstream
+    git rebase upstream/main
+    git push origin main
+    ```
+
+2. Update your project dependencies:
+
+    ```script
+    uv sync
+    ```
+
+### Adding project dependencies
+
+If your change requires a new dependency, add it as follows:
+
+```script
+uv add <dependency>
+```
+
+The [`uv add`](https://docs.astral.sh/uv/reference/cli/#uv-add) command will:
+
+- Add the dependency to `pyproject.toml`
+- Install the dependency into the project's virtual environment
+- Update the project's lockfile (`uv.lock`)
+
+Make sure to commit the updated versions of `pyproject.toml` and `uv.lock`.
+
+### Submitting code changes
+
+After you've completed the changes described in the issue you're working on,
+you can submit them by [creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) (PR) in the `pyprefab` repository.
+
+Please ensure the following are true before creating the PR:
+
+- Your change is covered by tests, if applicable
+- All tests pass (`uv run pytest`)
+- All pre-commit checks are successful
+(these checks will run automatically as you make commits)
+- The `[Unreleased]` section of [CHANGELOG.md](CHANGELOG.md) contains a
+description of your change.
+
+The PR itself should:
+
+- Have a descriptive title
+- Be [linked to its corresponding issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)
+in the description.
+- Have a description that includes any other information or context that will
+help a code reviewer understand your changes.

pyprefab-0.4.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.2
+Name: pyprefab
+Version: 0.4.0
+Summary: Python application template for personal use
+License: MIT License
+Project-URL: Repository, https://github.com/bsweger/pyprefab.git
+Project-URL: Changelog, https://github.com/bsweger/pyprefab/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: structlog
+Requires-Dist: rich
+Requires-Dist: typer
+Requires-Dist: jinja2>=3.1.5
+
+# pyprefab
+
+A template-driven command line interface (CLI) that creates the scaffolding
+for a fully-functional, modern Python package. The goal of pyprefab is to get
+you straight to writing application code by handling project startup tasks
+like logging setup and creating a test harness.
+
+The scaffolding includes:
+
+- project files in the [src layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/) format
+- `pyproject.toml` with [dependency groups](https://packaging.python.org/en/latest/specifications/dependency-groups/#dependency-groups)
+- `CHANGELOG.md`, `CONTRIBUTING.md`, `.gitignore`, and `README.md`
+- automated package versioning with [setuptools-scm](https://pypi.org/project/setuptools-scm/)
+- [structlog](https://www.structlog.org/)-based pre-configured logging
+- a [pytest](https://docs.pytest.org)-based test harness
+- a [pre-commit](https://pre-commit.com/) configuration with common plugins like
+[ruff](https://docs.astral.sh/ruff/) for linting (optional)
+- GitHub workflow that automatically runs code checks, tests, and a test
+coverage report
+- GitHub workflows to publish the package to TestPyPI and PyPI
+
+## Quickstart
+
+If you have `uv` installed,
+[`uv tool run`](https://docs.astral.sh/uv/reference/cli/#uv-tool-run) is the
+fastest way to create a new Python package with pyprefab:
+
+```sh
+uvx pyprefab <name-of-new-package>
+```
+
+Otherwise, use `pip` or `pipx` to install pyprefab:
+
+```sh
+pip install pyprefab
+
+pyprefab <name-of-new-package>
+```
+
+## Details
+
+### pyprefab CLI
+
+By design, pyprefab requires only a few pieces of information to create the
+boilerplate for a Python package.
+
+```bash
+➜ pyprefab --help
+
+  Usage: pyprefab [OPTIONS] NAME
+
+ 🐍 Create Python package boilerplate 🐍
+
+╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *    name      TEXT  Name of the project                                                                                      │
+│                      [required]                                                                                               │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *  --author             TEXT  Project author                                                                                  │
+│                               [required]                                                                                      │
+│ *  --description        TEXT  Project description                                                                             │
+│                               [required]                                                                                      │
+│ *  --dir                PATH  Directory that will contain the project                                                         │
+│                               [required]                                                                                      │
+│    --help                     Show this message and exit.                                                                     │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+For example:
+
+```sh
+pyprefab project_test --author lassie --description "this is a pet project for lassie" --dir ~/code/lassie
+```
+
+If you don't explicitly pass the `--author`, `--description`, and `--dir` options,
+pyprefab will prompt you for them:
+
+```sh
+➜ pyprefab project_test
+Project author: lassie
+Project description: this is a pet project for lassie
+Project directory: /Users/dogs/code/lassie
+```
+
+## Creating a dev environment for the new package
+
+Follow the steps below to create a development environment for Python packages
+generated by pyprefab.
+
+These directions use `uv`, but you can use your preferred tooling.
+
+1. `cd` to the directory of the new Python package
+
+2. Create a virtual environment and install the project dependencies:
+
+    ```script
+    uv sync
+    ```
+
+3. Test the project setupt:
+
+    ```script
+    uv run <your_package_name>
+    ```
+
+    You should see a log output stating that the project has been set up correctly.
+
+    For example:
+    `2025-01-13 02:29:08 [info     ] project_test successfully created.`
+
+    You can also run the tests:
+
+    ```script
+    uv run pytest
+    ```
+
+**Optional:**
+
+- Add the new project to a git repository:
+
+    ```script
+    git init
+    git add .
+    git commit -am "Initial commit"
+    ```
+
+- If you use [pre-commit](https://pre-commit.com/), pyprefab's boilerplate
+includes a baseline `pre-commit-config.yaml` configuration. To use it, make
+sure the project has been added to git (see above) and run the following
+command to install the pre-commit git hook scripts:
+
+    ```script
+    pre-commit install
+    ```
+
+## Contributing to pyprefab
+
+Please refer to
+[CONTRIBUTING.md](https://github.com/bsweger/pyprefab/blob/main/CONTRIBUTING.md).

pyprefab-0.4.0/README.md

@@ -0,0 +1,139 @@
+# pyprefab
+
+A template-driven command line interface (CLI) that creates the scaffolding
+for a fully-functional, modern Python package. The goal of pyprefab is to get
+you straight to writing application code by handling project startup tasks
+like logging setup and creating a test harness.
+
+The scaffolding includes:
+
+- project files in the [src layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/) format
+- `pyproject.toml` with [dependency groups](https://packaging.python.org/en/latest/specifications/dependency-groups/#dependency-groups)
+- `CHANGELOG.md`, `CONTRIBUTING.md`, `.gitignore`, and `README.md`
+- automated package versioning with [setuptools-scm](https://pypi.org/project/setuptools-scm/)
+- [structlog](https://www.structlog.org/)-based pre-configured logging
+- a [pytest](https://docs.pytest.org)-based test harness
+- a [pre-commit](https://pre-commit.com/) configuration with common plugins like
+[ruff](https://docs.astral.sh/ruff/) for linting (optional)
+- GitHub workflow that automatically runs code checks, tests, and a test
+coverage report
+- GitHub workflows to publish the package to TestPyPI and PyPI
+
+## Quickstart
+
+If you have `uv` installed,
+[`uv tool run`](https://docs.astral.sh/uv/reference/cli/#uv-tool-run) is the
+fastest way to create a new Python package with pyprefab:
+
+```sh
+uvx pyprefab <name-of-new-package>
+```
+
+Otherwise, use `pip` or `pipx` to install pyprefab:
+
+```sh
+pip install pyprefab
+
+pyprefab <name-of-new-package>
+```
+
+## Details
+
+### pyprefab CLI
+
+By design, pyprefab requires only a few pieces of information to create the
+boilerplate for a Python package.
+
+```bash
+➜ pyprefab --help
+
+  Usage: pyprefab [OPTIONS] NAME
+
+ 🐍 Create Python package boilerplate 🐍
+
+╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *    name      TEXT  Name of the project                                                                                      │
+│                      [required]                                                                                               │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *  --author             TEXT  Project author                                                                                  │
+│                               [required]                                                                                      │
+│ *  --description        TEXT  Project description                                                                             │
+│                               [required]                                                                                      │
+│ *  --dir                PATH  Directory that will contain the project                                                         │
+│                               [required]                                                                                      │
+│    --help                     Show this message and exit.                                                                     │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+For example:
+
+```sh
+pyprefab project_test --author lassie --description "this is a pet project for lassie" --dir ~/code/lassie
+```
+
+If you don't explicitly pass the `--author`, `--description`, and `--dir` options,
+pyprefab will prompt you for them:
+
+```sh
+➜ pyprefab project_test
+Project author: lassie
+Project description: this is a pet project for lassie
+Project directory: /Users/dogs/code/lassie
+```
+
+## Creating a dev environment for the new package
+
+Follow the steps below to create a development environment for Python packages
+generated by pyprefab.
+
+These directions use `uv`, but you can use your preferred tooling.
+
+1. `cd` to the directory of the new Python package
+
+2. Create a virtual environment and install the project dependencies:
+
+    ```script
+    uv sync
+    ```
+
+3. Test the project setupt:
+
+    ```script
+    uv run <your_package_name>
+    ```
+
+    You should see a log output stating that the project has been set up correctly.
+
+    For example:
+    `2025-01-13 02:29:08 [info     ] project_test successfully created.`
+
+    You can also run the tests:
+
+    ```script
+    uv run pytest
+    ```
+
+**Optional:**
+
+- Add the new project to a git repository:
+
+    ```script
+    git init
+    git add .
+    git commit -am "Initial commit"
+    ```
+
+- If you use [pre-commit](https://pre-commit.com/), pyprefab's boilerplate
+includes a baseline `pre-commit-config.yaml` configuration. To use it, make
+sure the project has been added to git (see above) and run the following
+command to install the pre-commit git hook scripts:
+
+    ```script
+    pre-commit install
+    ```
+
+## Contributing to pyprefab
+
+Please refer to
+[CONTRIBUTING.md](https://github.com/bsweger/pyprefab/blob/main/CONTRIBUTING.md).

{pyprefab-0.3.2 → pyprefab-0.4.0}/pyproject.toml

@@ -3,7 +3,7 @@ name = 'pyprefab'
 description = 'Python application template for personal use'
 license = {text = 'MIT License'}
 readme = 'README.md'
-requires-python = '>=3.9'
+requires-python = '>=3.9,<3.14'
 classifiers = [
     'Programming Language :: Python :: 3',
     'License :: OSI Approved :: MIT License',
@@ -19,6 +19,7 @@ dependencies = [
 
 [dependency-groups]
 dev = [
+    'build',
     'coverage',
     'freezegun',
     'mypy',
@@ -26,6 +27,7 @@ dev = [
     'pytest',
     "pytest-random-order>=1.1.1",
     'ruff',
+    "tomli>=2.2.1",
 ]
 
 [project.scripts]
@@ -33,6 +35,7 @@ pyprefab = "pyprefab.cli:app"
 
 [project.urls]
 Repository = "https://github.com/bsweger/pyprefab.git"
+Changelog = "https://github.com/bsweger/pyprefab/blob/main/CHANGELOG.md"
 
 [build-system]
 # Minimum requirements for the build system to execute.