pyscaffold package

Submodules

pyscaffold.cli module

Command-Line-Interface of PyScaffold

pyscaffold.cli.create_project(opts)

Create the project’s directory structure

Parameters:opts – options as dictionary
pyscaffold.cli.get_default_opts(project_name, **aux_opts)

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 – name of the project
  • aux_opts – auxiliary options as keyword parameters
Returns:

options with default values set as dictionary

pyscaffold.cli.main(args)

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

pyscaffold.cli.make_sanity_checks(opts)

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

Parameters:opts – options as dictionary
pyscaffold.cli.parse_args(args)

Parse command line parameters

Parameters:args – command line parameters as list of strings
Returns:command line parameters as dictionary
pyscaffold.cli.run(*args, **kwargs)

Entry point for setup.py

pyscaffold.info module

Provide general information about the system, user etc.

pyscaffold.info.email()

Retrieve the user’s email

Returns:user’s email as string
pyscaffold.info.is_git_configured()

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

Returns:boolean
pyscaffold.info.is_git_installed()

Check if git is installed

Returns:boolean
pyscaffold.info.project(opts)

Update user options with the options of an existing PyScaffold project

Parameters:opts – options as dictionary
Returns:options with updated values as dictionary
pyscaffold.info.username()

Retrieve the user’s name

Returns:user’s name as string

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()

Return Sphinx’s BuildDoc if available otherwise a dummy command

Returns:command as Command
pyscaffold.integration.deactivate_pbr_authors_changelog()

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)

Create the local part of a PEP440 version string

Parameters:version – version object as setuptools_scm.version.ScmVersion
Returns:local version string
pyscaffold.integration.pyscaffold_keyword(dist, keyword, value)

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

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

Creates a PEP440 version string

Parameters:version – version object as setuptools_scm.version.ScmVersion
Returns:version string

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.

Follow the discussion under: https://bitbucket.org/pytest-dev/pytest-runner/issues/7/support-all-pytest-commands

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)

Bases: setuptools.command.test.test

finalize_options()
initialize_options()
static marker_passes(marker)

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

run()

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

run_tests()
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)

Add an (annotated) tag to the git repository.

Parameters:
  • project – path to the project as string
  • tag_name – name of the tag as string
  • message – optional tag message as string
pyscaffold.repo.get_git_root()

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

pyscaffold.repo.git_tree_add(struct, prefix='')

Adds recursively a directory structure to git

Parameters:
  • struct – directory structure as dictionary of dictionaries
  • prefix – prefix for the given directory structure as string
pyscaffold.repo.init_commit_repo(project, struct)

Initialize a git repository

Parameters:
  • project – path to the project as string
  • struct – directory structure as dictionary of dictionaries
pyscaffold.repo.is_git_repo(folder)

Check if a folder is a git repository

Parameters:folder – path as string

pyscaffold.shell module

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

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

Bases: object

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

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

Decorator to convert given CalledProcessError to an exit message

This avoids displaying nasty stack traces to end-users

pyscaffold.shell.get_git_cmd(**args)

Retrieve the git shell command depending on the current platform

All additional parameters are passed to ShellCommand

pyscaffold.structure module

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

class pyscaffold.structure.FileOp

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)

Prepend the namespace to a given file structure

Parameters:
  • opts – options as dictionary
  • struct – directory structure as dictionary of dictionaries
Returns:

directory structure as dictionary of dictionaries

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

Apply update rules using FileOp to a directory structure

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

directory structure with keys removed according to the rules

pyscaffold.structure.create_cookiecutter(opts)

Create a cookie cutter template

Parameters:opts – options as dictionary
pyscaffold.structure.create_django_proj(opts)

Creates a standard Django project with django-admin.py

Parameters:opts – options as dictionary
pyscaffold.structure.create_structure(struct, prefix=None, update=False)

Manifests a directory structure in the filesystem

Parameters:
  • struct – directory structure as dictionary of dictionaries
  • prefix – prefix path for the structure
  • update – update an existing directory structure as boolean
pyscaffold.structure.make_structure(opts)

Creates the project structure as dictionary of dictionaries

Parameters:opts – options as dictionary
Returns:structure as dictionary of dictionaries

pyscaffold.templates module

Templates for all files of a project’s scaffold

pyscaffold.templates.authors(opts)

Template of AUTHORS.rst

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.changes(opts)

Template of CHANGES.rst

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.conftest_py(opts)

Template of conftest.py

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.coveragerc(opts)

Template of .coveragerc

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.get_template(name)

Retrieve the template by name

Parameters:name – name of template
Returns:template as string.Template
pyscaffold.templates.gitignore(opts)

Template of .gitignore

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.gitignore_empty(opts)

Template of empty .gitignore

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.init(opts)

Template of __init__.py

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.license(opts)

Template of LICENSE.txt

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.namespace(opts)

Template of __init__.py defining a namespace package

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.pre_commit_config(opts)

Template of .pre-commit-config.yaml

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.readme(opts)

Template of README.rst

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.requirements(opts)

Template of requirements.txt

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.setup_cfg(opts)

Template of setup.cfg

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.setup_py(opts)

Template of setup.py

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.skeleton(opts)

Template of skeleton.py defining a basic console script

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.sphinx_authors(opts)

Template of authors.rst

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.sphinx_changes(opts)

Template of changes.rst

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.sphinx_conf(opts)

Template of conf.py

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.sphinx_index(opts)

Template of index.rst

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.sphinx_license(opts)

Template of license.rst

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.sphinx_makefile(opts)

Template of Sphinx’s Makefile

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.tox(opts)

Template of tox.ini

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.travis(opts)

Template of .travis.yml

Parameters:opts – mapping parameters as dictionary
Returns:file content as string
pyscaffold.templates.travis_install(opts)

Template of travis_install.sh

Parameters:opts – mapping parameters as dictionary
Returns:file content as string

pyscaffold.utils module

Miscellaneous utilities and tools

pyscaffold.utils.best_fit_license(txt)

Finds proper license name for the license defined in txt

Parameters:txt – license name as string
Returns:license name as string
pyscaffold.utils.chdir(*args, **kwds)

Contextmanager to change into a directory

Parameters:path – path to change into as string
pyscaffold.utils.check_setuptools_version()

Checks that setuptools has all necessary capabilities for setuptools_scm

pyscaffold.utils.exceptions2exit(exception_list)

Decorator to convert given exceptions to exit messages

This avoids displaying nasty stack traces to end-users

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

Retrieve all files in the current directory by a pattern. Use ** as greedy wildcard and * as non-greedy wildcard.

Parameters:pattern – The pattern as used by distutils.filelist.Filelist
pyscaffold.utils.is_valid_identifier(string)

Check if string is a valid package name

Parameters:string – package name as string
Returns:boolean
pyscaffold.utils.levenshtein(s1, s2)

Calculate the Levenshtein distance between two strings

Parameters:
  • s1 – first string
  • s2 – second string
Returns:

distance between s1 and s2 as integer

pyscaffold.utils.list2str(lst, indent=0, brackets=True, quotes=True)

Generate a Python syntax list string with an indention

Parameters:
  • lst – list
  • indent – indention as integer
  • brackets – surround the list expression by brackets as boolean
  • quotes – surround each item with quotes
Returns:

string

pyscaffold.utils.make_valid_identifier(string)

Try to make a valid package name identifier from a string

Parameters:string – invalid package name as string
Returns:valid package name as string or RuntimeError
pyscaffold.utils.prepare_namespace(namespace_str)

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

Parameters:namespace_str – namespace as string, e.g. “com.blue_yonder”
Returns:list of namespaces, e.g. [“com”, “com.blue_yonder”]
pyscaffold.utils.utf8_decode(string)

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

Parameters:string – Python 2 str object or Python 3 str object
Returns:Python 2 unicode object or Python 3 str object
pyscaffold.utils.utf8_encode(string)

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

Parameters:string – Python 2 unicode object or Python 3 str object
Returns:Python 2 str object or Python 3 str object

Module contents