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: 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.- struct (dict) – project representation as (possibly) nested
-
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: 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: 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.- struct (dict) – project representation as (possibly) nested
-
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:
-
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: 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.- struct (dict) – project representation as (possibly) nested
Module contents¶
Exposed API for accessing PyScaffold via Python.
In addition to the functions and classes exposed in this module, please also
consider pyscaffold.templates.get_template
to be part of PyScaffold’s
public API.
-
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
-
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: 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:
-
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: Raises: DirectoryDoesNotExist
– when PyScaffold is told to update an nonexistent directoryGitNotInstalled
– when git command is not availableGitNotConfigured
– when git does not know user information
Note
This function uses git to determine some options, such as author name and email.
- struct (dict) – project representation as (possibly) nested
-
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: - struct (dict) – project representation as (possibly) nested
-
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: - struct (dict) – project representation as (possibly) nested
-
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: - struct (dict) – project representation as (possibly) nested