pyscaffold.extensions package#

Submodules#

pyscaffold.extensions.cirrus module#

Extension that generates configuration for Cirrus CI.

class pyscaffold.extensions.cirrus.Cirrus(name=None)[source]#

Bases: Extension

Add configuration file for Cirrus CI (includes –pre-commit)

activate(actions)[source]#

Activate extension, see activate.

augment_cli(parser)[source]#

Augments the command-line interface parser. See augment_cli.

pyscaffold.extensions.cirrus.add_files(struct, opts)[source]#

Add .cirrus.yml to the file structure

Parameters:
  • struct – project representation as (possibly) nested dict.

  • opts – given options, see create_project for an extensive list.

Returns:

updated project representation and options

Return type:

struct, opts

pyscaffold.extensions.cirrus.cirrus_descriptor(_opts)[source]#

Returns the rendered template

pyscaffold.extensions.config module#

CLI options for using/saving preferences as PyScaffold config files.

class pyscaffold.extensions.config.Config(name=None)[source]#

Bases: Extension

Add a few useful options for creating/using PyScaffold config files.

activate(actions)[source]#

Activates the extension by registering its functionality

Parameters:

actions (List[Action]) – list of action to perform

Returns:

updated list of actions

Return type:

List[Action]

augment_cli(parser)[source]#

Augments the command-line interface parser.

A command line argument --FLAG where FLAG=``self.name`` is added which appends self.activate to the list of extensions. As help text the docstring of the extension class is used. In most cases this method does not need to be overwritten.

Parameters:

parser – current parser object

persist = False#

When True PyScaffold will store the extension in the PyScaffold’s section of setup.cfg. Useful for updates. Set to False if the extension should not be re-invoked on updates.

pyscaffold.extensions.config.save(struct, opts)[source]#

Save the given opts as preferences in a PyScaffold’s config file.

pyscaffold.extensions.github_actions module#

Extension that generates configuration for GitHub Actions.

class pyscaffold.extensions.github_actions.GithubActions(name=None)[source]#

Bases: Extension

Add configuration file for GitHub Actions (includes –pre-commit)

activate(actions)[source]#

Activate extension, see activate.

augment_cli(parser)[source]#

Augments the command-line interface parser. See augment_cli.

pyscaffold.extensions.github_actions.add_files(struct, opts)[source]#

Add .github/workflows/ci.yml to the file structure

Parameters:
  • struct – project representation as (possibly) nested dict.

  • opts – given options, see create_project for an extensive list.

Returns:

updated project representation and options

Return type:

struct, opts

pyscaffold.extensions.gitlab_ci module#

Extension that generates configuration and script files for GitLab CI.

class pyscaffold.extensions.gitlab_ci.GitLab(name=None)[source]#

Bases: Extension

Generate GitLab CI configuration files

activate(actions)[source]#

Activate extension, see activate.

augment_cli(parser)[source]#

Augments the command-line interface parser. See augment_cli.

pyscaffold.extensions.gitlab_ci.add_files(struct, opts)[source]#

Add .gitlab-ci.yml file to structure

Parameters:
  • struct – project representation as (possibly) nested dict.

  • opts – given options, see create_project for an extensive list.

Returns:

updated project representation and options

Return type:

struct, opts

pyscaffold.extensions.interactive module#

Similarly to git rebase -i this extension allows users to interactively choose which options apply to putup, by editing a file filled with examples.

See CONFIG for more details on how to tweak the text generated in the interactive mode.

New in version 4.0: “interactive mode” introduced as an experimental extension.

Warning

NOTE FOR CONTRIBUTORS: Due to the way argparse is written, it is not very easy to obtain information about which options and arguments a given parser is currently configured with. There are no public methods that allow inspection/reflection, and therefore in order to do so, one has to rely on a few non-public methods (according to Python’s convention, the ones starting with a _ symbol). Since argparse implementation is very stable and mature, these non-public method are very unlikely to change and, therefore, it is relatively safe to use these methods, however developers and maintainers have to be aware and pay attention to eventual breaking changes. The non-public functions are encapsulated in the functions get_actions and format_args in this file, in order to centralise the usage of non-public API.

pyscaffold.extensions.interactive.CONFIG = {'comment': ['--verbose', '--very-verbose'], 'ignore': ['--help', '--version']}#

Configuration for the options that are not associated with an extension class. This dict value consist of a set of metadata organised as follows:

  • Each value must be a list of “long” argparse option strings (e.g. “–help” instead of “-h”).

  • Each key implies on a different interpretation for the metadata:

    • "ignore": Options that should be simply ignored when creating examples

    • "comment": Options that should be commented when creating examples, even if they appear in the original sys.argv.

Extension classes (or instances) can also provide configurations by defining a interactive attribute assigned to a similar dict object.

class pyscaffold.extensions.interactive.Interactive(name=None)[source]#

Bases: Extension

Interactively choose and configure PyScaffold’s parameters

augment_cli(parser)[source]#

See augment_cli.

command(opts)[source]#

This method replace the regular call to cli.run_scaffold with an intermediate file to confirm the user’s choices in terms of arguments/options.

parser#
pyscaffold.extensions.interactive.all_examples(parser, actions, opts)[source]#

Generate a example of usage of the CLI options corresponding to the given actions including the help text.

This function will skip options that are marked in the "ignore" configuration.

See example_with_help.

pyscaffold.extensions.interactive.alternative_flags(action)[source]#

Get the alternative flags (i.e. not the long one) of a argparse.Action

pyscaffold.extensions.interactive.comment(text, comment_mark='#', indent_level=0)[source]#

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

pyscaffold.extensions.interactive.example(parser, action, opts)[source]#

Generate a CLI example of option usage for the given 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" configuration.

pyscaffold.extensions.interactive.example_no_value(parser, action, opts)[source]#

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

See example.

pyscaffold.extensions.interactive.example_with_help(parser, action, opts)[source]#

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

See example.

pyscaffold.extensions.interactive.example_with_value(parser, action, opts)[source]#

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

See example.

pyscaffold.extensions.interactive.expand_computed_opts(opts)[source]#

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.

pyscaffold.extensions.interactive.format_args(parser, action)[source]#

Produce an example to be used together with the flag of the given action.

Warning

This function uses non-public API from Python’s stdlib argparse.

pyscaffold.extensions.interactive.get_actions(parser)[source]#

List actions related to options that were configured to the given ArgumentParser.

Warning

This function uses non-public API from Python’s stdlib argparse.

pyscaffold.extensions.interactive.get_config(kind)[source]#

Get configurations that will be used for generating examples (from both CONFIG and the interactive attribute of each extension).

The kind argument can assume the same values as the CONFIG keys.

This function is cached to improve performance. Call get_config.__wrapped__ to bypass the cache (or get_config.cache_clear, see functools.lru_cache).

pyscaffold.extensions.interactive.has_active_extension(action, opts)[source]#

Returns True if the given argparse.Action corresponds to an extension that was previously activated via CLI.

pyscaffold.extensions.interactive.join_block(*parts, sep='\n')[source]#

Join blocks of text using sep, but ignoring the empty ones

pyscaffold.extensions.interactive.long_option(action)[source]#

Get the long option corresponding to the given argparse.Action

pyscaffold.extensions.interactive.split_args(text)[source]#

Split the text from the interactive example into arguments that can be passed directly to argparse, as if they were invoked directly from the CLI (this includes removing comments).

pyscaffold.extensions.interactive.wrap(text, width=70, **kwargs)[source]#

Wrap text to fit lines with a maximum number of characters

pyscaffold.extensions.namespace module#

Extension that adjust project file tree to include a namespace package.

This extension adds a namespace option to create_project and provides correct values for the options root_pkg and namespace_pkg to the following functions in the action list.

class pyscaffold.extensions.namespace.Namespace(name=None)[source]#

Bases: Extension

Add a namespace (container package) to the generated package.

activate(actions)[source]#

Register an action responsible for adding namespace to the package.

Parameters:

actions – list of actions to perform

Returns:

updated list of actions

Return type:

list

augment_cli(parser)[source]#

Add an option to parser that enables the namespace extension.

Parameters:

parser (argparse.ArgumentParser) – CLI parser object

pyscaffold.extensions.namespace.add_namespace(struct, opts)[source]#

Prepend the namespace to a given file structure

Parameters:
  • struct – directory structure as dictionary of dictionaries

  • opts – options of the project

Returns:

Directory structure as dictionary of dictionaries and input options

pyscaffold.extensions.namespace.enforce_namespace_options(struct, opts)[source]#

Make sure options reflect the namespace usage.

pyscaffold.extensions.namespace.move_old_package(struct, opts)[source]#

Move old package that may be eventually created without namespace

Parameters:
  • struct (dict) – directory structure as dictionary of dictionaries

  • opts (dict) – options of the project

Returns:

directory structure as dictionary of dictionaries and input options

Return type:

tuple(dict, dict)

pyscaffold.extensions.namespace.prepare_namespace(namespace_str)[source]#

Check the validity of namespace_str and split it up into a list

Parameters:

namespace_str – namespace, e.g. “com.blue_yonder”

Returns:

list of namespaces, e.g. [“com”, “com.blue_yonder”]

Raises:

InvalidIdentifier – raised if namespace is not valid

pyscaffold.extensions.no_pyproject module#

Extension that omits the creation of file pyproject.toml.

Since the isolated builds with PEP517/PEP518 are not completely backward compatible, this extension provides an escape hatch for people that want to maintain the legacy behaviour.

Warning

This extension is transitional and will be removed in future versions of PyScaffold. Once support for isolated builds stabilises, the Python community will likely move towards using them more exclusively.

class pyscaffold.extensions.no_pyproject.NoPyProject(name=None)[source]#

Bases: Extension

Do not include a pyproject.toml file in the project root, and thus avoid isolated builds as defined in PEP517/518 [not recommended]

activate(actions)[source]#

Activates the extension by registering its functionality

Parameters:

actions (List[Action]) – list of action to perform

Returns:

updated list of actions

Return type:

List[Action]

name = 'no_pyproject'#
pyscaffold.extensions.no_pyproject.ensure_option(struct, opts)[source]#

Make option available in non-CLI calls (used by other parts of PyScaffold)

pyscaffold.extensions.no_pyproject.remove_files(struct, opts)[source]#

pyscaffold.extensions.no_skeleton module#

Extension that omits the creation of file skeleton.py

class pyscaffold.extensions.no_skeleton.NoSkeleton(name=None)[source]#

Bases: Extension

Omit creation of skeleton.py and test_skeleton.py

activate(actions)[source]#

Activate extension, see activate.

pyscaffold.extensions.no_skeleton.remove_files(struct, opts)[source]#

Remove all skeleton files from structure

Parameters:
  • struct – project representation as (possibly) nested dict.

  • opts – given options, see create_project for an extensive list.

Returns:

Updated project representation and options

pyscaffold.extensions.no_tox module#

Extension that removes configuration files for the Tox test automation tool.

class pyscaffold.extensions.no_tox.NoTox(name=None)[source]#

Bases: Extension

Prevent a tox configuration file from being created

activate(actions)[source]#

Activate extension, see activate.

pyscaffold.extensions.no_tox.remove_files(struct, opts)[source]#

Remove .tox.ini file to structure

pyscaffold.extensions.pre_commit module#

Extension that generates configuration files for Yelp pre-commit.

class pyscaffold.extensions.pre_commit.PreCommit(name=None)[source]#

Bases: Extension

Generate pre-commit configuration file

activate(actions)[source]#

Activate extension

Parameters:

actions (list) – list of actions to perform

Returns:

updated list of actions

Return type:

list

pyscaffold.extensions.pre_commit.add_files(struct, opts)[source]#

Add .pre-commit-config.yaml file to structure

Since the default template uses isort, this function also provides an initial version of .isort.cfg that can be extended by the user (it contains some useful skips, e.g. tox and venv)

pyscaffold.extensions.pre_commit.add_instructions(opts, content, file_op)[source]#

Add pre-commit instructions to README

pyscaffold.extensions.pre_commit.find_executable(struct, opts)[source]#

Find the pre-commit executable that should run later in the next action… Or take advantage of the venv to install it…

pyscaffold.extensions.pre_commit.install(struct, opts)[source]#

Attempts to install pre-commit in the project

pyscaffold.extensions.venv module#

Create a virtual environment for the project

pyscaffold.extensions.venv.DEFAULT = '.venv'#

Default directory name for collocated virtual environment that will be created

exception pyscaffold.extensions.venv.NotInstalled(msg=None)[source]#

Bases: 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.

class pyscaffold.extensions.venv.Venv(name=None)[source]#

Bases: Extension

Create a virtual environment for the project (using virtualenv or stdlib’s venv). Default location: “{DEFAULT}”.

If virtualenv is available, it will be used, since it has some advantages over stdlib’s venv (such as being faster, see https://virtualenv.pypa.io/en/stable/).

Notice that even if part of Python’s stdlib, venv is not guaranteed to be installed, some OS/distributions (such as Ubuntu) require an explicit installation. If you have problems, try installing virtualenv with pip and run the command again.

activate(actions)[source]#

Activate extension, see activate.

augment_cli(parser)[source]#

Augments the command-line interface parser. See augment_cli.

persist = False#

When True PyScaffold will store the extension in the PyScaffold’s section of setup.cfg. Useful for updates. Set to False if the extension should not be re-invoked on updates.

pyscaffold.extensions.venv.create(path, pretend=False)[source]#

Create the virtual environment with the first technique available. (virtualenv is preferred because it is faster).

pyscaffold.extensions.venv.create_with_stdlib(path, pretend=False)[source]#
pyscaffold.extensions.venv.create_with_virtualenv(path, pretend=False)[source]#
pyscaffold.extensions.venv.get_path(opts, default='.venv')[source]#

Get the path to the venv that will be created.

pyscaffold.extensions.venv.install_packages(struct, opts)[source]#

Install the specified packages inside the created venv.

pyscaffold.extensions.venv.instruct_user(struct, opts)[source]#

Simply display a message reminding the user to activate the venv.

pyscaffold.extensions.venv.run(struct, opts)[source]#

Action that will create a virtualenv for the project

Module contents#

Built-in extensions for PyScaffold.

class pyscaffold.extensions.Extension(name=None)[source]#

Bases: object

Base class for PyScaffold’s extensions

Parameters:

name (str) – How the extension should be named. Default: name of class By default, this value is used to create the activation flag in PyScaffold cli.

See our docs on how to create extensions in: https://pyscaffold.org/en/latest/extensions.html

Also check actions, Structure and ScaffoldOpts for more details.

Note

Please name your class using a CamelCase version of the name you use in the setuptools entrypoint (alternatively you will need to overwrite the name property to match the entrypoint name).

activate(actions)[source]#

Activates the extension by registering its functionality

Parameters:

actions (List[Action]) – list of action to perform

Returns:

updated list of actions

Return type:

List[Action]

augment_cli(parser)[source]#

Augments the command-line interface parser.

A command line argument --FLAG where FLAG=``self.name`` is added which appends self.activate to the list of extensions. As help text the docstring of the extension class is used. In most cases this method does not need to be overwritten.

Parameters:

parser – current parser object

property flag#
property help_text#
property name#
persist = True#

When True PyScaffold will store the extension in the PyScaffold’s section of setup.cfg. Useful for updates. Set to False if the extension should not be re-invoked on updates.

static register(actions, action, before=None, after=None)#

Shortcut for pyscaffold.actions.register

static unregister(actions, reference)#

Shortcut for pyscaffold.actions.unregister

pyscaffold.extensions.NO_LONGER_NEEDED = {'pyproject', 'tox'}#

Extensions that are no longer needed and are now part of PyScaffold itself

pyscaffold.extensions.include(*extensions)[source]#

Create a custom argparse.Action that saves multiple extensions for activation.

Parameters:

*extensions – extension objects to be saved

pyscaffold.extensions.iterate_entry_points(group='pyscaffold.cli')[source]#

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

This method can be used in conjunction with load_from_entry_point to filter the extensions before actually loading them.

pyscaffold.extensions.list_from_entry_points(group='pyscaffold.cli', filtering=<function <lambda>>)[source]#

Produces a list of extension objects for each extension registered via setuptools entry point mechanism.

Parameters:
  • group – name of the setuptools’ entry_point group where extensions is being registered

  • filtering – function returning a boolean deciding if the entry point should be loaded and included (or not) in the final list. A True return means the extension should be included.

pyscaffold.extensions.load_from_entry_point(entry_point)[source]#

Carefully load the extension, raising a meaningful message in case of errors

pyscaffold.extensions.store_with(*extensions)[source]#

Create a custom argparse.Action that stores the value of the given option in addition to saving the extension for activation.

Parameters:

*extensions – extension objects to be saved for activation