PyScaffold

4.6 · active · verified Thu Apr 16

PyScaffold is a template tool designed to quickly set up the scaffold of a Python project, following best practices and integrating with tools like setuptools_scm for version management, tox for testing, and pre-commit for quality control. It is currently at version 4.6 and typically releases minor or patch updates every few months, ensuring compatibility and incorporating improvements.

Common errors

```
putup: command not found
```
cause The `putup` command is not in your system's PATH, or PyScaffold was not installed correctly.

fix Ensure PyScaffold is installed (`pip install pyscaffold`) and that your Python environment's script directory is included in your system's PATH. If using `pipx`, ensure `pipx ensurepath` has been run.
```
Directory 'my_project' already exists. Use --force to overwrite.
```
cause PyScaffold prevents overwriting existing directories by default to avoid accidental data loss.

fix If you intend to overwrite the directory, add the `--force` flag: `putup my_project --force`. Otherwise, choose a different project name.
```
ValueError: No such extension found: 'xyz'
```
cause You tried to use an extension (`--extension xyz`) that is either not installed or misspelled.

fix First, ensure the extension package is installed (e.g., `pip install pyscaffoldext-xyz`). Then, verify the extension name is correct (e.g., `putup my_project --extension some_extension`). Check PyScaffold's documentation or PyPI for available extensions and their exact names.

Warnings

breaking PyScaffold v4.5 changed the default configuration directory on macOS from `~/Library/Preferences` to `~/Library/Application Support`. If you rely on custom PyScaffold configurations stored at the old path, they will no longer be found automatically.
Fix: Manually migrate any custom configuration files from `~/Library/Preferences/PyScaffold` to `~/Library/Application Support/PyScaffold`.
gotcha PyScaffold requires Python 3.7 or newer. Attempting to use it with older Python versions will result in `SyntaxError` or other runtime errors.
Fix: Ensure your environment uses Python 3.7+ (e.g., `python3.x -m pip install pyscaffold` where `x >= 7`).
deprecated For extension developers, PyScaffold v4.6 recommends using `importlib.resources.files` instead of `importlib.resources.read_text` or `pkgutil.get_data` for accessing package data. While old methods still work, they may be deprecated in future Python versions.
Fix: Update your extension code to use `importlib.resources.files` for resource access, e.g., `importlib.resources.files('my_package').joinpath('data.txt').read_text()`.
gotcha Generated `tox.ini` files from PyScaffold v4.4 onwards include workarounds to avoid problematic `tox` versions 4.0 and 4.1. If you manually modify the generated `tox.ini` or use an older PyScaffold version, you might encounter issues with these specific `tox` releases.
Fix: Prefer using `tox` versions outside of the 4.0-4.1 range or upgrade PyScaffold to v4.4 or newer to ensure the generated `tox.ini` template handles this automatically.

Install

pip install pyscaffold Install PyScaffold

Imports

create_project
```
from pyscaffold.api import create_project
```
While PyScaffold is primarily a command-line tool ('putup'), 'create_project' is the main programmatic entry point for creating projects.

Quickstart

Create a new project named 'my_new_project'. Navigate into the directory, install the project in editable mode with development and test dependencies, then run tests using tox.

putup my_new_project
cd my_new_project
pip install -e '.[dev,test]'
tox -e py

view raw JSON →