pyscaffold.api package¶
Submodules¶
pyscaffold.api.helpers module¶
Useful functions for manipulating the action list and project structure.
-
pyscaffold.api.helpers.
NO_CREATE
= 1¶ Do not create the file during an update
-
pyscaffold.api.helpers.
NO_OVERWRITE
= 0¶ Do not overwrite an existing file during update (still created if not exists)
-
pyscaffold.api.helpers.
ensure
(struct, path, content=None, update_rule=None)[source]¶ Ensure a file exists in the representation of the project tree with the provided content. All the parent directories are automatically created.
- Parameters
struct (dict) – project representation as (possibly) nested
dict
. Seemerge
.path (os.PathLike) –
path-like string or object relative to the structure root. The following examples are equivalent:
from pathlib import PurePath 'docs/api/index.html' PurePath('docs', 'api', 'index.html')
Deprecated - Alternatively, a list with the parts of the path can be provided, ordered from the structure root to the file itself.
content (str) – file text contents,
None
by default. The old content is preserved ifNone
.update_rule – see
FileOp
,None
by default
- Returns
updated project tree representation
- Return type
dict
Note
Use an empty string as content to ensure a file is created empty.
Warning
Deprecation Notice - In the next major release, the usage of lists for the
path
argument will result in an error. Please usepathlib.PurePath
instead.
-
pyscaffold.api.helpers.
logger
= <ReportLogger pyscaffold.log (WARNING)>¶ Logger wrapper, that provides methods like
report
. SeeReportLogger
.
-
pyscaffold.api.helpers.
merge
(old, new)[source]¶ Merge two dict representations for the directory structure.
Basically a deep dictionary merge, except from the leaf update method.
- Parameters
old (dict) – directory descriptor that takes low precedence during the merge
new (dict) – directory descriptor that takes high precedence during the merge
The directory tree is represented as a (possibly nested) dictionary. The keys indicate the path where a file will be generated, while the value indicates the content. Additionally, tuple values are allowed in order to specify the rule that will be followed during an
update
operation (seeFileOp
). In this case, the first element is the file content and the second element is the update rule. For example, the dictionary:{'project': { 'namespace': { 'module.py': ('print("Hello World!")', helpers.NO_OVERWRITE)}}
represents a
project/namespace/module.py
file with contentprint("Hello World!")
, that will be created only if not present.- Returns
resulting merged directory representation
- Return type
dict
Note
Use an empty string as content to ensure a file is created empty. (
None
contents will not be created).
-
pyscaffold.api.helpers.
modify
(struct, path, modifier=<function _id_func>, update_rule=None)[source]¶ Modify the contents of a file in the representation of the project tree.
If the given path, does not exist the parent directories are automatically created.
- Parameters
struct (dict) – project representation as (possibly) nested
dict
. Seemerge
.path (os.PathLike) –
path-like string or object relative to the structure root. The following examples are equivalent:
from pathlib import PurePath 'docs/api/index.html' PurePath('docs', 'api', 'index.html')
Deprecated - Alternatively, a list with the parts of the path can be provided, ordered from the structure root to the file itself.
modifier (callable) –
function (or callable object) that receives the old content as argument and returns the new content. If no modifier is passed, the identity function will be used. Note that, if the file does not exist in
struct
,None
will be passed as argument. Example:modifier = lambda old: (old or '') + 'APPENDED CONTENT'! modifier = lambda old: 'PREPENDED CONTENT!' + (old or '')
update_rule – see
FileOp
,None
by default. Note that, if noupdate_rule
is passed, the previous one is kept.
- Returns
updated project tree representation
- Return type
dict
Note
Use an empty string as content to ensure a file is created empty (
None
contents will not be created).Warning
Deprecation Notice - In the next major release, the usage of lists for the
path
argument will result in an error. Please usepathlib.PurePath
instead.
-
pyscaffold.api.helpers.
register
(actions, action, before=None, after=None)[source]¶ Register a new action to be performed during scaffold.
- Parameters
actions (list) – previous action list.
action (callable) –
function with two arguments: the first one is a (nested) dict representing the file structure of the project and the second is a dict with scaffold options. This function MUST return a tuple with two elements similar to its arguments. Example:
def do_nothing(struct, opts): return (struct, opts)
**kwargs (dict) –
keyword arguments make it possible to choose a specific order when executing actions: when
before
orafter
keywords are provided, the argument value is used as a reference position for the new action. Example:helpers.register(actions, do_nothing, after='create_structure') # Look for the first action with a name # `create_structure` and inserts `do_nothing` after it. # If more than one registered action is named # `create_structure`, the first one is selected. helpers.register( actions, do_nothing, before='pyscaffold.structure:create_structure') # Similar to the previous example, but the probability # of name conflict is decreased by including the module # name.
When no keyword argument is provided, the default execution order specifies that the action will be performed after the project structure is defined, but before it is written to the disk. Example:
helpers.register(actions, do_nothing) # The action will take place after # `pyscaffold.structure:define_structure`
- Returns
modified action list.
- Return type
list
-
pyscaffold.api.helpers.
reject
(struct, path)[source]¶ Remove a file from the project tree representation if existent.
- Parameters
struct (dict) – project representation as (possibly) nested
dict
. Seemerge
.path (os.PathLike) –
path-like string or object relative to the structure root. The following examples are equivalent:
from pathlib import PurePath 'docs/api/index.html' PurePath('docs', 'api', 'index.html')
Deprecated - Alternatively, a list with the parts of the path can be provided, ordered from the structure root to the file itself.
- Returns
modified project tree representation
- Return type
dict
Warning
Deprecation Notice - In the next major release, the usage of lists for the
path
argument will result in an error. Please usepathlib.PurePath
instead.
-
pyscaffold.api.helpers.
unregister
(actions, reference)[source]¶ Prevent a specific action to be executed during scaffold.
- Parameters
actions (list) – previous action list.
reference (str) –
action identifier. Similarly to the keyword arguments of
register
it can assume two formats:the name of the function alone,
the name of the module followed by
:
and the name of the function
- Returns
modified action list.
- Return type
list
Module contents¶
Exposed API for accessing PyScaffold via Python.
-
class
pyscaffold.api.
Extension
(name)[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.
-
activate
(actions)[source]¶ Activates the extension by registering its functionality
- Parameters
actions (list) – list of action to perform
- Returns
updated list of actions
- Return type
list
-
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
¶
-
mutually_exclusive
= False¶
-
static
register
(*args, **kwargs)[source]¶ Shortcut for
helpers.register
-
static
unregister
(*args, **kwargs)[source]¶ Shortcut for
helpers.unregister
-
pyscaffold.api.
create_project
(opts=None, **kwargs)[source]¶ Create the project’s directory structure
- Parameters
opts (dict) – options of the project
**kwargs – extra options, passed as keyword arguments
- Returns
a tuple of struct and opts dictionary
- Return type
tuple
Valid options include:
- Naming
project (str)
package (str)
- Package Information
author (str)
email (str)
release_date (str)
year (str)
title (str)
description (str)
url (str)
classifiers (str)
requirements (list)
- PyScaffold Control
update (bool)
force (bool)
pretend (bool)
extensions (list)
Some of these options are equivalent to the command line options, others are used for creating the basic python package meta information, but the last tree can change the way PyScaffold behaves.
When the force flag is
True
, existing files will be overwritten. When the update flag isTrue
, PyScaffold will consider that some files can be updated (usually the packaging boilerplate), but will keep others intact. When the pretend flag isTrue
, the project will not be created/updated, but the expected outcome will be logged.Finally, the extensions list may contain any function that follows the extension API. Note that some PyScaffold features, such as travis, tox and pre-commit support, are implemented as built-in extensions. In order to use these features it is necessary to include the respective functions in the extension list. All built-in extensions are accessible via
pyscaffold.extensions
submodule.Note that extensions may define extra options. For example, built-in cookiecutter extension define a
cookiecutter
option that should be the address to the git repository used as template.
-
pyscaffold.api.
discover_actions
(extensions)[source]¶ Retrieve the action list.
This is done by concatenating the default list with the one generated after activating the extensions.
- Parameters
extensions (list) – list of functions responsible for activating the
extensions. –
- Returns
scaffold actions.
- Return type
list
-
pyscaffold.api.
get_default_options
(struct, opts)[source]¶ Compute all the options that can be automatically derived.
This function uses all the available information to generate sensible defaults. Several options that can be derived are computed when possible.
- Parameters
struct (dict) – project representation as (possibly) nested
dict
.opts (dict) – given options, see
create_project
for an extensive list.
- Returns
project representation and options with default values set
- Return type
dict, dict
- Raises
DirectoryDoesNotExist – when PyScaffold is told to update an nonexistent directory
GitNotInstalled – when git command is not available
GitNotConfigured – when git does not know user information
Note
This function uses git to determine some options, such as author name and email.
-
pyscaffold.api.
init_git
(struct, opts)[source]¶ Add revision control to the generated files.
- Parameters
struct (dict) – project representation as (possibly) nested
dict
.opts (dict) – given options, see
create_project
for an extensive list.
- Returns
updated project representation and options
- Return type
dict, dict
-
pyscaffold.api.
verify_options_consistency
(struct, opts)[source]¶ Perform some sanity checks about the given options.
- Parameters
struct (dict) – project representation as (possibly) nested
dict
.opts (dict) – given options, see
create_project
for an extensive list.
- Returns
updated project representation and options
- Return type
dict, dict
-
pyscaffold.api.
verify_project_dir
(struct, opts)[source]¶ Check if PyScaffold can materialize the project dir structure.
- Parameters
struct (dict) – project representation as (possibly) nested
dict
.opts (dict) – given options, see
create_project
for an extensive list.
- Returns
updated project representation and options
- Return type
dict, dict