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. See merge.
  • 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 if None.
  • 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 use pathlib.PurePath instead.

pyscaffold.api.helpers.logger = <ReportLogger pyscaffold.log (WARNING)>

Logger wrapper, that provides methods like report. See ReportLogger.

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 (see FileOp). 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 content print("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. See merge.
  • 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 no update_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 use pathlib.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 or after 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. See merge.
  • 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 use pathlib.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.

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 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
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 is True, PyScaffold will consider that some files can be updated (usually the packaging boilerplate), but will keep others intact. When the pretend flag is True, 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:

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