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
anddestn
parameters, and then invokes theshutil.copytree
function.Parameters:
-
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
. Ifunpack
is True, then the retrieved file is assumed to be a tar file, and it is unpacked into the folder specified byunpack_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 ofdownload
is used. After a successful unpack the original downloaded file is deleted.
Return type: 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 aCommandError
on a non-zero return from the shell (unlessignore_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 theregexp
argument is not provided, the stdout of the command is returned. If theregexp
is provided, then the result of running anre.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: