8. Reference for all rules

8.1. pyke.rules

pyke.rules.clean(files, recursive=False, ignore_errors=True, **kwargs)

This method schedules some files and/or folder to be removed when the ‘clean’ phase is executed.

This is a special method that has been created with the pourpose of being functionally equivalent to the following code:

>>> old_section = pyke.build.section ('clean')
>>> rm (files)
>>> pyke.build.section (old_section)

Here this method works exactly as ‘rm’ with all the parameters, but all methods will be scheduled only in the clean phase, otherwise they will be ignored.

pyke.rules.compress(target, sources, algorithm=None, recursive=True, exclude=None, verbose=False, ignore_errors=False, **kwargs)

Compress the source files inside the target file, using appropriate compression algorithm based on the extension.

Depending on the file extension it will use one comperssion or another. .zip -> compress using zip file format .tar -> plain tar with no compression .tgz -> tar+gz .tar.gz -> tar+gz .tar.bz2-> tar+bzip2

Example:

>>> pyke.rules.compress ('out.tgz', { 'src/**' : 'tgz-path/src/' })
>>> pyke.rules.compress ('out.tgz', { 'LICENSE' : ['LICENSE', 'COPYING'] })

pyke.rules.cp(sources, target, mkdirs=True, replace=None, overwrite=True, copy_metadata=False, ignore_errors=False, **kwargs)

Copies a one or more source files to given destination

It accepts many sources but only one destination, so you can only copy one file to another file, or several files to a folder.

If the target is a folder that does not exists and mkdirs is True, the folder will get created to be able to copy the files. If mkdirs is False, it will fail.

If the target file exists it will fail, unless ignore_errors is specified in which case it will be overwritten.

pyke.rules.cptree(sources, target=None, overwrite=True, copy_metadata=False, ignore_errors=False, exclude=None, replace=None, **kwargs)

Copies a one or more source files to given destination

It accepts many sources but only one destination, so you can only copy one file to another file, or several files to a folder.

By default this method will overwrite files unless overwrite = False, in which case if a target file exists, it will fail.

exclude can be a path, a file pattern, a list combining both or a regular expression. Please note that exclude = ‘**.txt’ excludes all ‘txt’ files in any folder, whereas ‘.txt’ will probably do nothing, and os.path.join (source, ‘.txt’) will exclude all txt files in the source folder, but will not affect txt files in any of the subfolders being copied. This behaviour is on pourpose.

replace allows to perform internal string replacements on ALL files being copied.

Example:

>>> # recursive copy all files from in_folder to out_folder excluding '*.pyc' and '*.bak'
>>> cptree ('in_folder', 'out_folder', exclude = ['**.pyc', '**.bak'])

pyke.rules.execute(cmdline, **kwargs)

This command is for executing a single application calling the operating system directly (not using the shell).

Accepts the following keywords:

_cwd = current working directory where this command should run _creates = optional list of targets that will be generated _needs = list of dependencies _brief = how to display this command _if = changes the condition for this command to run

stdin_string = write given string on process standard input stdin_file = redirect process standard input to given file

stdout = equivalent to stdout_create stdout_create = redirect standard output to a new file (removes existing) stdout_append = redirect standard output to the end of a file (creates if not exists)

stderr = equivalent to stderr stderr_create = redirect standard error to a new file (removes existing) stderr_append = redirect standard error to the end of a file (creates if not exists)

expected_exitcode = the expected exit code of the application (defaults to 0)

when the output differs to this number, pyke will report an error and stop the execution

shell_mode = when False, it will call the operating system directly, whereas True will be equivalent as calling shell

universal_newlines = if False (by default) it will output the contents of the process as it is, otherwise (if True) it will try to normalize newlines.

Please note that this function will run always the command when no target list is specified, and in case a target list is specified it will be executed when the sources (_needs) are newer than the targets.

NOTE: since this method calls directly the OS, it won’t support pipes or other shell-like features.

Equivalent commands:

>>> execute ('ls -l')      --> runs $ls -l  in parallel with other commands
>>> execute ('ls', '-l')   --> runs $ls -l  in parallel with other commands
>>> execute (['ls', '-l']) --> runs $ls -l  in parallel with other commands

Example:

# creating file with result
$ ls -l > out
>>> execute ('ls -l', stdout_create = 'out')

# appending result to file
$ ls -l >> out
>>> execute ('ls -l', stdout_append = 'out')

pyke.rules.fileappend(file, contents, ignore_errors=False, **kwargs)

Appends given contents to a file, and when the file does not exist, it creates it

• ignore_errors: ignored

Return Value:

This file returns the job node that has been created for the task

pyke.rules.filereplace(source, target, replace_pairs, ignore_errors=False, force=False, **kwargs)

Opens given filename and replace the contents by using given replacement dictionary.

replace_pairs can be either a dict or a list of tuples where the first item is the search string and the second is the replacement string. Please note that using dicts does not guarantee the replacement order. Also note that compiled regular expressions can be used as well.

NOTE: The whole file is readed in memory for doing replacement

Example:

>>> filereplace ('source', 'target', )

pyke.rules.maketar(tarfile, sources, recursive=True, exclude=None, verbose=False, ignore_errors=False, **kwargs)

Adds given set of source files inside ‘tarfile’

pyke.rules.makezip(tarfile, sources, recursive=True, exclude=None, verbose=False, ignore_errors=False, **kwargs)

Adds given set of source files inside ‘ziopfile’

pyke.rules.mkdir(dirs, mode=511, ignore_errors=False, **kwargs)

Adds a job for creating each directory passed in the dirs list.

Arguments:

dirs can be a path string or list of path strings to specify which directories should be created.

Returns:

A list with all the directories that should have been created after all dirs exist

Example:

>>> mkdir( '/abspath/to/folder' )
['/abs/path/to/folder']

>>> mkdir( 'relpath/to/folder' )
['/abs/path/to/relpath/to/folder']

>>> mkdir( ['folder1', 'folder2'] )
['/abs/path/to/folder1', '/abs/path/to/folder2']

>>> mkdir( masterpath( ['folder1', 'folder2'] ) )
['/abs/path/to/master/folder1', '/abs/path/to/master/folder2']

pyke.rules.rm(files, recursive=False, ignore_errors=True, **kwargs)

Creates the rules to remove given set of files

pyke.rules.rmdir(paths, ignore_errors=True, **kwargs)

Creates the rules to remove given paths or set of pathss ignore_errors cause this function to always succeed.

e.g: rmdir (path_to_dir, _needs=files_inside)

pyke.rules.rmtree(files, ignore_errors=True, **kwargs)

pyke.rules.shell(cmdline, **kwargs)

Accepts a command line string or list of command-line arguments and some extra keywords.

_cwd = current working directory where this command should run _env = dictionary of environment variables we want to pass _creates = optional list of targets that will be generated _needs = list of dependencies _brief = how to display this command _if = changes the condition for this command to run

stdin_string = write given string on process standard input stdin_file = redirect process standard input to given file

stdout = equivalent to stdout_create stdout_create = redirect standard output to a new file (removes existing) stdout_append = redirect standard output to the end of a file (creates if not exists)

stderr = equivalent to stderr stderr_create = redirect standard error to a new file (removes existing) stderr_append = redirect standard error to the end of a file (creates if not exists)

expected_exitcode = the expected exit code of the application (defaults to 0)

when the output differs to this number, pyke will report an error and stop the execution

separator = defaults to ‘

‘ and serves to split multi-line commands

shell_mode = if True (by default) it will run given command through the OS shell, otherwise it will run calling operating system directly (as any other job).

universal_newlines = if False (by default) it will output the contents of the process as it is, otherwise (if True) it will try to normalize newlines.

Please note that this function will run always the command when no target list is specified, and in case a target list is specified it will be executed when the sources (_needs) are newer than the targets.

Equivalent commands:

>>> shell ('ls -l')    --> runs $ls -l  in parallel with other commands
>>> shell ('ls', '-l') --> runs $ls -l  in parallel with other commands
>>> shell (['ls -l'])  --> runs $ls -l  in parallel with other commands

Example:

# creating file with result $ ls -l > out >>> shell (‘ls -l’, stdout_create = ‘out’)

# appending result to file $ ls -l >> out >>> shell (‘ls -l’, stdout_append = ‘out’)

# running a piped command $ find . -name “.py” | xargs grep -l name > out >>> shell (‘find . -name “.py” | xargs grep -l name’, stdout_create = ‘out’)

# running several commands $ mkdir _x1 _x2 _x3 $ mkdir _a1 _a2 _a3 $ find . -name “_x*” | xargs rm -rf

>>> shell (
  """
    mkdir _x1 _x2 _x3 
    mkdir _a1 _a2 _a3 
    find . -name "_x*" | xargs rm -rf
  """
)

# same as before (please note “multiline = True”) >>> shell ([

“mkdir _x1 _x2 _x3”, “mkdir _a1 _a2 _a3”, “find . -name “_x*” | xargs rm -rf”

]

)

pyke.rules.touch(files, **kwargs)

Creates the rules to touch given set of files

Return Value: This method returns all the files that have been created

pyke.rules.untar(tarfile, target_path, verbose=True, ignore_errors=False, **kwargs)

Warning

Not implemented yet!

pyke.rules.unzip(zipfile, target_path, verbose=True, ignore_errors=False, **kwargs)

Warning

Not implemented yet!