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`.
`get_common_egse_root`	Returns the absolute path to the installation directory for the Common-EGSE.
`get_resource_dirs`	Define directories that contain resources like images, icons, and data files.
`get_resource_path`	Searches for a data file (resource) with the given name.
`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=None)

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`	`str`	the top level folder to search [default=common-egse-root]	`None`

Returns:

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

find_dirs ¶

find_dirs(pattern, root=None)

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 [default=common-egse-root]	`None`

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=None, 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, 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`	`str`	the top level folder to search [default=common-egse-root]	`None`
`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=None, 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, 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`	`str`	the top level folder to search [default=common-egse-root]	`None`
`in_dir`	`str`	the 'leaf' directory in which the file shall be	`None`

Returns:

Type	Description
	Paths of files matching pattern, from root.

find_first_occurrence_of_dir ¶

find_first_occurrence_of_dir(pattern, root=None)

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.

Parameters:

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

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.

get_common_egse_root `cached` ¶

get_common_egse_root(path=None)

Returns the absolute path to the installation directory for the Common-EGSE.

The algorithm first tries to determine the path from the environment variable PLATO_COMMON_EGSE_PATH. If this environment variable doesn't exist, the algorithm tries to determine the path automatically from (1) the git root if it is a git repository, or (2) from the location of this module assuming the installation is done from the GitHub distribution.

When the optional argument path is given, that directory will be used to start the search for the root folder.

At this moment the algorithm does not cache the egse_path in order to speed up the successive calls to this function.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	a directory as a Path or str [optional]	`None`

Returns:

Name	Type	Description
`Path`	`Optional[PurePath]`	the absolute path to the Common-EGSE installation directory or None

get_resource_dirs ¶

get_resource_dirs(root_dir=None)

Define directories that contain resources like images, icons, and data files.

Resource directories can have the following names: resources, data, icons, or images. This function checks if any of the resource directories exist in the project root directory, in the root_dir that is given as an argument or in the src/egse sub-folder.

So, the directories that are searched for the resource folders are:

root_dir or the project's root directory
the src/egse sub-folder of one of the above

For all existing directories the function returns the absolute path.

Parameters:

Name	Type	Description	Default
`root_dir`	`str`	the directory to search for resource folders	`None`

Returns:

Type	Description
`List[Path]`	a list of absolute Paths.

get_resource_path ¶

get_resource_path(name, resource_root_dir=None)

Searches for a data file (resource) with the given name.

When resource_root_dir is not given, the search for resources will start at the root folder of the project (using the function get_common_egse_root()). Any other root directory can be given, e.g. if you want to start the search from the location of your source code file, use Path(__file__).parent as the resource_root_dir argument.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the resource that is requested	required
`resource_root_dir`	`str`	the root directory where the search for resources should be started	`None`

Returns:

Type	Description
`PurePath`	the absolute path of the data file with the given name. The first name that matches is returned. If no file with the given name or path exists, a FileNotFoundError is raised.

set_logger_levels ¶

set_logger_levels(logger_levels=None)

Set the logging level for the given loggers.

egse.config

WorkingDirectory ¶

path property ¶

find_dir ¶

find_dirs ¶

find_file ¶

find_files ¶

find_first_occurrence_of_dir ¶

find_root ¶

get_common_egse_root cached ¶

get_resource_dirs ¶

get_resource_path ¶

set_logger_levels ¶

path `property` ¶

get_common_egse_root `cached` ¶