PyScaffold Documentation

Extending PyScaffold relies on two fundamental concepts:

1. Project structure representation: An in-memory model of the files and directories that PyScaffold intends to create.
2. Action pipeline: The mechanism through which PyScaffold executes file operations.

Extensions interact with these by implementing methods that intercept the pipeline to modify the structure or the actions themselves (e.g., using reject to prevent default files from being generated or modify to change the contents of an existing file).

PyScaffold represents a Python package project internally as a tree data structure. This tree is implemented as a nested dict where:

• Keys represent the file system path (relative to the project folder).
• Values represent the file content or a nested dictionary for sub-directories.

Note on versioning: Since version 4.0, the structure considers everything under the project folder, excluding the top-level project directory itself.

Example of a directory structure:

• folder/ contains file.txt (content: "Hello World!") and another-folder/.
• folder/another-folder/ contains empty-file.txt (empty content).

{
    "folder": {
        "file.txt": "Hello World!",
        "another-folder": {
            "empty-file.txt": ""
        }
    }
}

PyScaffold uses setuptools_scm to infer the project version from Git tags.

1. Tagging: Use the format MAJOR.MINOR[.PATCH] (e.g., 0.1.0 or 0.1).
2. Retrieving version: You can check the current PEP 440-compliant version using:

   python -m setuptools_scm

3. PyPI Requirement: Because PyPI rejects local versions (like 0.1.dev1+abc), you must create a Git tag before uploading a version to PyPI.

PyScaffold projects typically involve two distribution stages:

1. sdist (Source Distribution): A platform-independent distribution generated from the original source code. It is considered best practice to upload an sdist to PyPI alongside your wheels to support platforms that cannot use pre-built wheels. PyScaffold uses setuptools-scm, so documentation and tests are included in the sdist by default.

2. wheel (Built Distribution): A platform-specific distribution that can contain highly optimized, pre-compiled files. Wheels are faster to install but may be tied to specific OSs or Python versions.

Key differences:

• Platform Support: sdist is platform-independent; wheel is platform-specific.
• Content: wheel files often have documentation and test files automatically removed, whereas sdist should include them whenever possible.

To specify how a file should be written to disk, you can use a tuple as the value in the structure dictionary instead of a simple string.

In the tuple (content, operation):

1. The first element is the file content.
2. The second element is a callable (function) responsible for writing that content to the disk.

If you provide only a string as the value, PyScaffold defaults to using pyscaffold.operations.create.

from pyscaffold.operations import create

{
    "src": {
        "namespace": {
            "module.py": ('print("Hello World!")', create)
        }
    }
}

Extensions are the preferred way to add new functionality or modify the action pipeline at runtime. They can be built-in (shipped with pyscaffold) or external (installed as separate Python packages).

Key Extension Mechanics:

• Discovery: PyScaffold dynamically discovers installed extensions using setuptools entry points.
• CLI Integration: Extensions are required to add at least one CLI argument to allow users to opt-in to their behavior. These arguments are automatically added to the main putup parser.
• Pipeline Manipulation: Once activated, extensions can use helper functions from pyscaffold.actions to manipulate the action pipeline and the resulting project structure.

PyScaffold does not attempt to replace dedicated tools like dependency managers or build systems. Instead, it provides sane default configurations for the most common Python ecosystem tools so they work together seamlessly.

By default, a generated project includes configurations for:

• setuptools: For building Python packages.
• Sphinx: For documentation.
• pytest: For testing.
• tox: For task running and testing across environments (e.g., tox -e build, tox -e docs, or tox -e publish).
• pre-commit: For running linters and formatters like black and adhering to PEP 8.

PyScaffold is designed to be composable (it produces a standard Python package that interoperates with other tools), extensible (via a powerful extension system), and has no lock-in (PyScaffold is not a required install or development dependency of your project once generated).

To generate files that adapt to project parameters (like package name or author), you can use the following for file content:

1. string.Template objects: PyScaffold uses safe_substitute to populate these templates.
2. Functions: A function that accepts a single dict argument (containing pyscaffold.operations.ScaffoldOpts) and returns a str.

These templates and functions are executed during the scaffolding process using the current project's options.

PyScaffold ≥ 3 uses a src directory to hold the actual Python package. This structure prevents common import errors where Python might import the local package directory instead of the installed version during testing.

Key Rules:

• All files inside src are assumed to be part of the distributed package.
• Do not include files in src that are not meant for distribution (e.g., temporary files, local configs).
• For extra files not meant for distribution, use the docs folder or create a dedicated folder in the repository root (e.g., examples).