Pmakeup autoloaded plugins

By default pmakeup has automatically loaded some plugin that allows you to make basic stuff (read from file, set variables). Such plugins are described here:

Core

class pmakeup.plugins.core.CorePMakeupPlugin.CorePMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

Contains all the commands available for the user in a PMakeupfile.py file

add_or_update_variable_in_cache(name: str, supplier: Callable[], Any], mapper: Callable[[Any], Any])

Add a new variable in the cache

Parameters

• name – the variable to set

• supplier – function used to generate the value fo the variable if the variable does not exist in the cache

• mapper – function used to generate the value fo the variable if the variable does exist in the cache. The input is the variable old value

clear_cache()

Clear the cache of pmakeup

ensure_condition(condition: Callable[], bool], message: str = '') → None

Perform a check. If the condition is not satisfied, we raise exception

Parameters

• condition – the condition to check. generate exception if the result is False

• message – the message to show if the exception needs to be generated

ensure_has_cli_variable(name: str) → None

Ensure the user has passed a variable via “–variable” CLI utils. If not, an exception is generated

Parameters

name – the variable name to check

ensure_has_cli_variable_is_one_of(name: str, *allowed_values) → None

Ensure that a variable has been passed from the command line and has a value among the one passed

Parameters

• name – variable name

• allowed_values – set of values we check against the variable calue

ensure_has_variable(name: str) → None

Ensure the user has passed a variable in the registry. If not, an exception is generated

Parameters

name – the variable name to check

get_all_available_command_names() → Iterable[str]

Get all the commands you can execute right now

get_all_registered_plugins() → Iterable[str]

get all the registered pmakeup plugins at this moment

get_architecture() → int

check if the system is designed on a 32 or 64 bits

Returns

either 32 or 64 bit

get_command_line_string() → str

Get the command line string from the user

Returns

argv

get_home_folder() → str

Get the home fodler of the currently logged used

get_latest_path_with_architecture(current_path: str, architecture: int) → str

get the latest path on the system with the specified archietcture

Parameters

• current_path – nominal path name

• architecture – either 32 or 64

Returns

the first path compliant with this path name

get_latest_version_in_folder(folder: str = None, should_consider: Callable[[str], bool] = None, version_fetcher: Callable[[str], semantic_version.base.Version] = None) → Tuple[semantic_version.base.Version, List[str]]

Scan the subfiles and subfolder of a given directory. We assume each file or folder has a version withint it. Then fetches the latest version. This command is useful in dierctories where all releases of a given software are placed. if we need to fetch the latest one, this function is perfect for the task.

Parameters

• folder – the folder to consider. If unspecified, it is the current working directory

• should_consider – a function that allows you to determine if we need to consider or not a subfile/subfolder. The input isan absolute path. If no function is given, we accept all the sub files

• version_fetcher – a function that extract a version from the filename. If left unspecified, we will use ::semantic_version_2_only_core

Returns

the latest version in the folder. The second element of the tuple is a collection of all the filenames that specify the latest version

get_pmakeupfile_dir() → str

The directory where the analyzed pmakeupfile is located

Returns

absolute ptha of the directory of the path under analysis

get_pmakeupfile_dirpath() → str

Returns

absolute path of the folder containing the main PMakeupfile path

get_pmakeupfile_path() → str

Returns

absolute path of the main PMakeupfile path

get_starting_cwd() → str

Returns

absolute path of where you have called pmakeup

get_variable_in_cache(name: str) → Any

Get the variable from the cache. if the variable does not exist, an error is generated

Parameters

name – name of the variable to check

Returns

the value associated to such a variable

get_variable_in_cache_or(name: str, default: Any) → Any

Get the variable value from the cache or get a default value if it does not exist

Parameters

• name – name of the variable to fetch

• default – if the variable does not exist in the cache, the value to retturn from this function

Returns

the variable value

get_variable_in_cache_or_fail(name: str) → Any

Get the variable value from the cache or raise an error if it does not exist

Parameters

name – name of the variable to fetch

Returns

the variable value

has_variable_in_cache(name: str) → bool

Check if a variable is in the pmakeup cache

Parameters

name – name of the variable to check

Returns

true if a varaible with such a name is present in the cache, false otherwise

include_file(*file: str) → None

Replace the include directive with the content fo the included file. Fails if there is no such path

Parameters

file – the external file to include in the script

include_string(string: str) → None

Include and execute the code within the given string

Parameters

string – the commands to execute

is_process_running(program_name: str) → bool

Check if a program with the given name is currently running

Parameters

program_name – the program we need to check

Returns

true if we are running such a program, false otheriwse

kill_process_by_name(program_name: str, ignore_if_process_does_not_exists: bool = True)

Kill a program

Parameters

• program_name – name fo the program that is running on the system

• ignore_if_process_does_not_exists – if the proces does not exist and thsi parameter is true, this function will not throw exception

kill_process_by_pid(pid: int, ignore_if_process_does_not_exists: bool = True)

Kill a program

Parameters

• pid – pid of the program that is running on the system

• ignore_if_process_does_not_exists – if the proces does not exist and thsi parameter is true, this function will not throw exception

load_cache()

Load all the variables present in cache into the available variables

log_command(message: str)

reserved. Useful to log the action performed by the user

Parameters

message – message to log

on_linux() → bool

Check if we are running on linux

Returns

true if we are running on linux

on_windows() → bool

Check if we are running on windows

Returns

true if we are running on windows

path_wrt_pmakeupfile(*folder: str) → str

Compute path relative to the file where PMakeupfile is located

Parameters

folder – other sections of the path

Returns

path relative to the absolute path of where PMakeupfile is located

path_wrt_starting_cwd(*folder: str) → str

Compute path relative to the starting cwd

Parameters

folder – other sections of the path

Returns

path relative to the absolute path of where you have called pmakeup

quasi_semantic_version_2_only_core(filename: str) → semantic_version.base.Version

A function that can be used within ::get_latest_version_in_folder. It accepts values like “1.0.0”, but also “1.0” and “1”

Parameters

filename – the absolute path of a file that contains a version

Returns

the version

read_variables_from_properties(file: str, encoding: str = 'utf-8') → None

Read a set of easy variables from a property file. All the read variables will be available in the “variables” value. If some variable name preexists, it will not be overriden :see: https://docs.oracle.com/cd/E23095_01/Platform.93/ATGProgGuide/html/s0204propertiesfileformat01.html

Parameters

• file – the file to read

• encoding – encoding of the file. If left missing, we will use utf-8

require_pmakeup_plugins(*pmakeup_plugin_names: str)

Tells pmakeup that, in order to run the script, you required a sequence of pmakeup plugins correctly installed (the version does not matter)

Pmakeup will then arrange itself in installing dependencies and the correct order of the plugins

Parameters

pmakeup_plugin_names – the plugins that are requierd to be present in order for the script to work. Dependencies are automatically added

require_pmakeup_version(lowerbound: str) → None

Check if the current version of pmakeup is greater or equal than the given one. If the current version of pmakeup is not compliant with this constraint, an error is generated

Parameters

lowerbound – the minimum version this script is compliant with

semantic_version_2_only_core(filename: str) → semantic_version.base.Version

A function that can be used within ::get_latest_version_in_folder

Parameters

filename – the absolute path of a file that contains a version

Returns

the version

set_variable_in_cache(name: str, value: Any, overwrite_if_exists: bool = True)

Set a variable inside the program cache. Setting variable in cache allows pmakeup to store information between several runs of pmakeup.

How pmakeup stores the information is implementation dependent and it should not be relied upon

Parameters

• name – name of the variable to store

• value – object to store

• overwrite_if_exists – if true, if the cache already contain a variable with the same name, such a varaible will be replaced with the new one

vars() → pmakeup.models.AttrDict.AttrDict

Get a dictioanry containing all the variables setup up to this point. You can use thi dictionary to gain access to a variable in a more pythonic way (e.g., vars.foo rather than get_variable(“foo”)

Raises

PMakeupException – if the variable is not found

Files

class pmakeup.plugins.files.FilesPMakeupPlugin.FilesPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

allow_file_to_be_executed_by_anyone(file: str)

Allow the file to be executed by anyone. On a linux system it should be equal to “chmod o+x”

Parameters

file – the file whose permission needs to be changed

append_string_at_end_of_file(name: str, content: Any, encoding: str = 'utf-8') → None

Append a string at the end of the file. carriage return is automatically added

Parameters

• name – filename

• content – string to append

• encoding – encoding of the file. If missing, “utf-8” is used

append_strings_at_end_of_file(name: str, content: Iterable[Any], encoding: str = 'utf-8') → None

Append a string at the end of the file. carriage return is automatically added

Parameters

• name – filename

• content – string to append

• encoding – encoding of the file. If missing, “utf-8” is used

copy_file(src: str, dst: str, create_dirs: bool = True)

Copy a single file from a position to another one. If the destination folder hierarchy does not exist, we will create it

Parameters

• src – file to copy

• dst – destination where the file will be copied to. If a file, we will copy the src file into another file with different name. If a directory, we will copy the specified file into the dirctory dst (without altering the filename)

• create_dirs – if true, we will create the directories of dst if non existent

copy_files_that_basename(src: str, dst: str, regex: str)

Copy the files located (directly or indirctly) in src into dst. We will copy only the files whose basename (e.g. foo.txt is the basename of /opt/foo/bar/foo.txt). We will copy the directories where a file is located as well matches the given regex

Parameters

• src – folder where we will find files to copy

• dst – destination of the files

• regex – regex that determines wether or not a file is copies

Returns

copy_folder_content(folder: str, destination: str)

Copy all the content of “folder” into the folder “destination”

Parameters

• folder – folder to copy files from

• destination – folder where the contents will be copied into

copy_tree(src: str, dst: str)

Copy a whole directory tree or a single file. If you specifies a file rather than a directory, the function behaves like :see copy_file

Parameters

• src – the folder or the file to copy.

• dst – the destination where the copied folder will be positioned

create_empty_directory(name: str) → str

Create an empty directory in the CWD (if the path is relative)

:param name:the name of the driectory to create :return: the full path of the directory just created

create_empty_file(name: str, encoding: str = 'utf-8')

Create an empty file. if the file is relative, it is relative to the CWD

Parameters

• name – file name to create

• encoding – encoding of the file. If unspecified, it is utf-8

find_directory(root_folder: str, folder: str) → Iterable[str]

Find all the directories with the given name

Parameters

• root_folder – fodler where we need to look int

• folder – name of the folder we need to fetch

Returns

list of files with thwe given filename

find_directory_with_filename_compliant_with_regex(root_folder: str, folder_regex: str) → Iterable[str]

Find all the directories with the given name

Parameters

• root_folder – fodler where we need to look int

• folder_regex – regex the folder name should be compliant with

Returns

list of files with thwe given filename

find_directory_with_fullpath_compliant_with_regex(root_folder: str, folder_regex: str) → Iterable[str]

Find all the directories with the given name

Parameters

• root_folder – folder where we need to look int

• folder_regex – regex the folder name should be compliant with

Returns

list of files with thwe given filename

find_executable_in_program_directories(program_name: str, fail_if_program_is_not_found: bool = False) → Optional[str]

Find a program ouside the path as well. Paths is still considered

Parameters

• program_name – name of the program to look for

• fail_if_program_is_not_found – if true, we will raise an exception if the program is not found

Returns

first absolute path of the program found. None if we did not find the program

find_file(root_folder: str, filename: str) → Iterable[str]

Find all the files with the given filename (extension included)

Parameters

• root_folder – fodler where we need to look int

• filename – filename we need to fetch

Returns

list of files with thwe given filename

find_file_in_roots_st(root_folders: str, match: Callable[[str, str, str], bool]) → Iterable[str]

Find all the files matchign the given function

Parameters

• root_folders – folders where we need to look int

• match – a function that defines if you want to include the file into the output. The first parameter is the folder containing the given file. The second parameter is the involved file. The third is the absolute path of the involved path

Returns

list of files compliant with the given function

find_file_st(root_folder: str, match: Callable[[str, str, str], bool]) → Iterable[str]

Find all the files matchign the given function

Parameters

• root_folder – folder where we need to look int

• match – a function that defines if you want to include the file into the output. The first parameter is the folder containing the given file. The second parameter is the involved file. The third is the absolute path of the involved path

Returns

list of files compliant with the given function

find_file_with_filename_compliant_with_regex(root_folder: str, filename_regex: str) → Iterable[str]

Find all the files containign (search) the given regex

Parameters

• root_folder – folder where we need to look int

• filename_regex – the regex any filename should be compliant

Returns

list of files with thwe given filename

find_file_with_fullpath_compliant_with_regex(root_folder: str, filename_regex: str) → Iterable[str]

Find all the files containing (search) the given regex

Parameters

• root_folder – folder where we need to look int

• filename_regex – the regex any filename should be compliant

Returns

list of files with the given filename

find_first_file_in_roots_st(root_folders: str, match: Callable[[str, str, str], bool]) → Optional[str]

Find the first file matching the given function

Parameters

• root_folders – folders where we need to look int

• match – a function that defines if you want to include the file into the output. The first parameter is the folder containing the given file. The second parameter is the involved file. The third is the absolute path of the involved path

Returns

file compliant with the given function or None

find_first_file_in_roots_st_or_fail(root_folders: str, match: Callable[[str, str, str], bool]) → str

Find the first file matching the given function. If no such file exists, generates an exception

Parameters

• root_folders – folders where we need to look int

• match – a function that defines if you want to include the file into the output. The first parameter is the folder containing the given file. The second parameter is the involved file. The third is the absolute path of the involved path

Returns

file compliant with the given function or None

find_first_file_st(root_folder: str, match: Callable[[str, str, str], bool]) → Optional[str]

Find the first file matching the given function

Parameters

• root_folder – folder where we need to look int

• match – a function that defines if you want to include the file into the output. The first parameter is the folder containing the given file. The second parameter is the involved file. The third is the absolute path of the involved path

Returns

file compliant with the given function or None

find_first_file_st_or_fail(root_folder: str, match: Callable[[str, str, str], bool]) → str

Find the first file matching the given function. If no such file exists, generates an exception

Parameters

• root_folder – folder where we need to look int

• match – a function that defines if you want to include the file into the output. The first parameter is the folder containing the given file. The second parameter is the involved file. The third is the absolute path of the involved path

Returns

file compliant with the given function or None

find_folder_st(root_folder: str, match: Callable[[str, str, str], bool]) → Iterable[str]

Find all the folder matching a given function

Parameters

• root_folder – folder where we need to look int

• match – a function that defines if you want to include the folder into the output. The first parameter is the folder containing the given folder. The second parameter is the involved folder. The third is the absolute path of the involved path

Returns

list of folders compliant with the given function

find_regex_match_in_file(pattern: str, *p: str, encoding: str = 'utf8', flags: Union[int, re.RegexFlag] = 0) → Optional[re.Match]

FInd the first regex pattern in the file

If you used named capturing in the pattern, you can gain access via result.group(“name”)

Parameters

• pattern – regex pattern to consider

• p – file to consider

• encoding – encoding of the file to search. Defaults to utf8

• flags – flags of the regex to build. Passed as-is

Returns

a regex match representing the first occurence. If None we could not find anything

get_file_size(*f: str) → int

Get the filesize of a given file. If the file is a directory, return the cumulative size of all the files in it

Parameters

f – the path of the file to consider

Returns

number of bytes

is_directory(*p: str) → bool

Check if the given path is a directory

Parameters

p – paths to check

Returns

true if the concatenated version of p is a directory. False otherwise

is_directory_empty(name: str) → bool

Check if a directory exists and is empty

Parameters

name – folder to check

Returns

true if the folder exists and is empty, false otherwise

is_directory_exists(name: str) → bool

Check if a directory exists.

Parameters

name – folder to check

Returns

true if the folder exists, false otherwise

is_file(*p: str) → bool

Check if the given path represents a file or a directory

Parameters

p – paths to check

Returns

true if the concatenated version of p is a file. False otherwise

is_file_empty(name: str) → bool

Checks if a file exists. If exists, check if it empty as well.

Parameters

name – file to check

Returns

true if the file exists and has no bytes; false otherwise

is_file_exists(name: str) → bool

Check if a file exists

Parameters

name – file whose existence we need to assert

Returns

true if the file exists, false otherwise

is_file_non_empty(*name: str) → bool

Checks if a file exists. If exists, check if it is not empty as well.

Parameters

name – file to check

Returns

true if the file exists and has at least one byte; false otherwise

ls(folder: str = None, generate_absolute_path: bool = False) → Iterable[str]

Show the list of all the files in the given directory

Parameters

• folder – folder to scan. default to CWD

• generate_absolute_path – if true, we will generate in the outptu the absolute path of the subfolders. Otherwise we will return only the

Returns

iterable of all the files in the given directory

ls_directories_recursive(folder: str) → Iterable[str]

Show the list of all the directories in the given folder

Parameters

folder – folder to scan (default to cwd)

Returns

list of absolute filename representing the stored directories

ls_only_directories(folder: str = None, generate_absolute_path: bool = False) → Iterable[str]

Show the list of all the directories in the given directory

Parameters

• folder – folder to scan. If missing, default to CWD

• generate_absolute_path – if true, we will generate in the outptu the absolute path of the subfolders. Otherwise we will return only the names.

Returns

a list of absolute paths representing the subdirectories inside folder

ls_only_files(folder: str = None, generate_absolute_path: bool = False) → Iterable[str]

Show the list of all the files (but not directories) in the given directory

Parameters

• folder – folder to scan. default to CWD

• generate_absolute_path – if true, we will generate in the outptu the absolute path of the subfolders. Otherwise we will return only the

Returns

ls_recursive(folder: str = None) → Iterable[str]

Show the list of all the files in the given folder

Parameters

folder – folder to scan (default to cwd)

Returns

list of absolute filename representing the stored files

make_directories(*folder: str) → None

Create all the needed directories for the given path. Note that if you inject the path temp/foo/hello.txt (you can see hello.txt shoudl be a file) the function will generate hello.txt as a directory!

Parameters

folder – folders to create

move_file(src: str, dst: str)

Move a single file from a location to another one

Parameters

• src – the file to move

• dst – the path where the file will be moved to

move_tree(src: str, dst: str)

Move an entire directory tree from one position to another one

Parameters

• src – path of the directory to move

• dst – path of the directory that we will create

read_file_content(name: str, encoding: str = 'utf-8', trim_newlines: bool = True) → str

Read the whole content of the file in a single string

Parameters

• name – name of the file to load

• encoding – the encoding of the file. If unspecified, it is utf-8

• trim_newlines – if true, we will trim the newlines, spaces and tabs at the beginning and at the end of the file

Returns

string repersenting the content of the file

read_lines(name: str, encoding: str = 'utf-8') → Iterable[str]

Read the content of a file and yields as many item as there are lines in the file. Strip from the line ending new lines. Does not consider empty lines

Parameters

• name – name of the file

• encoding – encoding of the file. If unspecified, it is utf-8

Returns

iterable containing the lines of the file

remove_file(name: str, ignore_if_not_exists: bool = True) → bool

Remove a file. If the cannot be removed (for some reason), ignore_if_not_exists determines if somethign goes wrong

Parameters

• name – file to delete

• ignore_if_not_exists – if true, we won’t raise exception if the file does not exists or cannot be removed

Returns

true if we have removed the file, false otherwise

remove_files_that_basename(src: str, regex: str)

Remove the files located (directly or indirectly) in src. We will copy only the files whose basename (e.g. foo.txt is the basename of /opt/foo/bar/foo.txt). We will copy the directories where a file is located as well matches the given regex

Parameters

• src – folder where we will find files to copy

• regex – regex that determines wether or not a file is copies

Returns

remove_last_n_line_from_file(name: str, n: int = 1, consider_empty_line: bool = False, encoding: str = 'utf-8') → List[str]

Read the content of a file and remove the last n lines from the file involved. Then, rewrites the whole file

Parameters

• name – file involved. If relative, it is relative to ::cwd()

• n – the number of lines to remove at the end.

• consider_empty_line – if True, we consider empty lines as well.

• encoding – the encoding used to rewrite file

Returns

the lines just removed

remove_string_in_file(name: str, substring: str, count: int = - 1, encoding: str = 'utf-8')

Remove some (or all) the occurences of a given substring in a file

Parameters

• name – path of the file to handle

• substring – substring to replace

• count – the number of occurences to remove. -1 if you want to remove all occurences

• encoding – encoding used for reading the file

remove_tree(*folder: str, ignore_if_not_exists: bool = True) → None

Remove a dirctory tree

Parameters

• folder – path to the directory to remove

• ignore_if_not_exists – if the directory does not exists, we do nothing if htis field is true

replace_regex_in_file(name: str, regex: str, replacement: str, count: int = - 1, encoding: str = 'utf-8')

Replace some (or all) the occurences of a given regex in a file.

If you want to use named capturing group, you can do so! For instance,

replace_regex_in_file(file_path, ‘(?P<word>w+)’, ‘(?P=word)aa’) ‘spring’ will be replaced with ‘springaa’

It may not work, so you can use the following syntax to achieve the same: replace_regex_in_file(file_path, ‘(?P<word>w+)’, r’g<word>aa’) ‘spring’ will be replaced with ‘springaa’

Parameters

• name – path of the file to handle

• regex – regex to replace

• replacement – string that will replace substring

• count – the number of occurences to replace. -1 if you want to replace all occurences

• encoding – encoding used for reading the file

See

https://docs.python.org/3/howto/regex.html

replace_string_in_file(name: str, substring: str, replacement: str, count: int = - 1, encoding: str = 'utf-8')

Replace some (or all) the occurences of a given substring in a file

Parameters

• name – path of the file to handle

• substring – substring to replace

• replacement – string that will replace substring

• count – the number of occurences to replace. -1 if you want to replace all occurences

• encoding – encoding used for reading the file

write_file(name: str, content: Any, encoding: str = 'utf-8', overwrite: bool = False, add_newline: bool = True)

Write into a file with the specified content. if overwrite is unset, we will do nothing if the file already exists

Parameters

• name – name of the file to create

• content – content of the file to create.

• encoding – encoding fo the file to create. utf-8 by default

• overwrite – if true, we will overwrite the file

• add_newline – if true, we will add a new line at the end of the content

write_lines(name: str, content: Iterable[Any], encoding: str = 'utf-8', overwrite: bool = False)

Write severla lines into a file. if overwrite is unset, we will do nothing if the file already exists

Parameters

• name – name of the file to create

• content – lines of the file to create. We will append a new ine at the end of each line

• encoding – encoding fo the file to create. utf-8 by default

• overwrite – if true, we will overwrite the file

Paths

class pmakeup.plugins.paths.PathsPMakeupPlugin.PathsPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

abs_path(*p: pmakeup.plugins.paths.PathsPMakeupPlugin.PathsPMakeupPlugin.path) → str

Generate a path compliant with the underlying operating system path scheme.

If the path is relative, it is relative to the cwd

Parameters

p – the path to build

cd(*folder: str, create_if_not_exists: bool = True) → str

Gain access to a directory. If the directory does nto exists, it is created If the path is relative, it is relative to the CWD

Parameters

• folder – folder where we need to go into

• create_if_not_exists – if true, we will create the directory if we try to cd into a non existent directory

Returns

the directory where we have cd from

cd_into_directories(folder: str, prefix: str, folder_format: str, error_if_mismatch: bool = True)

Inside the given folder, there can be several folders, each of them with the same format. We cd into the “latest” one. How can we determine which is the “latest” one? Via folder_format. it is a string that is either: - “number”: an integer number - “semver2”: a semantic versionign string; We fetch the “latest” by looking at the one with the greater value. If the folder contains a folder which it is not compliant with folder_format, it is either ignored or rase error

Parameters

• folder – folder where several folders are located

• prefix – a string that prefix folder_format

• folder_format – either “number” or “semver2”

• error_if_mismatch – if a folder is not compliant with folder_format, if true we will generate an exception

Returns

change_filename_extension(new_extension: str, *p) → str

Change the extension of the given path

new extensions: dat /path/to/file.txt.zp.asc -> /path/to/file.txt.zp.dat

Parameters

• new_extension – extension that will be set

• p – path to chan

Returns

p, but with the updated extensions

cwd() → str

Returns

the CWD the commands operates in

get_absolute_file_till_root(filename: str, base: str = None) → str

Starting from the directory base, check if a fiel called “filename” is present. If nt, recursively chekc the parent directory Raise an exception if the file is not found whern considering the root

Parameters

• filename – the name of the file (extension included) we need to look for

• base – directory where we start looking. If left missing, we consider the CWD

Returns

absolute path of the file found

get_basename(*p) → str

Compute the base name of the path

/path/to/file.txt.zp.asc -> file.txt.zp.asc

Parameters

p – path to consider

Returns

basename

get_basename_with_no_extension(*p) → str

Compute the basename of the path and remove its extension as well

/path/to/file.txt.zp.asc -> file.txt.zp

Parameters

p – path to consider

Returns

basename

get_extension(*p) → str

Compute the extension of a file

Parameters

p – the file to consider

Returns

the file extension

get_file_without_extension(*p: str) → str

Compute the filename without its last extension

/path/to/some/file.txt.zip.asc –> /path/to/some/file.txt.zip

Parameters

p – path to consider

Returns

same absolute path, without extension

get_parent_directory(*p) → str

Retrieve the absolute path of the parent directory of the specified path.

/foo/tbar/tmp.txt -> /foo/tbar

Parameters

p – path to consider

Returns

parent directory of path

get_relative_path_wrt(p: str, reference: str) → str

If we were in folder reference, what actiosn should we perform in order to reach the file p?

Parameters

• p – the file to reach

• reference – the folder we are in right now

Returns

relative path

path(*p: str) → str

Generate a path compliant wit the underlying operating system path scheme.

If the path is relative, we will not join it with cwd

Parameters

p – the path to build

Strings

class pmakeup.plugins.strings.StringsPMakeupPlugin.StringsPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

match(string: str, regex: str) → bool

Check if a given string matches perfectly the given regex

Parameters

• string – the sting to check

• regex – the regex to check. The syntax is available at https://docs.python.org/3/library/re.html

Returns

true if such a substring can be found, false otherwise

replace_regex_in_string(string: str, regex: str, replacement: str, count: int = - 1, encoding: str = 'utf-8') → str

Replace some (or all) the occurences of a given string

If you want to use named capturing group, you can do so! For instance,

replace_regex_in_string(‘3435spring9437’, r’(?P<word>[a-z]+)’, r’
aa’) ‘spring’ will be replaced with ‘springaa’

It may not work, so you can use the following syntax to achieve the same: replace_regex_in_file(file_path, ‘(?P<word>w+)’, r’g<word>aa’) ‘spring’ will be replaced with ‘springaa’

Parameters

• string – string that will be involved in the replacements

• regex – regex to replace

• replacement – string that will replace substring

• count – the number of occurences to replace. -1 if you want to replace all occurences

• encoding – encoding used for reading the file

See

https://docs.python.org/3/howto/regex.html

replace_substring_in_string(string: str, substring: str, replacement: str, count: int = - 1) → str

Replace some (or all) the occurences of a given string

Parameters

• string – string that will be involved in the replacements

• substring – the string to repplace

• replacement – string that will replace substring

• count – the number of occurences to replace. -1 if you want to replace all occurences

search(string: str, regex: str)

Check if a given string has a substring that matches the given regex

Parameters

• string – the sting to check

• regex – the regex to check. The syntax is available at https://docs.python.org/3/library/re.html

Returns

true if such a substring can be found, false otherwise

Targets

class pmakeup.plugins.targets.TargetsPMakeupPlugin.TargetsPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

declare_file_descriptor(description: str)

Defines what to write at the beginning of the info string that is displayed whenver the user wants to know what the given Pmakeupfile does

Parameters

description – string to show

declare_target(target_name: str, f: Callable[], None], requires: Iterable[str] = None, description: str = '')

Declare that the user can declare a pseudo-makefile target.

Parameters

• target_name – name of the target to declare

• description – a description that is shown when listing all available targets

• requires – list fo target names this target requires in order to be executed. They must already exist in pmakeup environment

• f – the function to perform when the user requests this target

get_target_descriptor(target_name: str) → pmakeup.TargetDescriptor.TargetDescriptor

Get a descriptor for a given pmakeup target. Raises exception if target is not declared

Parameters

target_name – name of the target

Returns

descriptor for the target

is_target_requested(target_name: str) → bool

Check if the the user has specified the given target

Parameters

target_name – the name of the target that we need to check

Returns

true if the target has been declard by the user, false otherwise

process_targets()

Function used to process in the correct order. If the user requested to show the help for this file, the function will show it and return it

It will call the function declared in declare_target

TempFiles

class pmakeup.plugins.tempfiles.TempFilesPMakeupPlugin.TempFilesPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

create_temp_directory_with(directory_prefix: str) → Any

Create a temporary directory on the file system where to put temporary files

Parameters

directory_prefix – a prefix to be put before the temporary folder

Returns

the absolute path of the temporary folder created. The function can be used an input of a “with” statement. The folder will be automatically removed at the end of the with.

create_temp_file(directory: str, file_prefix: str = None, file_suffix: str = None, mode: str = 'r', encoding: str = 'utf-8', readable_for_all: bool = False, executable_for_owner: bool = False, executable_for_all: bool = False) → str

Creates the file. You need to manually dispose of the file by yourself

Parameters

• directory – the directory where to put the file

• file_prefix – a string that will be put at the beginning of the filename

• file_suffix – a string that will be put at the end of the filename

• mode – how we will open the file. E.g., “r”, “w”

• encoding – the encodign of the file. Default to “utf-8”

• readable_for_all – if True, the file can be read by anyone

• executable_for_owner – if True, the file can be executed by the owner

• executable_for_all – if True, anyone can execute the file

Returns

the absolute path of the temp file

get_temp_filepath(prefix: str = None, suffix: str = None) → str

Get the filename of a temp file. You need to manually create such a temp file

Parameters

• prefix – a prefix the temp file to generate has

• suffix – a suffix the temp file to generate has

Returns

the absolute path of the temp path

Utils

class pmakeup.plugins.utils.UtilsPMakeupPlugin.UtilsPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

as_bool(v: Any) → bool

Convert a value into a boolean

Parameters

v – value to convert as a boolean

Returns

true of false

convert_table(table_str: str) → List[List[str]]

Convert a table printed as:

Port Type Board Name FQBN Core /dev/ttyACM1 Serial Port (USB) Arduino/Genuino MKR1000 arduino:samd:mkr1000 arduino:samd

Into a list of lists of strings

Parameters

table_str – representation of a table

Returns

list of lists of strings

get_column_of_table(table: List[List[str]], index: int) → List[str]

Select a single column from the table, generated by ::convert_table

Parameters

• table – the table generated by ::convert_table

• index – index of the column to return. Starts from 0

Returns

the column requested

get_column_of_table_by_name(table: List[List[str]], column_name: str) → List[str]

Select a single column from the table, generated by ::convert_table We assumed the first row of the table is a header, contaiing the column names

Parameters

• table – the table generated by ::convert_table

• column_name – name of the column to return.

Returns

the column requested

grep(lines: Iterable[str], regex: str, reverse_match: bool = False) → Iterable[str]

Filter the lines fetched from terminal

Parameters

• lines – the lines to fetch

• regex – a python regex. If a line contains a substring which matches the given regex, the line is returned

• reverse_match – if True, we will return lines which do not match the pattern

Returns

lines compliant with the regex

pairs(it: Iterable[Any]) → Iterable[Tuple[Any, Any]]

Convert the iterable into an iterable of pairs.

1,2,3,4,5,6 becomes (1,2), (2,3), (3,4), (4,5), (5,6)

Parameters

it – iterable whose sequence we need to generate

Returns

iterable of pairs

Logging

class pmakeup.plugins.log.LoggingPMakeupPlugin.LoggingPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

critical(message: str)

Log a message using ‘CRITICAL’ level

Parameters

message – the message to log

debug(message: str)

Log a message using ‘DEBUG’ level

Parameters

message – the message to log

echo(message: str, foreground: str = None, background: str = None)

Print a message on the screen

Parameters

• message – the message to print out

• foreground – foreground color of the string. Accepted values: RED, GREEN, YELLOW, BLUE, MAGENT, CYAN, WHITE

• background – background color of the string. Accepted values: RED, GREEN, YELLOW, BLUE, MAGENT, CYAN, WHITE

echo_variables(foreground: str = None, background: str = None)

Echo all the variables defined in “variables”

Parameters

• foreground – the foregruodn color

• background – the background color

info(message: str)

Log a message using ‘INFO’ level

Parameters

message – the message to log

print_blue(message: str)

Print a blue message

Parameters

message – message to print

print_cyan(message: str)

Print a blue message

Parameters

message – message to print

print_red(message: str)

Print a red message

Parameters

message – message to print

print_yellow(message: str)

Print a blue message

Parameters

message – message to print

Operating system

class pmakeup.plugins.operating_system.OperatingSystemPMakeupPlugin.OperatingSystemPMakeupPlugin(model: pmakeup.models.PMakeupModel.PMakeupModel)

Bases: pmakeup.plugins.AbstractPmakeupPlugin.AbstractPmakeupPlugin

current_user() → str

get the user currently logged

Returns

the user currently logged

execute_admin_and_forget(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → int

Execute a command as admin but ensure that no stdout will be printed on the console

Parameters

• commands – the command to execute. They will be exeucte in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_admin_and_run_in_background(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, Any] = None) → int

Execute a command as admin but ensure that no stdout will be printed on the console

Parameters

• commands – the command to execute. They will be exeucte in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

Returns

pid of running process

execute_admin_return_stdout(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → Tuple[int, str, str]

Execute a command as an admin. We won’t show the stdout on pmakeup console but we will capture it and returned it

Parameters

• commands – the command to execute. They will be execute in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_admin_stdout_on_screen(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → int

Execute a command as an admin. We won’t capture the stdout but we will show it on pmakeup console

Parameters

• commands – the command to execute. They will be execute in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_admin_with_password_and_run_in_background(commands: Union[str, List[Union[str, List[str]]]], password: str, cwd: str = None, env: Dict[str, Any] = None) → int

Execute a command as admin but ensure that no stdout will be printed on the console

Parameters

• commands – the command to execute. They will be exeucte in the same context

• password – password of the user to invoke the program as an admin

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_admin_with_password_fire_and_forget(commands: Union[str, List[Union[str, List[str]]]], password: str, cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → int

Execute a command as admin by providing the admin password. THIS IS INCREDIBLE UNSAFE!!!!!!!!!!!!. Please, I beg you, do NOT use this if you need any level of security!!!!! This will make the password visible on top, on the history, everywhere on your system. Please use it only if you need to execute a command on your local machine.

Parameters

• commands – the command to execute. They will be executed in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

• password – [UNSAFE!!!!] If you really need, you might want to run a command as an admin only on your laptop, and you want a really quick and dirty way to execute it, like as in the shell. Do not use this in production code, since the password will be ‘printed in clear basically everywhere! (e.g., history, system monitor, probably in a file as well)

execute_admin_with_password_return_stdout(commands: Union[str, List[Union[str, List[str]]]], password: str, cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → Tuple[int, str, str]

Execute a command as an admin. We won’t show the stdout on pmakeup console but we will capture it and returned it

Parameters

• commands – the command to execute. They will be execute in the same context

• password – [UNSAFE!!!!] If you really need, you might want to run a command as an admin only on your laptop, and you want a really quick and dirty way to execute it, like as in the shell. Do not use this in production code, since the password will be ‘printed in clear basically everywhere! (e.g., history, system monitor, probably in a file as well)

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_admin_with_password_stdout_on_screen(commands: Union[str, List[Union[str, List[str]]]], password: str, cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → int

Execute a command as an admin. We won’t capture the stdout but we will show it on pmakeup console

Parameters

• commands – the command to execute. They will be execute in the same context

• password – [UNSAFE!!!!] If you really need, you might want to run a command as an admin only on your laptop, and you want a really quick and dirty way to execute it, like as in the shell. Do not use this in production code, since the password will be ‘printed in clear basically everywhere! (e.g., history, system monitor, probably in a file as well)

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_and_forget(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, str] = None, check_exit_code: bool = True, timeout: int = None) → int

Execute a command but ensure that no stdout will be printed on the console

Parameters

• commands – the command to execute. They will be exeucte in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_and_run_in_background(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, str] = None) → int

Execute a command but ensure that no stdout will be printed on the console

Parameters

• commands – the command to execute. They will be exeucte in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

Returns

pid of running process

execute_return_stdout(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → Tuple[int, str, str]

Execute a command. We won’t show the stdout on pmakeup console but we will capture it and returned it

Parameters

• commands – the command to execute. They will be exeucte in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

execute_stdout_on_screen(commands: Union[str, List[Union[str, List[str]]]], cwd: str = None, env: Dict[str, Any] = None, check_exit_code: bool = True, timeout: int = None) → int

Execute a command. We won’t capture the stdout but we will show it on pmakeup console

Parameters

• commands – the command to execute. They will be exeucte in the same context

• cwd – current working directory where the command is executed

• env – a dictionary representing the key-values of the environment variables

• check_exit_code – if true, we will generate an exception if the exit code is different than 0

• timeout – if positive, we will give up waiting for the command after the amount of seconds

Returns

triple. The first element is the error code, the second is the stdout (if captured), the third is stderr

get_program_path() → Iterable[str]

List of paths in PATH environment variable

Returns

collections of path

is_program_installed(program_name: str) → bool

Check if a program is reachable via commandline. We will look only in the PATH environment variable. If you want to look in other parts as well, conside rusing

Parameters

program_name – the name of the program (e.g., dot)

Returns

true if there is a program accessible to the PATH with the given name, false otherwise