craftr.path

craftr.path.addprefix(subject, prefix)

Given a filename, this function will prepend the specified prefix to the base of the filename and return it. filename may be an iterable other than a string in which case the function is applied recursively and a list is being returned instead of a string.

__Important__: This is not the directy equivalent of addsuffix() as it considered subject to be a filename and appends the prefix only to the files base name.

craftr.path.addsuffix(subject, suffix, replace=False)

Given a string, this function appends suffix to the end of the string and returns the new string.

subject may be an iterable other than a string in which case the function will be applied recursively on all its items and a list is being returned instead of a string.

If the replace argument is True, the suffix will be replaced instead of being just appended. Make sure to include a period in the suffix parameter value.

craftr.path.autoglob(path, parent=None)

Returns glob(path) if path is actually a glob-style pattern. If it is not, it will return [path] as is, not checking wether it exists or not.

craftr.path.buildlocal(path)

Given a relative path, this function returns an absolute version assuming the path is relative to to current module’s build directory.

Note

Can only be called from a module context (ie. from inside a Craftr module).

craftr.path.commonpath(paths)

Returns the longest sub-path of each pathname in the sequence paths. Raises ValueError if paths is empty or contains both relative and absolute pathnames. If there is only one item in paths, the parent directory is returned.

craftr.path.get_long_path_name(path)

On Windows, this function returns the correct capitalization for path. On all other systems, this returns path unchanged.

craftr.path.glob(*patterns, exclude=None, parent=None)

Wrapper for glob2.glob() that accepts an arbitrary number of patterns and matches them. The paths are normalized with normpath(). If called from within a module, relative patterns are assumed relative to the modules parent directory.

If exclude is specified, it must be a string or a list of strings that is/contains glob patterns or filenames to be removed from the result before returning.

craftr.path.isglob(path)

Returns True if path is a glob-able pattern, False if not.

craftr.path.iter_tree(dirname, depth=1)

Iterates over all files in dirname and its sub-directories up to the specified depth. If dirname is a list, this scheme will be applied for all items in the list.

craftr.path.listdir(path, abs=True)

This version of os.listdir yields absolute paths.

craftr.path.local(path)

Given a path relative to the current module’s project directory, this function returns a normalized absolute path. Just like many of the path functions, path can also be alist.

Note

Can only be called from a module context (ie. from inside a Craftr module).

craftr.path.makedirs(path)

Simple os.makedirs() clone that does not error if path is already an existing directory.

craftr.path.move(filename, basedir, newbase)

Given a filename and two directory names, this function generates a new filename which is constructed from the relative path of the filename and the first directory and the joint of this relative path with the second directory.

This is useful to generate a new filename in a different directory based on another. Craftr uses this function to generate object filenames.

Example:

>>> move('src/main.c', 'src', 'build/obj')
build/obj/main.c

path may be an iterable other than a string in which case the function is applied recursively to all its items and a list is returned instead of a string.

craftr.path.normpath(path, parent_dir=None, abs=True)

Normalizes a filesystem path. Also expands user variables. If a parent_dir is specified, a relative path is considered relative to that directory and converted to an absolute path. The default parent directory is the current working directory.

path may be an iterable other than a string in which case the function is applied recursively to all its items and a list is returned instead of a string.

If abs is True, the path is returned as an absolute path always, otherwise the path is returned in its original structure.

craftr.path.relpath(path, start='.', only_sub=False)

Like the original os.path.relpath() function, but with the only_sub parameter. If only_sub is True and path is not a subpath of start, the path is returned unchanged.

craftr.path.rmvsuffix(subject)

Given a filename, this function removes the the suffix of the filename and returns it. If the filename had no suffix to begin with, it is returned unchanged.

subject may be an iterable other than a string in which case the function is applied recursively to its items and a list is returned instead of a string.

craftr.path.setsuffix(subject, suffix)

Remove the existing suffix from subject and add suffix instead. The suffix must contain the dot at the beginning.

craftr.path.silent_remove(filename, is_dir=False)

Remove the file filename if it exists and be silent if it does not. Returns True if the file was removed, False if it did not exist. Raises an error in all other cases.

Parameters:

• filename – The path to the file or directory to remove.
• is_dir – If True, remove recursive (for directories).

craftr.path.split_path(path)

Splits path into a list of its parts.

class craftr.path.tempfile(suffix='', prefix='tmp', dir=None, text=False)

A better temporary file class where the close() function does not delete the file but only __exit__() does. Obviously, this allows you to close the file and re-use it with some other processing before it finally gets deleted.

This is especially important on Windows because apparently another process can’t read the file while it’s still opened in the process that created it.

from craftr import path, shell
with path.tempfile(suffix='c', text=True) as fp:
  fp.write('#include <stdio.h>\nint main() { }\n')
  fp.close()
  shell.run(['gcc', fp.name])

Parameters:

• suffix – The suffix of the temporary file.
• prefix – The prefix of the temporary file.
• dir – Override the temporary directory.
• text – True to open the file in text mode. Otherwise, it will be opened in binary mode.