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 package [required] โ
โ --author TEXT Package author [default: None] โ
โ --description TEXT Package description [default: None] โ
โ --dir PATH Directory that will contain the package [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
โญโโโโโโโโโโโโโโ Package Created Successfully โโโโโโโโโโโโโโโโโฎ
โ Created new package 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
โย ย โโโ __main__.py
โย ย โโโ app.py
โโโ test
โโโ test_app.py
Optional package 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
โย ย โโโ __main__.py
โย ย โโโ app.py
โโโ test
โโโ test_app.py
Interactive modeยถ
If you donโt explicitly specify options, pyprefab will prompt for them:
>>> pyprefab
Package name ๐: holodeck
Package author ๐ค [None]: rbarclay
Package description ๐ [None]: personal holodeck programs
Package directory ๐ฌ [/Users/rbarclay/code/holodeck]:
Include Sphinx docs? ๐ [y/N]: y
โญโโโโโโโโโโโโโโโโโ Package Created Successfully โโโโโโโโโโโโโโโฎ
โ Created new package 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
Hosting your project on GitHubยถ
Code generated by pyprefab includes some extra boilerplate files for
projects hosted on GitHub. There are located in the .github
directory, which
you can delete if youโre not using GitHub.
GitHub workflowsยถ
The following
GitHub workflow
files are generated by pyprefab. These are located in the .github/workflow
directory:
ci.yaml
: runs tests against multiple versions of python, checks test coverage, and runs a linter check using ruffpublish-pypi-test.yaml
: publishes the package to test PyPi (setup required, see comments in the file)publish-pypi.yaml
: publishes the package to PyPI (setup required, see comments in the file)
Tip
GitHub reposistories have actions enabled by default, so review the workflow files to ensure that their triggers match your expectations.
Depdabot configยถ
The .github
directory also contains a configuration file for
GitHub Dependabot: dependabot.yaml
.
This file instructs Dependabot to check your projectโs Python and GitHub action dependencies each week and submit pull requests if there are any updates.
Itโs important to review and merge these pull requests regularly to keep your code base secure.