The path_tools module

A set of tools for managing paths.

The path_tools module provides auxiliary methods for converting between different path names. It’s main function is to convert path names indicated relative to the Transport directory to absolute path names.

Functions

src.tools.path_tools.flatten(nested)

Takes a nested list and returns a flattened list. The output is always a single-level list, and the input can be a tuple, a list, a string, an uncombined sequence of strings, or any nested combination of these.

Parameters :

nested : sequence

A (possibly) nested sequence of strings. It can be entered as a list, a single string, a tuple, or simply a comma-separated series of arguments.

Returns :

list :

A single-level list of the same elements.

src.tools.path_tools.unrel(*args, **kwargs)

Expand a relative path into an absolute path.

Merges the components in args (which may be a list, a tuple, or simply a comma-separated series) and assembles a full path, assuming they are paths relative to the project root.

Parameters :

args : sequence

A (possibly) nested sequence of strings representing path elements, relative to the root of the Transport project tree. It can be entered as a list, a single string, a tuple, or simply a comma-separated series of arguments.

Returns :

str :

The absolute path of the specified file.

src.tools.path_tools.rel(path, asList=False)

Convert an absolute path to one relative to the project home.

Parameters :

path : str

The absolute path to convert to a relative path.

asList : bool

Whether to return the result as a list. If False, the path will be returned as a string. The default is False.

Returns :

str or list(str) :

The path relative to the project home. If asList is True, the result is a list of path components. If it is False, the result is a relative path string. If path is not a child of the project home, None is returned.

src.tools.path_tools.pathToImportString(path, isRelative=True, importItem=None, importFrom=True)

Convert a path to a string suitable for importing.

Parameters :

path : str

The path of a python module.

isRelative : bool

Whether path is relative to the project home. If False, path will be taken to be an absolute path. The default is True.

importItem : str

The name of the item to be imported.

importFrom : bool

If importItem is None: Whether the import string should be of the form from [package] import [module]. If False, the import string will be of the form import [package].[module].

If importItem is not None: whether the import string should be of the form from [package].[module] import [importItem]. If False, the import string will be of the form import [package].[module].[importItem].

The default is True.

Returns :

tuple (str, str) :

A two element tuple where the first element is a string containing the requested components separated by periods, and the second is a string which can be passed to exec to actually perform the import.

src.tools.path_tools.normalizePath(path)

Replace all backslashes with front-slashes.

Parameters :

path : str

A file path to normalize.

Returns :

str :

The path with all front-slashes.

src.tools.path_tools.splitPath(path)

Return the path split into its components.

Parameters :

path : str

A file path.

Returns :

list of str :

A list of strings representing the components of path.

src.tools.path_tools.lsAbsolute(directory, filesOnly=False)

List the contents of a directory specified by an absolute path.

Parameters :

directory : str

The absolute path of the directory to list.

filesOnly : bool

Whether to ignore subdirectories of directory.

Returns :

list of str :

The contents of directory as a list of strings.

src.tools.path_tools.ls(directory, filesOnly=False)

List the contents of a directory specified relative to the project home.

Parameters :

directory : str

The relative (to the project home) path of the directory to list.

filesOnly : bool

Whether to ignore subdirectories of directory.

Returns :

list(str) :

The contents of directory as a list of strings.

src.tools.path_tools.getNextScan(directory)

Determine the next scan number.

Determine the next unused scan number, assuming that scans are indicated by ‘sNNN’ or ‘sNNNN’, where N is a digit.

Parameters :

directory : str

The absolute path of the directory of data files.

Returns :

str :

A string representing the next scan number. It’s format is “sNNN”, where N is an integer.

src.tools.path_tools.appendDigitsAsNecessary(folder, basename, extension='xdat')

Append digits to avoid filename clashes.

Append incrementally larger digits to the name of a file until the name does not collide with existing files.

Parameters :

folder : str

The folder in which the data file will be saved. It should not include a trailing slash.

basename : str

The base name of the data file. It should include a scan number, if applicable, but it should not include an extension.

extension : str

The intended extension of the filename. It should not include a leading period.

Returns :

str :

The base name for the data file with appropriate digits added and no extension.

src.tools.path_tools.getFilesPostprocessor()

Return a dictionary containing data about postprocessor scripts.

Returns :

dict :

A dictionary in which the keys are strings representing an absolute filename without an extension. The value for each key is a dictionary with three keys: ‘py’, ‘pyc’, ‘pyo’. Each of the values is a bool specifying whether the base file with the corresponding extension exists.

src.tools.path_tools.createHomePathOld()

Create the home path the old way if necessary.

src.tools.path_tools.createHomePath()

Create the home path if necessary.