pyscaffold package

Submodules

pyscaffold.cli module

Command-Line-Interface of PyScaffold

pyscaffold.cli.create_project(opts)[source]

Create the project’s directory structure

Parameters:opts (dict) – options of the project
pyscaffold.cli.get_default_opts(project_name, **aux_opts)[source]

Creates default options using auxiliary options as keyword argument

Use this function if you want to use PyScaffold from another application in order to generate an option dictionary that can than be passed to create_project.

Parameters:
  • project_name (str) – name of the project
  • **aux_opts – auxiliary options as keyword parameters
Returns:

options with default values set

Return type:

dict

pyscaffold.cli.main(args)[source]

PyScaffold is a tool for putting up the scaffold of a Python project.

pyscaffold.cli.make_sanity_checks(opts)[source]

Perform some sanity checks, e.g., if git is installed.

Parameters:opts (dict) – options of the project
pyscaffold.cli.parse_args(args)[source]

Parse command line parameters

Parameters:args ([str]) – command line parameters as list of strings
Returns:command line parameters
Return type:dict
pyscaffold.cli.run(*args, **kwargs)[source]

Entry point for setup.py

pyscaffold.info module

Provide general information about the system, user etc.

pyscaffold.info.email()[source]

Retrieve the user’s email

Returns:user’s email
Return type:str
pyscaffold.info.is_git_configured()[source]

Check if user.name and user.email is set globally in git

Returns:True if it is set globally, False otherwise
Return type:bool
pyscaffold.info.is_git_installed()[source]

Check if git is installed

Returns:True if git is installed, False otherwise
Return type:bool
pyscaffold.info.project(opts)[source]

Update user options with the options of an existing PyScaffold project

Params:
opts (dict): options of the project
Returns:options with updated values
Return type:dict
pyscaffold.info.username()[source]

Retrieve the user’s name

Returns:user’s name
Return type:str

pyscaffold.integration module

Integration part for hooking into distutils/setuptools

Rationale: The use_pyscaffold keyword is unknown to setuptools’ setup(...) command, therefore the entry_points are checked for a function to handle this keyword which is pyscaffold_keyword below. This is where we hook into setuptools and apply the magic of setuptools_scm and pbr.

pyscaffold.integration.build_cmd_docs()[source]

Return Sphinx’s BuildDoc if available otherwise a dummy command

Returns:command object
Return type:Command
pyscaffold.integration.deactivate_pbr_authors_changelog()[source]

Deactivate automatic generation of AUTHORS and ChangeLog file

This is an automatism of pbr and we rather keep track of our own AUTHORS.rst and CHANGES.rst files.

pyscaffold.integration.local_version2str(version)[source]

Create the local part of a PEP440 version string

Parameters:version (setuptools_scm.version.ScmVersion) – version object
Returns:local version
Return type:str
pyscaffold.integration.pyscaffold_keyword(dist, keyword, value)[source]

Handles the use_pyscaffold keyword of the setup(...) command

Parameters:
  • dist (setuptools.dist) – distribution object as
  • keyword (str) – keyword argument = ‘use_pyscaffold’
  • value – value of the keyword argument
pyscaffold.integration.version2str(version)[source]

Creates a PEP440 version string

Parameters:version (setuptools_scm.version.ScmVersion) – version object
Returns:version string
Return type:str

pyscaffold.pytest_runner module

This module provides a test runner for setup.py copied over from https://bitbucket.org/pytest-dev/pytest-runner/ in order to make some improvements.

This file is MIT licensed:

Copyright (c) 2011 Jason R. Coombs <jaraco@jaraco.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

class pyscaffold.pytest_runner.PyTest(dist, **kw)[source]

Bases: setuptools.command.test.test

finalize_options()[source]
initialize_options()[source]
static marker_passes(marker)[source]

Given an environment marker, return True if the marker is valid and matches this environment.

run()[source]

Override run to ensure requirements are available in this session (but don’t install them anywhere).

run_tests()[source]
user_options = [('extras', None, 'Install (all) setuptools extras when running tests'), ('index-url=', None, 'Specify an index url from which to retrieve dependencies'), ('allow-hosts=', None, 'Whitelist of comma-separated hosts to allow when retrieving dependencies'), ('addopts=', 'a', 'Additional options to be passed verbatim to the pytest runner')]

pyscaffold.repo module

Functionality for working with a git repository

pyscaffold.repo.add_tag(project, tag_name, message=None)[source]

Add an (annotated) tag to the git repository.

Parameters:
  • project (str) – path to the project
  • tag_name (str) – name of the tag
  • message (str) – optional tag message
pyscaffold.repo.get_git_root(default=None)[source]

Return the path to the top-level of the git repository or default.

Parameters:default (str) – if no git root is found, default is returned
Returns:top-level path or default
Return type:str
pyscaffold.repo.git_tree_add(struct, prefix='')[source]

Adds recursively a directory structure to git

Parameters:
  • struct (dict) – directory structure as dictionary of dictionaries
  • prefix (str) – prefix for the given directory structure
pyscaffold.repo.init_commit_repo(project, struct)[source]

Initialize a git repository

Parameters:
  • project (str) – path to the project
  • struct (dict) – directory structure as dictionary of dictionaries
pyscaffold.repo.is_git_repo(folder)[source]

Check if a folder is a git repository

Parameters:folder (str) – path

pyscaffold.shell module

Shell commands like git, django-admin.py etc.

class pyscaffold.shell.ShellCommand(command, shell=True, cwd=None)[source]

Bases: object

Shell command that can be called with flags like git(‘add’, ‘file’)

Parameters:
  • command (str) – command to handle
  • shell (bool) – run the command in the shell
  • cwd (str) – current working dir to run the command
pyscaffold.shell.called_process_error2exit_decorator(func)[source]

Decorator to convert given CalledProcessError to an exit message

This avoids displaying nasty stack traces to end-users

pyscaffold.shell.django_admin = <pyscaffold.shell.ShellCommand object>

Command for django-admin.py

pyscaffold.shell.get_git_cmd(**args)[source]

Retrieve the git shell command depending on the current platform

Parameters:**args – additional keyword arguments to ShellCommand
pyscaffold.shell.git = <pyscaffold.shell.ShellCommand object>

Command for git

pyscaffold.structure module

Functionality to generate and work with the directory structure of a project

class pyscaffold.structure.FileOp[source]

Bases: object

Namespace for file operations during an update:

  • NO_OVERWRITE: Do not overwrite an existing file during update
  • NO_CREATE: Do not create the file during an update
NO_CREATE = 1
NO_OVERWRITE = 0
pyscaffold.structure.add_namespace(opts, struct)[source]

Prepend the namespace to a given file structure

Parameters:
  • opts (dict) – options of the project
  • struct (dict) – directory structure as dictionary of dictionaries
Returns:

directory structure as dictionary of dictionaries

Return type:

dict

pyscaffold.structure.apply_update_rules(rules, struct, prefix=None)[source]

Apply update rules using FileOp to a directory structure

Parameters:
  • rules (dict) – directory structure as dictionary of dictionaries with FileOp keys. The structure will be modified.
  • struct (dict) – directory structure as dictionary of dictionaries
  • prefix (str) – prefix path for the structure
Returns:

directory structure with keys removed according to the rules

Return type:

dict

pyscaffold.structure.create_cookiecutter(opts)[source]

Create a cookie cutter template

Parameters:opts (dict) – options of the project
pyscaffold.structure.create_django_proj(opts)[source]

Creates a standard Django project with django-admin.py

Parameters:opts (dict) – options of the project
Raises:RuntimeError – raised if django-admin.py is not installed
pyscaffold.structure.create_structure(struct, prefix=None, update=False)[source]

Manifests a directory structure in the filesystem

Parameters:
  • struct (dict) – directory structure as dictionary of dictionaries
  • prefix (str) – prefix path for the structure
  • update (bool) – update an existing directory structure
Raises:

RuntimeError – raised if content type in struct is unknown

pyscaffold.structure.make_structure(opts)[source]

Creates the project structure as dictionary of dictionaries

Parameters:opts (dict) – options of the project
Returns:structure as dictionary of dictionaries
Return type:dict

pyscaffold.utils module

Miscellaneous utilities and tools

pyscaffold.utils.best_fit_license(txt)[source]

Finds proper license name for the license defined in txt

Parameters:txt (str) – license name
Returns:license name
Return type:str
pyscaffold.utils.chdir(*args, **kwds)[source]

Contextmanager to change into a directory

Parameters:path (str) – path to change current working directory to
pyscaffold.utils.check_setuptools_version()[source]

Checks that setuptools has all necessary capabilities for setuptools_scm

Raises:RuntimeError – raised if necessary capabilities are not met
pyscaffold.utils.exceptions2exit(exception_list)[source]

Decorator to convert given exceptions to exit messages

This avoids displaying nasty stack traces to end-users

Parameters:[Exception] (exception_list) – list of exceptions to convert
pyscaffold.utils.get_files(pattern)[source]

Retrieve all files in the current directory by a pattern.

Use ** as greedy wildcard and * as non-greedy wildcard.

Parameters:pattern (str) – pattern as used by distutils.filelist.Filelist
Returns:list of files
Return type:[str]
pyscaffold.utils.is_valid_identifier(string)[source]

Check if string is a valid package name

Parameters:string (str) – package name
Returns:True if string is valid package name else False
Return type:bool
pyscaffold.utils.levenshtein(s1, s2)[source]

Calculate the Levenshtein distance between two strings

Parameters:
  • s1 (str) – first string
  • s2 (str) – second string
Returns:

distance between s1 and s2

Return type:

int

pyscaffold.utils.list2str(lst, indent=0, brackets=True, quotes=True, sep=', ')[source]

Generate a Python syntax list string with an indention

Parameters:
  • lst ([str]) – list of strings
  • indent (int) – indention
  • brackets (bool) – surround the list expression by brackets
  • quotes (bool) – surround each item with quotes
  • sep (str) – separator for each item
Returns:

string representation of the list

Return type:

str

pyscaffold.utils.make_valid_identifier(string)[source]

Try to make a valid package name identifier from a string

Parameters:string (str) – invalid package name
Returns:valid package name as string or RuntimeError
Return type:str
Raises:RuntimeError – raised if identifier can not be converted
pyscaffold.utils.prepare_namespace(namespace_str)[source]

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

Parameters:namespace_str (str) – namespace, e.g. “com.blue_yonder”
Returns:list of namespaces, e.g. [“com”, “com.blue_yonder”]
Return type:[str]
Raises:RuntimeError – raised if namespace is not valid
pyscaffold.utils.utf8_decode(string)[source]

Decode a Python 2 str object to unicode for compatibility with Python 3

Parameters:string (str) – Python 2 str object or Python 3 str object
Returns:Python 2 unicode object or Python 3 str object
Return type:str
pyscaffold.utils.utf8_encode(string)[source]

Encode a Python 2 unicode object to str for compatibility with Python 3

Parameters:string (str) – Python 2 unicode object or Python 3 str object
Returns:Python 2 str object or Python 3 str object
Return type:str

Module contents