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)
- 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.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 appendsself.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 ofsetup.cfg
. Useful for updates. Set toFalse
if the extension should not be re-invoked on updates.
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)
- 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
- 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 originalsys.argv
.
Extension classes (or instances) can also provide configurations by defining a
interactive
attribute assigned to a similardict
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
. Theopts
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 theinteractive
attribute of each extension).The
kind
argument can assume the same values as theCONFIG
keys.This function is cached to improve performance. Call
get_config.__wrapped__
to bypass the cache (orget_config.cache_clear
, seefunctools.lru_cache
).
- pyscaffold.extensions.interactive.has_active_extension(action, opts)[source]#
Returns
True
if the givenargparse.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.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:
- 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
- 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_skeleton module#
Extension that omits the creation of file skeleton.py
pyscaffold.extensions.no_tox module#
Extension that removes configuration files for the Tox test automation tool.
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
- 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.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 pipvenv
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 apython-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’svenv
(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.- persist = False#
When
True
PyScaffold will store the extension in the PyScaffold’s section ofsetup.cfg
. Useful for updates. Set toFalse
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.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.
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
andScaffoldOpts
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 appendsself.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 ofsetup.cfg
. Useful for updates. Set toFalse
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