PyScaffold

https://pyscaffold.org/en/stable/
Admin
PyScaffold is a project generator for bootstrapping high-quality Python packages that are ready to...
Tokens:132,443
Snippets:1,205
Trust Score:7.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Create a project with namespace and package configuration

Source: https://pyscaffold.org/en/stable/usage.html

This example demonstrates creating a project with a specific installation name and a namespace package structure, useful for advanced packaging scenarios.

```bash
putup my_zope_subpackage --name my-zope-subpackage --namespace zope --package subpackage
```

--------------------------------

### Initialize and Setup Virtual Environment

Source: https://pyscaffold.org/en/stable/dependencies.html

Commands to install PyScaffold, create a new project, and configure a virtual environment with essential development tools.

```bash
$ pip install pyscaffold
$ putup myproj
$ cd myproj
$ virtualenv .venv
# OR python -m venv .venv
$ source .venv/bin/activate
$ pip install -U pip setuptools setuptools_scm tox
```

--------------------------------

### Interactive project setup

Source: https://pyscaffold.org/en/stable/usage.html

The experimental --interactive option opens your default text editor with an editable help text for guided project setup.

```bash
putup -i my_little_project
```

--------------------------------

### Install and Build Project

Source: https://pyscaffold.org/en/stable/migration.html

After migration, install the project locally using `pip install .` and then test the build process with `tox -e build` or `python -m build --wheel`. These commands help verify the project structure and configuration.

```bash
pip install .

```

```bash
tox -e build

```

```bash
python -m build --wheel

```

--------------------------------

### Start Django Project with PyScaffold

Source: https://pyscaffold.org/en/stable/_sources/features.rst.txt

Use this command to create a new Django project enhanced by PyScaffold features. Ensure `pyscaffoldext-django` is installed.

```bash
django-admin startproject my_project
```

--------------------------------

### Initialize a project with putup

Source: https://pyscaffold.org/en/stable/_sources/usage.rst.txt

Examples of using the putup CLI to create projects with specific names, licenses, and extensions.

```bash
putup Scikit-Gravity -p skgravity -l BSD-3-Clause
```

```bash
putup youtub --django --pre-commit -d "Ultimate video site for hot tub fans"
```

```bash
putup thoroughly_tested --cirrus
```

```bash
putup my_zope_subpackage --name my-zope-subpackage --namespace zope --package subpackage
```

--------------------------------

### Install and Test Project

Source: https://pyscaffold.org/en/stable/dependencies.html

Standard commands to install the current project in editable mode and run tests via tox.

```bash
$ pip install -e .
$ tox
```

--------------------------------

### Installing Pre-commit Hooks

Source: https://pyscaffold.org/en/stable/features.html

After scaffolding your project, install pre-commit by running `pip install pre-commit` and then `pre-commit install` to enable Git pre-commit hooks.

```bash
pre-commit install
```

--------------------------------

### Install setuptools-scm

Source: https://pyscaffold.org/en/stable/features.html

This package is required for certain PyScaffold functionalities, particularly those related to version management. Install it using pip.

```bash
pip install setuptools_scm
```

--------------------------------

### Initialize a new project

Source: https://pyscaffold.org/en/stable/usage.html

Creates a new project directory with a standard template. Use the -i flag to trigger the interactive setup mode.

```bash
putup my_project
```

```bash
putup -i my_project
```

--------------------------------

### Install Pre-commit Hook

Source: https://pyscaffold.org/en/stable/examples/pre-commit-extension.html

Attempts to install the pre-commit hook using the found executable. If the installation fails, it logs a warning with instructions for manual installation.

```python
def install(struct: Structure, opts: ScaffoldOpts) -> ActionParams:
    """Attempts to install pre-commit in the project"""
    project_path = opts.get("project_path", "PROJECT_DIR")
    pre_commit = opts.get(CMD_OPT) or shell.get_command(EXECUTABLE, venv.get_path(opts))
    # ^  try again after venv, maybe it was installed
    if pre_commit:
        try:
            with chdir(opts.get("project_path", "."), **opts):
                pre_commit("install", pretend=opts.get("pretend"))
            logger.warning(SUCCESS_MSG)
            return struct, opts
        except ShellCommandException:
            logger.error(ERROR_MSG, exc_info=True)

    logger.warning(INSTALL_MSG.format(project_path=project_path))
    return struct, opts

```

--------------------------------

### Initialize and Configure a PyScaffold Project

Source: https://pyscaffold.org/en/stable/_sources/dependencies.rst.txt

Standard workflow for creating a new project, setting up a virtual environment, and installing dependencies.

```bash
$ pip install pyscaffold
$ putup myproj
$ cd myproj
$ virtualenv .venv
# OR python -m venv .venv
$ source .venv/bin/activate
$ pip install -U pip setuptools setuptools_scm tox
# ... edit setup.cfg to add dependencies ...
$ pip install -e .
$ tox
```

--------------------------------

### Install development dependencies

Source: https://pyscaffold.org/en/stable/contributing.html

Install the package in editable mode and set up pre-commit hooks.

```bash
pip install -U pip setuptools -e .
```

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Custom PyScaffold Configuration File Example

Source: https://pyscaffold.org/en/stable/usage.html

This example shows the structure of a custom PyScaffold configuration file. It allows specifying metadata like author and license, and PyScaffold extensions to be used. This file helps in automating project creation with preferred settings.

```ini
[metadata]
author = John Doe
author-email = john.joe@gmail.com
license = MPL-2.0

[pyscaffold]
extensions =
    cirrus
    pre-commit

```

--------------------------------

### Install Pre-commit Hooks

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/pre_commit.html

Attempts to install pre-commit hooks in the project. If the executable is found, it runs `pre-commit install`. Otherwise, it logs a warning with installation instructions.

```python
def install(struct: Structure, opts: ScaffoldOpts) -> ActionParams:
    """Attempts to install pre-commit in the project"""
    project_path = opts.get("project_path", "PROJECT_DIR")
    pre_commit = opts.get(CMD_OPT) or shell.get_command(EXECUTABLE, venv.get_path(opts))
    # ^  try again after venv, maybe it was installed
    if pre_commit:
        try:
            with chdir(opts.get("project_path", "."), **opts):
                pre_commit("install", pretend=opts.get("pretend"))
            logger.warning(SUCCESS_MSG)
            return struct, opts
        except ShellCommandException:
            logger.error(ERROR_MSG, exc_info=True)

    logger.warning(INSTALL_MSG.format(project_path=project_path))
    return struct, opts
```

--------------------------------

### GET /read_setupcfg

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/info.html

Reads a configuration file in setup.cfg format from a specified path.

```APIDOC
## GET /read_setupcfg

### Description
Reads-in a configuration file that follows a setup.cfg format. Useful for retrieving stored information during updates.

### Method
GET

### Endpoint
/read_setupcfg

### Parameters
#### Query Parameters
- **path** (PathLike) - Required - Path where to find the config file.
- **filename** (str) - Optional - Name of the file if path is a directory (default: setup.cfg).

### Response
#### Success Response (200)
- **ConfigUpdater** (Object) - Object that can be used to read/edit configuration parameters.
```

--------------------------------

### Install PyScaffold with All Extensions using pip

Source: https://pyscaffold.org/en/stable/_sources/install.rst.txt

Install PyScaffold along with all official extensions using this command. Pip automatically handles requirement installations.

```bash
pip install --upgrade pyscaffold[all]
```

--------------------------------

### Generate CLI Usage Example

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/interactive.html

Generates an example of CLI option usage, including help text, for given actions. Skips options marked for ignoring in the configuration.

```python
def all_examples(parser: ArgumentParser, actions: List[Action], opts: Opts) -> str:
    """Generate a example of usage of the CLI options corresponding to the given
    :obj:`actions <argparse.Action>` including the help text.

    This function will skip options that are marked in the ``"ignore"``
    :obj:`configuration <CONFIG>`.

    See :obj:`example_with_help`.
    """
    parts = (
        example_with_help(parser, a, opts)
        for a in actions
        if long_option(a) not in get_config("ignore")
    )
    return join_block(*parts, sep=os.linesep * 3)
```

--------------------------------

### Install project requirements

Source: https://pyscaffold.org/en/stable/_sources/features.rst.txt

Install dependencies listed in a requirements file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install PyScaffold using pipx

Source: https://pyscaffold.org/en/stable/_sources/install.rst.txt

Install PyScaffold system-wide using pipx for easy access to the 'putup' command, independent of your Python environment. Check pipx documentation for details on managing extra requirements or injecting extensions.

```bash
pipx install pyscaffold
```

--------------------------------

### Install a built distribution

Source: https://pyscaffold.org/en/stable/_sources/faq.rst.txt

Install a pre-built distribution of your Python project using pip. This is the recommended method for users of your package.

```bash
pip install my_project-3.2.3-py3-none-any.whl
```

--------------------------------

### PyScaffold default configuration file

Source: https://pyscaffold.org/en/stable/_sources/usage.rst.txt

Example of a global configuration file used to set default CLI options for putup.

```ini
[metadata]
author = John Doe
author-email = john.joe@gmail.com
license = MPL-2.0

[pyscaffold]
extensions =
    cirrus
    pre-commit
```

--------------------------------

### Define Project Structure Example

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/structure.html

Demonstrates how to define a project structure with a specific file operation using a nested dictionary.

```python
from pyscaffold.operations import no_overwrite
struct: Structure = {
    'namespace': {
        'module.py': ('print("Hello World!")', no_overwrite())
    }
}
```

--------------------------------

### Install PyScaffold using Pipx

Source: https://pyscaffold.org/en/stable/install.html

Install PyScaffold system-wide using pipx, making the 'putup' command available independently of the Python environment. This is ideal for managing multiple Python versions and environments.

```bash
pipx install pyscaffold

```

--------------------------------

### GET /info/git/status

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/info.html

Checks the status of the Git environment, including installation, configuration, and workspace cleanliness.

```APIDOC
## GET /info/git/status

### Description
Provides methods to verify if Git is installed, configured, and if a specific workspace is clean.

### Method
GET

### Parameters
#### Query Parameters
- **path** (string) - Required for workspace check - The path to the git repository.

### Response
#### Success Response (200)
- **is_installed** (boolean) - True if git is installed.
- **is_configured** (boolean) - True if user.name and user.email are set.
- **is_clean** (boolean) - True if the workspace has no uncommitted changes.
```

--------------------------------

### Example of using a custom configuration file with putup

Source: https://pyscaffold.org/en/stable/usage.html

This command demonstrates how to create a new project 'myproj' using PyScaffold, leveraging a pre-defined custom configuration file. This is equivalent to specifying all options directly on the command line.

```bash
$ putup myproj

```

--------------------------------

### Activate Conda Environment

Source: https://pyscaffold.org/en/stable/_sources/dependencies.rst.txt

Activate your newly created Conda environment to start using its installed packages. Replace 'my_conda_env' with your environment's name.

```bash
conda activate my_conda_env
```

--------------------------------

### Project configuration using setup.cfg

Source: https://pyscaffold.org/en/stable/usage.html

This is an example of a setup.cfg file used for configuring Python projects managed by setuptools and PyScaffold. It includes metadata, options, and testing configurations.

```ini
# Docs on setup.cfg:
# http://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files

[metadata]
name = my_project
description = A test project that was set up with PyScaffold
author = Florian Wilhelm
author_email = Florian.Wilhelm@blue-yonder.com
license = MIT
url = https://...
long_description = file: README.rst
platforms = any
classifiers =
    Development Status :: 5 - Production/Stable
    Topic :: Utilities
    Programming Language :: Python
    Programming Language :: Python :: 3
    Environment :: Console
    Intended Audience :: Developers
    License :: OSI Approved :: MIT License
    Operating System :: POSIX :: Linux
    Operating System :: Unix
    Operating System :: MacOS
    Operating System :: Microsoft :: Windows

[options]
zip_safe = False
packages = find_namespace:
python_requires = >=3.6
include_package_data = True
package_dir =
    =src
# Add here dependencies of your project (semicolon/line-separated)
install_requires =
    pandas
    scikit-learn

[options.packages.find]
where = src
exclude =
    tests

[options.extras_require]
# Add here additional requirements for extra features, like:
# pdf = ReportLab>=1.2; RXP
# rest = docutils>=0.3; pack ==1.1, ==1.3
all = django; cookiecutter
# Add here test requirements (semicolon/line-separated)
testing =
    pytest
    pytest-cov

[options.entry_points]
# Add here console scripts like:
# console_scripts =
#     script_name = ${package}.module:function
# For example:
# console_scripts =
#     fibonacci = ${package}.skeleton:run
# And any other entry points, for example:
# pyscaffold.cli =
#     awesome = pyscaffoldext.awesome.extension:AwesomeExtension

[tool:pytest]
# Options for py.test:
# Specify command line options as you would do when invoking py.test directly.
# e.g. --cov-report html (or xml) for html/xml output or --junitxml junit.xml
# in order to write a coverage file that can be read by Jenkins.
addopts =
    --cov my_project --cov-report term-missing
    --verbose
norecursedirs =
    dist
    build
    .tox
testpaths = tests
markers =
    slow: mark tests as slow (deselect with '-m "not slow"')

[bdist_wheel]
universal = 1

[devpi:upload]

```

--------------------------------

### Activate Pre-commit Extension

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/pre_commit.html

Activates the pre-commit extension by registering necessary actions. It ensures that files are added, the pre-commit executable is found, and the hooks are installed before the project setup is reported as done.

```python
def activate(self, actions: List[Action]) -> List[Action]:
    """Activate extension

    Args:
        actions (list): list of actions to perform

    Returns:
        list: updated list of actions
    """
    actions = self.register(actions, add_files, after="define_structure")
    actions = self.register(actions, find_executable, after="define_structure")
    return self.register(actions, install, before="report_done")
```

--------------------------------

### Initialize project with license

Source: https://pyscaffold.org/en/stable/_sources/features.rst.txt

Create a new project with a specific open-source license using the SPDX identifier.

```bash
putup --license MPL-2.0 my_project
```

--------------------------------

### pyscaffold.templates.setup_cfg

Source: https://pyscaffold.org/en/stable/api/pyscaffold.templates.html

Generates the content for the setup.cfg file based on provided options.

```APIDOC
## setup_cfg

### Description
Template of `setup.cfg`

### Method
(Not specified, likely a Python function call)

### Endpoint
(Not applicable, this is a Python function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **opts** (dict) - Required - mapping parameters as dictionary

### Request Example
```python
from pyscaffold.templates import setup_cfg

# Example usage (assuming opts is a dictionary)
# setup_cfg_content = setup_cfg(opts)
```

### Response
- **file content** (str) - The content of the `setup.cfg` file.

### Response Example
(Example not provided, but would be a string representing file content)

```

--------------------------------

### List Extensions from Entry Points

Source: https://pyscaffold.org/en/stable/api/pyscaffold.extensions.html

Produces a list of extension objects from setuptools entry points, with optional filtering.

```python
pyscaffold.extensions.list_from_entry_points(group='pyscaffold.cli', filtering=<function <lambda>>)
```

--------------------------------

### Install PyScaffold Extension

Source: https://pyscaffold.org/en/stable/_sources/features.rst.txt

Install any PyScaffold extension using pip with the format `pip install pyscaffoldext-NAME`.

```bash
pip install pyscaffoldext-NAME
```

--------------------------------

### Install PyScaffold using pip

Source: https://pyscaffold.org/en/stable/_sources/install.rst.txt

Use this command to install the latest stable version of PyScaffold. Pip automatically handles requirement installations.

```bash
pip install --upgrade pyscaffold
```

--------------------------------

### Add entry points to setup.cfg

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/update.html

Adds the [options.entry_points] section to the project's setup.cfg file if it does not already exist.

```python
@_change_setupcfg
def add_entrypoints(setupcfg: ConfigUpdater, opts: ScaffoldOpts):
    """Add [options.entry_points] to setup.cfg"""
    new_section_name = "options.entry_points"
    if new_section_name in setupcfg:
        return setupcfg, opts

    cfg = ConfigUpdater().read_string(templates.setup_cfg(opts))
    new_section = cfg[new_section_name].detach()

    add_after_sect = "options.extras_require"
    if add_after_sect not in setupcfg:
        # user removed it for some reason, default to metadata
        add_after_sect = "metadata"

    setupcfg[add_after_sect].add_after.section(new_section).space()

    return setupcfg, opts
```

--------------------------------

### Handle Missing Virtual Environment Installers

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/venv.html

Custom exception class to indicate that neither `virtualenv` nor `venv` are installed. Provides guidance on how to install them.

```python
class NotInstalled(ImportError):
    """Neither virtualenv or venv are installed in the computer. Please check the
    following alternatives:

    - ``virtualenv`` can be installed via pip
    - ``venv`` is supposed to installed by default with Python3, however some OS or
      distributions (such as Ubuntu) break the standard library in a series of packages
      that need to be manually installed via OS package manager.
      You can try to search for a ``python-venv``, ``python3-venv`` or similar in the
      official repositories.
    """

    def __init__(self, msg: Optional[str] = None):
        super().__init__(msg or self.__doc__)
```

--------------------------------

### Create a project with specific license and description

Source: https://pyscaffold.org/en/stable/_sources/usage.rst.txt

Create a project with a custom license, description, and homepage URL. This command allows for detailed initial project configuration.

```bash
putup skynet -l GPL-3.0-only -d "Finally, the ultimate AI!" -u https://sky.net
```

--------------------------------

### Install Development Version of PyScaffold using pip

Source: https://pyscaffold.org/en/stable/_sources/install.rst.txt

Install the most recent development version of PyScaffold with this command. Pip automatically handles requirement installations.

```bash
pip install --pre --upgrade pyscaffold
```

--------------------------------

### Initialize namespace package

Source: https://pyscaffold.org/en/stable/_sources/features.rst.txt

Create a project with a specific namespace using the putup command.

```bash
putup my_project --package my_package --namespace com.my_domain
```

--------------------------------

### Create a project with tox and Cirrus CI configuration

Source: https://pyscaffold.org/en/stable/usage.html

Set up a project with files for tox testing and Cirrus CI integration.

```bash
putup thoroughly_tested --cirrus
```

--------------------------------

### Venv Package Installation Action

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/venv.html

Describes the action for installing packages into the created virtual environment.

```APIDOC
## Install Packages into Venv

### Description
Installs a list of specified packages into the newly created virtual environment using pip.

### Method
`install_packages`

### Endpoint
N/A (Internal action)

### Parameters
#### Request Body
- **venv_install** (List[str]) - Required - A list of packages to install.
- **pretend** (bool) - Optional - If true, simulates the action without making changes.
- **project_path** (Path) - Required - The root path of the project.

### Request Example
```json
{
  "venv_install": ["requests", "pytest"],
  "project_path": "/path/to/your/project"
}
```

### Response
#### Success Response (200)
- **struct** (Structure) - The project structure object.
- **opts** (ScaffoldOpts) - The options object.

#### Response Example
```json
{
  "struct": { ... },
  "opts": { ... }
}
```

### Error Handling
- **NotInstalled** - Raised if pip cannot be found inside the venv.
```

--------------------------------

### Generate setup.cfg Content

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/templates.html

Generates the content for a setup.cfg file using a template. It handles single-line and multi-line descriptions, installs requirements, and adds PyScaffold-specific metadata.

```python
def setup_cfg(opts: ScaffoldOpts) -> str:
    """Template of setup.cfg

    Args:
        opts: mapping parameters as dictionary

    Returns:
        str: file content as string
    """

    template = get_template("setup_cfg")

    # template needs single-line `description`,
    # thus we pass only the first line of a multi-line description...
    desc = opts.get("description", "").splitlines() or [""]
    cfg_str = template.substitute({**opts, "description": desc[0]})

    updater = ConfigUpdater()
    updater.read_string(cfg_str)

    # ... and finally the multi-line string for the full description.
    if desc[0] != opts.get("description", ""):
        updater["metadata"]["description"].set_values(desc)

    requirements = deps.add(deps.RUNTIME, opts.get("requirements", []))
    updater["options"]["install_requires"].set_values(requirements)

    # fill [pyscaffold] section used for later updates
    add_pyscaffold(updater, opts)
    pyscaffold = updater["pyscaffold"]
    pyscaffold["version"].add_after.option("package", opts["package"])

    return str(updater)
```

--------------------------------

### Configure extension entry points

Source: https://pyscaffold.org/en/stable/_sources/extensions.rst.txt

Define the entry point in setup.cfg to register the extension class with the PyScaffold CLI.

```ini
[options.entry_points]
pyscaffold.cli =
    awesome_files = pyscaffoldext.${EXT_NAME}.extension:AwesomeFiles
```

--------------------------------

### pyscaffold.info.read_setupcfg

Source: https://pyscaffold.org/en/stable/api/pyscaffold.html

Reads a configuration file in setup.cfg format.

```APIDOC
## pyscaffold.info.read_setupcfg

### Description
Reads-in a configuration file that follows a setup.cfg format. Useful for retrieving stored information.

### Parameters
#### Query Parameters
- **path** (string) - Required - path where to find the config file
- **filename** (string) - Optional - if path is a directory, name will be considered a file relative to path (default: setup.cfg)

### Response
- **Object** (object) - Object that can be used to read/edit configuration parameters.
```

--------------------------------

### Equivalent putup command with explicit options

Source: https://pyscaffold.org/en/stable/usage.html

This command explicitly lists all the options that would be applied when using the custom configuration file from the previous example. It shows the direct mapping between the config file and CLI arguments.

```bash
$ putup --license MPL-2.0 --cirrus --pre-commit myproj

```

--------------------------------

### setup_cfg

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/templates.html

Generates the content for a setup.cfg file based on provided scaffold options.

```APIDOC
## setup_cfg

### Description
Generates a string representation of a setup.cfg file using PyScaffold templates and configuration options.

### Parameters
#### Arguments
- **opts** (ScaffoldOpts) - Required - Dictionary containing project configuration parameters.

### Response
- **str** - The formatted setup.cfg file content.
```

--------------------------------

### Install packages into venv

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/venv.html

Installs specified packages into the created virtual environment using pip. Handles deduplication and provides logging.

```python
def install_packages(struct: Structure, opts: ScaffoldOpts) -> ActionParams:
    """Install the specified packages inside the created venv."""

    packages = opts.get("venv_install")
    if not packages:
        return struct, opts

    pretend = opts.get("pretend")
    venv_path = get_path(opts)

    if not pretend:
        pip = get_command("pip", venv_path, include_path=False)
        if not pip:
            raise NotInstalled(f"pip cannot be found inside {venv_path}")
        pip("install", "-U", *deps.deduplicate(packages))

    logger.report("run", f"pip install -U {' '.join(packages)} [{venv_path}]")
    return struct, opts
```

--------------------------------

### Initialize and Sync Project with pip-tools

Source: https://pyscaffold.org/en/stable/_sources/dependencies.rst.txt

Workflow for setting up a new PyScaffold project with pip-tools, managing dependencies, and syncing the environment.

```bash
$ putup myproj --venv --venv-install pip-tools setuptools_scm && cd myproj
$ source .venv/bin/activate
# ... edit setup.cfg to add dependencies ...
$ echo '-e file:.' > requirements.in
$ echo -e 'tox\nsphinx\nptpython' >> requirements.in  # etc
$ pip-compile
$ pip-sync
$ tox
# ... do some debugging/live experimentation running Python in the terminal
$ ptpython
$ git add *requirements.{in,txt}
```

--------------------------------

### Option Processing and CLI Example Generation

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/interactive.html

Functions for processing PyScaffold options, generating CLI examples, and formatting text for output.

```APIDOC
## expand_computed_opts

### Description
Pre-process the given PyScaffold options and add default/computed values (including the ones derived from ``setup.cfg`` in case of ``--update`` or PyScaffold's own configuration file in the user's home directory.

### Method
N/A (Internal function)

### Endpoint
N/A

## wrap

### Description
Wrap text to fit lines with a maximum number of characters.

### Method
N/A (Internal function)

### Endpoint
N/A

## comment

### Description
Comment each line of the given text (optionally indenting it).

### Method
N/A (Internal function)

### Endpoint
N/A

## join_block

### Description
Join blocks of text using ``sep``, but ignoring the empty ones.

### Method
N/A (Internal function)

### Endpoint
N/A

## long_option

### Description
Get the long option corresponding to the given :obj:`argparse.Action`.

### Method
N/A (Internal function)

### Endpoint
N/A

## alternative_flags

### Description
Get the alternative flags (i.e. not the long one) of a :obj:`argparse.Action`.

### Method
N/A (Internal function)

### Endpoint
N/A

## has_active_extension

### Description
Returns :obj:`True` if the given :obj:`argparse.Action` corresponds to an extension that was previously activated via CLI.

### Method
N/A (Internal function)

### Endpoint
N/A

## example_no_value

### Description
Generate a CLI example of option usage for a :obj:`argparse.Action` that do not expect arguments (``nargs = 0``).

See :obj:`example`.

### Method
N/A (Internal function)

### Endpoint
N/A

## example_with_value

### Description
Generate a CLI example of option usage for a :obj:`argparse.Action` that expects one or more arguments (``nargs`` is ``?``, ``*``, ``+`` or ``N`` > 0).

See :obj:`example`.

### Method
N/A (Internal function)

### Endpoint
N/A

## example

### Description
Generate a CLI example of option usage for the given :obj:`argparse.Action`. The ``opts`` argument corresponds to options already processed by PyScaffold, and interferes on the generated text (e.g., when the corresponding option is already processed, the example will be adjusted accordingly; when the corresponding option is not present, the example might be commented out; ...).

This function will comment options that are marked in the ``"comment"`` :obj:`configuration <CONFIG>`.

### Method
N/A (Internal function)

### Endpoint
N/A

## example_with_help

### Description
Generate a CLI example of option usage for the given :obj:`argparse.Action` that includes a comment text block explaining its meaning (basically the same text displayed when using ``--help``).

See :obj:`example`.

### Method
N/A (Internal function)

### Endpoint
N/A
```

--------------------------------

### Get Cirrus CI Descriptor Template

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/cirrus.html

Retrieves the content of the Cirrus CI template file. This function is used internally by the extension to get the default configuration.

```python
def cirrus_descriptor(_opts: ScaffoldOpts) -> str:
    """Returns the rendered template"""
    return get_template(TEMPLATE_FILE).template  # no substitutions required
```

--------------------------------

### Add dependencies to setup.cfg

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/update.html

Updates the install_requires list in setup.cfg to include necessary runtime dependencies.

```python
@_change_setupcfg
def add_dependencies(setupcfg: ConfigUpdater, opts: ScaffoldOpts):
    """Add dependencies"""
    # TODO: Revise the need for `deps.RUNTIME` once `python_requires = >= 3.8`
    options = setupcfg["options"]
    if "install_requires" in options:
        install_requires = options.get("install_requires", Object(value=""))
        runtime_deps = deps.split(cast(str, install_requires.value))
        runtime_deps = deps.add(deps.RUNTIME, runtime_deps)
        options["install_requires"].set_values(runtime_deps)
    else:
        options.set("install_requires")
        options["install_requires"].set_values(deps.RUNTIME)

    return setupcfg, opts
```

--------------------------------

### Install project in editable mode

Source: https://pyscaffold.org/en/stable/_sources/usage.rst.txt

Installs the project in editable mode, making it available for import like any other Python module. Ensure your package manager and tooling are up-to-date.

```bash
pip install -e .
```

--------------------------------

### Install PyScaffold using conda

Source: https://pyscaffold.org/en/stable/_sources/install.rst.txt

Install PyScaffold from the conda-forge channel. This method is suitable for users who rely on conda for package management, especially in data science environments.

```bash
conda install -c conda-forge pyscaffold
```

--------------------------------

### Create Virtual Environment with virtualenv

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions/venv.html

Use this function to create a virtual environment using the `virtualenv` package. It logs a warning before installation and reports the creation. Requires `virtualenv` to be installed.

```python
def create_with_virtualenv(path: Path, pretend=False):
    import virtualenv

    args = [str(path)]

    if pretend:
        virtualenv.session_via_cli(args)
    else:
        logger.warning("\nInstalling virtual environment, it might take a while...\n")
        virtualenv.cli_run(args)

    logger.report("virtualenv", path)
```

--------------------------------

### Generate setup.cfg content

Source: https://pyscaffold.org/en/stable/api/pyscaffold.templates.html

Generates the content for a setup.cfg file based on provided options.

```python
from pyscaffold.templates import setup_cfg

# Example usage (opts would be a dictionary of parameters)
# setup_cfg_content = setup_cfg(opts)
```

--------------------------------

### Preview Documentation via Web Server

Source: https://pyscaffold.org/en/stable/contributing.html

Serves the compiled HTML documentation on a local web server for browser preview.

```bash
python3 -m http.server --directory 'docs/_build/html'
```

--------------------------------

### pyscaffold.info.check_git

Source: https://pyscaffold.org/en/stable/api/pyscaffold.html

Checks for git installation and configuration status.

```APIDOC
## pyscaffold.info.check_git

### Description
Checks for git and raises appropriate exception if not available or configured.

### Errors
- **GitNotInstalled** - when git command is not available
- **GitNotConfigured** - when git does not know user information
```

--------------------------------

### Initialize PyScaffold structure

Source: https://pyscaffold.org/en/stable/_sources/migration.rst.txt

Deploys the new project structure into an existing repository.

```bash
putup my_project --force --no-skeleton -p my_package
```

--------------------------------

### CLI command equivalence

Source: https://pyscaffold.org/en/stable/_sources/usage.rst.txt

Demonstrates how global configuration files affect the execution of the putup command.

```bash
$ putup myproj
```

```bash
$ putup --license MPL-2.0 --cirrus --pre-commit myproj
```

--------------------------------

### pyscaffold.extensions.pre_commit

Source: https://pyscaffold.org/en/stable/api/pyscaffold.extensions.html

Functions for managing Yelp pre-commit configuration and installation.

```APIDOC
## pyscaffold.extensions.pre_commit.activate

### Description
Activate the pre-commit extension.

### Parameters
#### Request Body
- **actions** (list) - Required - List of actions to perform.

### Response
- **Returns** (list) - Updated list of actions.
```

--------------------------------

### Configure setup.cfg for src layout

Source: https://pyscaffold.org/en/stable/_sources/faq.rst.txt

When using a src layout with setuptools, configure setup.cfg to correctly find and include namespace packages. This setup is essential for implicit namespace packages.

```ini
[options]
# ...
packages = find_namespace:
package_dir =
    =src
# ...

[options.packages.find]
where = src
```

--------------------------------

### GET /get_curr_version

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/info.html

Retrieves the PyScaffold version that generated the project.

```APIDOC
## GET /get_curr_version

### Description
Retrieves the PyScaffold version that put up the scaffold.

### Method
GET

### Endpoint
/get_curr_version

### Parameters
#### Query Parameters
- **project_path** (PathLike) - Required - Path to the project.

### Response
#### Success Response (200)
- **Version** (Object) - Version specifier.
```

--------------------------------

### Create a basic project

Source: https://pyscaffold.org/en/stable/usage.html

Use this command to create a new project directory with a Python package of the same name and the MIT license.

```bash
putup my_little_project
```

--------------------------------

### Initialize Colorama

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/termui.html

Attempts to initialize the colorama library if it is installed in the environment.

```python
def init_colorama():
    """Initialize colorama if it is available.

    Returns:
        bool: result of check
    """
    try:
        import colorama  # noqa

        colorama.init()
        return True
    except ImportError:
        return False
```

--------------------------------

### GET /list_actions

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/cli.html

Lists the planned actions for a project without executing them.

```APIDOC
## GET /list_actions

### Description
Displays the sequence of actions that would be performed based on the provided extensions and options.

### Parameters
#### Request Body
- **opts** (dict) - Required - Dictionary containing project configuration and extensions.

### Response
#### Success Response (200)
- **actions** (list) - A printed list of action IDs.
```

--------------------------------

### GET /read_pyproject

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/info.html

Reads a configuration file in pyproject.toml format from a specified path.

```APIDOC
## GET /read_pyproject

### Description
Reads-in a configuration file that follows a pyproject.toml format.

### Method
GET

### Endpoint
/read_pyproject

### Parameters
#### Query Parameters
- **path** (PathLike) - Required - Path where to find the config file.
- **filename** (str) - Optional - Name of the file if path is a directory (default: pyproject.toml).

### Response
#### Success Response (200)
- **TOMLMapping** (Object) - Object that can be used to read/edit configuration parameters.
```

--------------------------------

### Entry Point Iteration

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/extensions.html

Function to discover and iterate over extensions registered via setuptools entry points.

```APIDOC
## Function `iterate_entry_points(group=ENTRYPOINT_GROUP)`

### Description
Produces a generator yielding an `EntryPoint` object for each extension registered via `setuptools` entry point mechanism.

### Parameters
- **group** (str) - The entry point group to iterate over. Defaults to `ENTRYPOINT_GROUP`.

### Returns
- An iterable of `EntryPoint` objects.
```

--------------------------------

### Add Extension Arguments

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/cli.html

Dynamically loads and registers arguments from installed PyScaffold extensions.

```python
def add_extension_args(parser: argparse.ArgumentParser):
    """Add options and arguments defined by extensions to the CLI parser."""
    # load and instantiate extensions
    cli_extensions = list_all_extensions()

    for extension in cli_extensions:
        extension.augment_cli(parser)
```

--------------------------------

### Get Function Identifier

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/identification.html

Calculates a string identifier for a function in the format module:name.

```python
def get_id(function: Callable) -> str:
    """Given a function, calculate its identifier.

    A identifier is a string in the format ``<module name>:<function name>``,
    similarly to the convention used for setuptools entry points.

    Note:
        This function does not return a Python 3 ``__qualname__`` equivalent.
        If the function is nested inside another function or class, the parent
        name is ignored.

    Args:
        function (callable): function object
    """
    return f"{function.__module__}:{function.__name__}"
```

--------------------------------

### Compile Documentation with Tox

Source: https://pyscaffold.org/en/stable/contributing.html

Use this command to build the project documentation locally.

```bash
tox -e docs
```

--------------------------------

### Validate Git Configuration

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/info.html

Utilities to verify Git installation, configuration status, and workspace cleanliness.

```python
def is_git_installed() -> bool:
    """Check if git is installed"""
    logger.report("check", "is git installed...")
    try:
        shell.git("--version")
    except ShellCommandException:
        return False
    return True
```

```python
def is_git_configured() -> bool:
    """Check if user.name and user.email is set globally in git

    Check first git environment variables, then config settings.
    This will also return false if git is not available at all.

    Returns:
        True if it is set globally, False otherwise
    """
    logger.report("check", "is git configured...")
    if os.getenv(GitEnv.author_name.value) and os.getenv(GitEnv.author_email.value):
        return True
    else:
        try:
            for attr in ("name", "email"):
                shell.git("config", "--get", f"user.{attr}")
        except ShellCommandException:
            return False
        else:
            return True
```

```python
def check_git():
    """Checks for git and raises appropriate exception if not

    Raises:
       :class:`~.GitNotInstalled`: when git command is not available
       :class:`~.GitNotConfigured`: when git does not know user information
    """
    if not is_git_installed():
        raise GitNotInstalled
    if not is_git_configured():
        raise GitNotConfigured
```

```python
def is_git_workspace_clean(path: PathLike) -> bool:
    """Checks if git workspace is clean

    Args:
        path: path to git repository

     Raises:
        :class:`~.GitNotInstalled`: when git command is not available
        :class:`~.GitNotConfigured`: when git does not know user information
    """
    logger.report("check", "is workspace of git clean...")
    check_git()
    try:
        with chdir(path):
            shell.git("diff-index", "--quiet", "HEAD", "--")
    except ShellCommandException:
        return False
    return True
```

--------------------------------

### Update setup.cfg configuration

Source: https://pyscaffold.org/en/stable/_modules/pyscaffold/update.html

Ensures the [options] section exists and updates the [PyScaffold] section within setup.cfg.

```python
@_change_setupcfg
def update_setup_cfg(setupcfg: ConfigUpdater, opts: ScaffoldOpts):
    """Update `pyscaffold` in setupcfg and ensure some values are there as expected"""
    if "options" not in setupcfg:
        template = templates.setup_cfg(opts)
        new_section = ConfigUpdater().read_string(template)["options"]
        setupcfg["metadata"].add_after.section(new_section.detach())

    # Add "PyScaffold" section if missing and update saved extensions
    setupcfg = templates.add_pyscaffold(setupcfg, opts)
    return setupcfg, opts
```

--------------------------------

### Register Custom Action

Source: https://pyscaffold.org/en/stable/api/pyscaffold.html

Example of a minimal action function that returns the structure and options unchanged.

```python
def do_nothing(struct, opts):
    return (struct, opts)
```
Tokens:
Raw