egse.config

cgse-common

This code is part of the cgse-common package.

egse.config

This module provides convenience functions to properly configure the CGSE and to find paths and resources.

Classes:

Name	Description
WorkingDirectory	WorkingDirectory is a context manager to temporarily change the working directory while

Functions:

Name	Description
find_dir	Find the first folder that matches the given pattern.
find_dirs	Generator for returning directory paths from a walk started at root and matching pattern.
find_file	Find the path to the given file starting from the root directory of the
find_files	Generator for returning file paths from a top folder, matching the pattern.
find_first_occurrence_of_dir	Returns the full path of the directory that first matches the pattern. The directory hierarchy is
find_root	Find the root folder based on the files in tests.
set_logger_levels	Set the logging level for the given loggers.

WorkingDirectory

WorkingDirectory(path)

WorkingDirectory is a context manager to temporarily change the working directory while executing some code.

This context manager has a property path which returns the absolute path of the current directory.

Parameters:

Name	Type	Description	Default
path	(str, Path)	the folder to change to within this context	required

Raises:

Type	Description
ValueError	when the given path doesn't exist.

Example

with WorkingDirectory(find_dir("/egse/images")) as wdir:
    for file in wdir.path.glob('*'):
        assert file.exists()  # do something with the image files

Attributes:

Name	Type	Description
path		Resolve and return the current Path of the context.

path property

path

Resolve and return the current Path of the context.

find_dir

find_dir(pattern, root)

Find the first folder that matches the given pattern.

Note that if there are more folders that match the pattern in the distribution, this function only returns the first occurrence that is found, which might not be what you want. To be sure only one folder is returned, use the find_dirs() function and check if there is just one item returned in the list.

Parameters:

Name	Type	Description	Default
pattern	str	pattern to match (use * for wildcard)	required
root	Path | str	the top level folder to search	required

Returns:

Type	Description
Path | None	the first occurrence of the directory pattern or None when not found.

find_dirs

find_dirs(pattern, root)

Generator for returning directory paths from a walk started at root and matching pattern.

The pattern can contain the asterisk '*' as a wildcard.

The pattern can contain a directory separator '/' which means the last part of the path needs to match these folders.

Parameters:

Name	Type	Description	Default
pattern	str	pattern to match (use * for wildcard)	required
root	str	the top level folder to search	required

Returns:

Name	Type	Description
Generator	None	Paths of folders matching pattern, from root.

Example

>>> for folder in find_dirs("/egse/images"):
...     assert folder.match('*/egse/images')

>>> folders = list(find_dirs("/egse/images"))
>>> assert len(folders)

find_file

find_file(name, root, in_dir=None)

Find the path to the given file starting from the root directory of the distribution.

Note that if there are more files with the given name found in the distribution, this function only returns the first file that is found, which might not be what you want. To be sure only one file is returned, use the find_files() function and check if there is just one file returned in the list.

When the file shall be in a specific directory, use the in_dir keyword. This requires that the path ends with the given string in in_dir.

>>> file_pattern = 'EtherSpaceLink*.dylib'
>>> in_dir = 'lib/CentOS-7'
>>> file = find_file(file_pattern, root='.', in_dir=in_dir)
>>> assert file.match("*/lib/CentOS-7/EtherSpace*")

Parameters:

Name	Type	Description	Default
name	str	the name of the file	required
root	Path | str	the top level folder to search	required
in_dir	str	the 'leaf' directory in which the file shall be	None

Returns:

Type	Description
Path | None	the first occurrence of the file or None when not found.

find_files

find_files(pattern, root, in_dir=None)

Generator for returning file paths from a top folder, matching the pattern.

The top folder can be specified as e.g. __file__ in which case the parent of that file will be used as the top root folder. Note that when you specify '.' as the root argument the current working directory will be taken as the root folder, which is probably not what you intended.

When the file shall be in a specific directory, use the in_dir keyword. This requires that the path ends with the given string in in_dir.

>>> file_pattern = 'EtherSpaceLink*.dylib'
>>> in_dir = 'lib/CentOS-7'
>>> for file in find_files(file_pattern, root='.', in_dir=in_dir):
...     assert file.match("*lib/CentOS-7/EtherSpaceLink*")

Parameters:

Name	Type	Description	Default
pattern	str)	sorting pattern (use * for wildcard)	required
root	Path | str	the top level folder to search	required
in_dir	str	the 'leaf' directory in which the file shall be	None

Returns:

Type	Description
None	Paths of files matching pattern, from root.

find_first_occurrence_of_dir

find_first_occurrence_of_dir(pattern, root)

Returns the full path of the directory that first matches the pattern. The directory hierarchy is traversed in alphabetical order. The pattern is matched first against all directories in the root folder, if there is no match, the first folder in root is traversed until a match is found. If no match is found, the second folder in root is traversed.

Note that the pattern may contain parent directories, like /egse/data/icons or egse/*/icons, in which case the full pattern is matched.

In the case that you pass an empty string for the root argument, it will resolve into the current working directory.

Parameters:

Name	Type	Description	Default
pattern	str	a filename pattern	required
root	Path | str	the root folder to start the hierarchical search	required

Returns:

Type	Description
Path | None	The full path of the matched pattern or None if no match could be found.

find_root

find_root(path, tests=(), default=None)

Find the root folder based on the files in tests.

The algorithm crawls backward over the directory structure until one of the items in tests is matched. and it will return that directory as a Path.

When no root folder can be determined, the default parameter is returned as a Path (or None).

When nothing is provided in tests, all matches will fail and the default parameter will be returned.

Parameters:

Name	Type	Description	Default
path	Union[str, PurePath] | None	folder from which the search is started	required
tests	Tuple[str, ...]	names (files or dirs) to test for existence	()
default	str	returned when no root is found	None

Returns:

Type	Description
Union[PurePath, None]	a Path which is the root folder.

set_logger_levels

set_logger_levels(logger_levels=None)

Set the logging level for the given loggers.