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.
cd
to the directory of the new Python packageCreate a virtual environment and install the project dependencies:
uv sync
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