Built-in Definitions¶

The following table defines all the variables that are pre-defined. Values passed into the py_mini_sh.run() function are added to this list of built-in values (and override them).

Name	Value	Comment
PYVER	e.g `'2.7'`	Current Python major + minor version.
PYVER_NUMBER	e.g. `'27'`	Current Python major and minor version.
BIN_DIR	On Windows `'Scripts'`	On Linux it will be `'bin'`.
SEP	On Windows `'\\'`	On Linux it will be `'/'`.
PYTHON_EXEC	`sys.executable`	Full path to the running interpreter
VENV_BIN	`sys.executable` folder	The folder in which the running intepreter is located.
SITE_PACKAGES	Platform dependent	The site-packages folder for the current interpreter.
PLATFORM	On Windows `'win'`	On Linux `'linux'`.
ALLVARIANTS	`'{PLATFORM}-{PYVER_NUMBER}'`	Useful for specifying varianted build or ship folders.
PYPI_HOST	From environment	Pulled from the env var if it’s there.
PIP_FLAGS	`'-i http://{PYPI_HOST}/simple --trusted-host={PYPI_HOST}'`	Or is set to `''` if PYPI_HOST is not defined.

Code Documentation¶

This package provides helper functions to simplify the writing of platform-independent sh-like scripts in Python.

py_mini_sh.BuildError¶

Backwards compatibility with old scripts

alias of py_mini_sh.CommandError

exception py_mini_sh.CommandError[source]¶: An exception that indicates a non-zero status has been returned from running a subprocess command.

py_mini_sh.PY2 = False¶: PY2 - True if running on a Python 2.X interpreter.

py_mini_sh.WINDOWS = False¶: WINDOWS is True if running on Windows, which is always the platform which does things differently.

py_mini_sh.copy_changed_files(src, pat, dst, prefix='')[source]¶

This function is most useful for copying files into a ship folder, and only copying the files from the source that are not in the destination, or are newer in the source location. This could be useful to not trigger re-builds if some make system is expecting files not to change if they are not different. This function operates only on the supplied source folder and does not recurse into sub-folders.

Parameters:	src – The location of the source folder, after it is expanded. pat (str) – A `glob.glob` pattern which is used for matching the source files, after it is expanded. dst – The destination for where the files should be copied, after it is expanded.

py_mini_sh.copytree(source, destn)[source]¶

This function expands the supplied source and destn parameters, and then invokes the shutil.copytree function.

Parameters:	source (str) – The source to the copytree, after it is expanded. destn (str) – The destination for the copytree, after it is expanded.

py_mini_sh.del_(fname)[source]¶

Unlink the expanded fname file if it exists. If the file doesn’t exist then this function does nothing. If it does, and there is an error in removing it, the appropriate OSError exception is raised.

Parameters:	fname (str) – Name of file to delete, which is expanded.

py_mini_sh.download(url, into, unpack=False, unpack_dir=None)[source]¶

Download the contents at the specified URL, expanding the URL with the current definitions, into the file named into. If unpack is True, then the retrieved file is assumed to be a tar file, and it is unpacked into the folder specified by unpack_dir.

Parameters:	url (str) – The URL used to download the file after expanding it. into (str) – The name of the file, after expanding, into which the downloaded contents is saved. unpack (bool) – If True then the downloaded file is unpacked. unpack_dir – If `unpack` is True the tar file is unpacked into this folder after it is expanded. If the value of this parameter is None then the default value of `download` is used. After a successful unpack the original downloaded file is deleted.
Return type:	str or None
Raises:	CommandError – if there is some error in downloading the file from the URL.

py_mini_sh.exec_(cmd, cwd=None, env=None, ignore_error=False, echo=True)[source]¶

Execute in command in a sub-shell. The cmd is expanded with the current definitions. Raise a CommandError on a non-zero return from the shell (unless ignore_error is True).

Parameters:

cmd (str) – The command to run, with format variables in it are expanded first.
cwd (None or str) – Set the current working folder for the command if it is provided. If it is then it is also expanded first.
env (None or dict) – Change the environment in which the command runs if provided.
ignore_error (bool) – Indicates whether an error running the command should be ignored, or if a CommandError exception is raised.
echo (bool) – Indicates if the command should be echoed to the logging output or not. This us usually because the command might contain sensitive information.

py_mini_sh.expand(fstr)[source]¶

Use the Python format method repeatedly to expand all variable references recursively.

Parameters:	fstr (str) – The string with the format expressions in it that need to be expanded with the current set of definitions.
Returns:	The recursively expanded string.
Return type:	str

py_mini_sh.is_d(dname)[source]¶

Test if the expanded directory exists.

Parameters:	dname – The name of the directory that is tested after `expand()` is called.
Return type:	bool

py_mini_sh.is_f(fname)[source]¶

Test if the expanded filename exists.

Parameters:	fname (str) – The name of the file that is tested after `expand()` is called.
Return type:	bool

py_mini_sh.parse_cmd_line()[source]¶: Pull out command line options that look like “<name>=<value>”, and return them in a dictionary. Ignore arguments that don’t match this pattern.

py_mini_sh.parse_pylint_output(lines)[source]¶

This function is useful for extracting data from the stdout of a pylint command. It would normally be used in conjunction with a pipe() call like this:

pylint_data = pipe('{VENV_BIN}pylint {PY_LINT_ARGS}', ignore_error=True)
e, w, c, r = parse_pylint_output(pylint_data)

Parameters:	lines (List[str]) – The lines of stdout text from a pylint run.
Returns:	A four-tuple of the number of errors, warnings, conventions and refactor statements found in the pylint output.

py_mini_sh.pipe(cmd, cwd=None, ignore_error=False, env=None, regexp=None)[source]¶

Execute the command in a sub-shell and collect the stdout from this command. The cmd is expanded with the current definitions. If the regexp argument is not provided, the stdout of the command is returned. If the regexp is provided, then the result of running an re.search on the output is returned.

Parameters:	cmd (str) – The command to run, with format variables in it are expanded first. cwd (None or str) – Set the current working folder for the command if it is provided. If it is then it is also expanded first. ignore_error (bool) – If True ignore any error in running the command, otherwise raise a `BuildCommand` on any error. env (None or dict) – Change the environment in which the command runs if provided. regexp (None or an `re.compile` object.) – A regular expression to use on the stdout of the command. If this is not provided the entire stdout is returned.
Returns:	The entire stdout of the command, or the result of running `re.search` on the stdout.
Return type:	List[str] or a Regular Expression object
Raises:	CommandError – when the cmd cannot run or returns a non-zero status.

py_mini_sh.readall(fname)[source]¶

Read all the data from the expanded fname file. The file is opened in text mode.

Parameters:	fname (str) – The file name that gets expanded before being opened.
Returns:	The contents of the file.

py_mini_sh.run(func, defines, add_cmd_args=True)[source]¶

This is the entry-point into this package. Scripts should usually be expressed as a single function that is handed to this function to run in the context of the predefined definitions, augmented with the supplied of defines to this function. A common way to structure your script is to do the following:

from py_mini_sh import run, ...

MY_VAR = 'foo'
ANOTHER_VAR = 42

def main()
    ...

if __name__ == '__main__':
    sys.exit(run(main, globals()))

Parameters:	func (Zero-args callable) – The function to call in the context of the supplied extra definitions. defines (dict) – The list of extra defines or redefinitions which are used when expanding many of the parameters of the functions defined in this package. add_cmd_args (bool) – If True the command line is parsed to look for values of the form “<name>=<value>”, and these are defintions are added to the defines that are provided.
Returns:	The return code which should be used to exit Python.
Return type:	int

py_mini_sh.unzip(source, destn)[source]¶

This function expands the supplied source and destn parameters, and then invokes the zipfile module’s extractall method.

Parameters:	source (str) – The location of the zipfile, after it is expanded. destn (str) – The destination for where the zipfile should be unzipped, after it is expanded.

py_mini_sh.writeall(fname, data)[source]¶

Write the data to the expanded fname file. The file is opened in text mode.

Parameters:	fname (str) – The name of the file that gets written. data (str) – The data that is written to the file.