Using Pyprefabยถ

pyprefab CLIยถ

pyprefab requires only a few pieces of information to create the boilerplate for a Python package.

>>> pyprefab --help

Usage: pyprefab [OPTIONS] NAME

๐Ÿ Create Python package boilerplate ๐Ÿ

โ•ญโ”€ Options โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ *  --name         TEXT  Name of the project [required]                                  โ”‚
โ”‚    --author       TEXT  Project author [default: None]                                  โ”‚
โ”‚    --description  TEXT  Project description [default: None]                             โ”‚
โ”‚    --dir          PATH  Directory that will contain the project [default: <current dir> โ”‚
โ”‚    --docs    --no-docs  Include Sphinx documentation files [default: no-docs]           โ”‚
โ”‚    --help               Show this message and exit.                                     โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

Example CLI useยถ

To create a Python package named holodeck in a directory named trek/code/holodeck:

>>> pyprefab holodeck --author rbarclay \
>>> --description "personal holodeck programs" \
>>> --dir trek/code/holodeck

โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Project Created Successfully โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Created new project holodeck in trek/code/holodeck         โ”‚
โ”‚ Author: rbarclay                                           โ”‚
โ”‚ Description: personal holodeck programs                    โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

The pyprefab command above creates scaffolding for the new holodeck package, with the following files in trek/code/holodeck:

.
โ”œโ”€โ”€ .github
โ”‚ย ย  โ””โ”€โ”€ workflows
โ”‚ย ย      โ”œโ”€โ”€ ci.yaml
โ”‚ย ย      โ”œโ”€โ”€ publish-pypi-test.yaml
โ”‚ย ย      โ””โ”€โ”€ publish-pypi.yaml
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ .pre-commit-config.yaml
โ”œโ”€โ”€ CHANGELOG.md
โ”œโ”€โ”€ CONTRIBUTING.md
โ”œโ”€โ”€ README.md
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ src
โ”‚ย ย  โ””โ”€โ”€ holodeck
โ”‚ย ย      โ”œโ”€โ”€ __init__.py
โ”‚ย ย      โ””โ”€โ”€ app.py
โ””โ”€โ”€ test
    โ””โ”€โ”€ test_app.py

Optional project documentationยถ

Pass the --docs option to pyprefab to include Sphinx-based documentation files with the new package.

>>> pyprefab holodeck --author rbarclay \
>>> --description "personal holodeck programs" \
>>> --dir /users/becky/code/trek/code/holodeck \
>>> --docs

This option adds a docs directory to the code base:

.
โ”œโ”€โ”€ .github
โ”‚ย ย  โ””โ”€โ”€ workflows
โ”‚ย ย      โ”œโ”€โ”€ ci.yaml
โ”‚ย ย      โ”œโ”€โ”€ publish-pypi-test.yaml
โ”‚ย ย      โ””โ”€โ”€ publish-pypi.yaml
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ .pre-commit-config.yaml
โ”œโ”€โ”€ CHANGELOG.md
โ”œโ”€โ”€ CONTRIBUTING.md
โ”œโ”€โ”€ README.md
โ”œโ”€โ”€ docs
โ”‚ย ย  โ””โ”€โ”€ source
โ”‚ย ย      โ”œโ”€โ”€ CHANGELOG.md
โ”‚ย ย      โ”œโ”€โ”€ CONTRIBUTING.md
โ”‚ย ย      โ”œโ”€โ”€ README.md
โ”‚ย ย      โ”œโ”€โ”€ _static
โ”‚ย ย      โ”‚ย ย  โ””โ”€โ”€ custom.css
โ”‚ย ย      โ”œโ”€โ”€ conf.py
โ”‚ย ย      โ”œโ”€โ”€ index.rst
โ”‚ย ย      โ””โ”€โ”€ usage.md
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ src
โ”‚ย ย  โ””โ”€โ”€ holodeck
โ”‚ย ย      โ”œโ”€โ”€ __init__.py
โ”‚ย ย      โ””โ”€โ”€ app.py
โ””โ”€โ”€ test
    โ””โ”€โ”€ test_app.py

Interactive modeยถ

If you donโ€™t explicitly specify options, pyprefab will prompt for them:

>>> pyprefab
Project name ๐Ÿ: holodeck
Project author ๐Ÿ‘ค [None]: rbarclay
Project description ๐Ÿ“ [None]: personal holodeck programs
Project directory ๐ŸŽฌ [/Users/rbarclay/code/holodeck]:
Include Sphinx docs? ๐Ÿ“„ [y/N]: y
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Project Created Successfully โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Created new project holodeck in /Users/rbarclay/holode      โ”‚
โ”‚ Author: rbarclay                                            โ”‚
โ”‚ Description: personal holodeck programs                     โ”‚
โ”‚ Documentation: /Users/rbarclay/holodeck/docs                โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

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:

    uv sync
    
  3. Test the project setupt:

    uv run <your_package_name>
    

    You should see 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:

    uv run pytest
    

Previewing documentationยถ

If your project includes the optional Sphinx documentation, make sure you can build and preview the docs before updating them:

uv run --group docs sphinx-autobuild docs/source docs/_build/html

The output of the above command provides a URL for viewing the documentation via a local server (usually http://127.0.0.1:8000).

The HTML pages are in docs/_build/html.
[sphinx-autobuild] Serving on http://127.0.0.1:8000
[sphinx-autobuild] Waiting to detect changes...

Adding the project to gitยถ

To create a new git repository for the project (this is optional):

git init
git add .
git commit -am "Initial commit"

Tip

If you use pre-commit, 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 install the pre-commit hooks: pre-commit install