flib.base.env module

Environmental integration.

basename(*args, pkgname: Optional[str] = None) → str

Extract file basename from a path like structure.

Parameters:*args – Path like arguments, respectively given by a tree of strings, which can be joined to a path.
Returns:String containing basename of file.

Examples

>>> filename(('a', ('b', 'c')), 'base.ext')
'base'
clear_filename(fname: str) → str

Clear filename from invalid characters.

Parameters:fname – Arbitrary string, which is be cleared from invalid filename characters.
Returns:String containing valid path syntax.

Examples

>>> clear_filename('3/\nE{$5}.e')
'3E5.e'
copytree(source: Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]]]]], target: Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]]]]], pkgname: Optional[str] = None) → None

Copy directory structure from given source to target directory.

Parameters:
  • source – Path like structure, which comprises the path of a source folder
  • target – Path like structure, which comprises the path of a destination folder
Returns:

True if the operation was successful.

expand(*args, udict: Optional[Dict[str, Any]] = None, pkgname: Optional[str] = None, envdirs: bool = True) → pathlib.Path

Expand path variables.

Parameters:
  • *args – Path like arguments, respectively given by a tree of strings, which can be joined to a path.
  • udict – dictionary for user variables. Thereby the keys in the dictionary are encapsulated by the symbol ‘%’. The user variables may also include references.
  • envdirs – Boolen value which determines if environmental path variables are expanded. For a full list of valid environmental path variables see ‘.env.get_dirs’. Default is True
Returns:

String containing valid path syntax.

Examples

>>> expand('%var1%/c', 'd', udict = {'var1': 'a/%var2%', 'var2': 'b'})
'a\\b\\c\\d'
fileext(*args, pkgname: Optional[str] = None) → str

Fileextension of file.

Parameters:*args – Path like arguments, respectively given by a tree of strings, which can be joined to a path.
Returns:String containing fileextension of file.

Examples

>>> fileext(('a', ('b', 'c')), 'base.ext')
'ext'
filename(*args, pkgname: Optional[str] = None) → str

Extract file name from a path like structure.

Parameters:*args – Path like arguments, respectively given by a tree of strings, which can be joined to a path.
Returns:String containing normalized directory path of file.

Examples

>>> filename(('a', ('b', 'c')), 'base.ext')
'base.ext'
get_cwd() → pathlib.Path

Get path of current working directory.

Returns:Path of current working directory.
get_dir(dirname: str, *args, pkgname: Optional[str] = None, **kwds) → pathlib.Path

Get application specific environmental directory by name.

This function returns application specific system directories by platform independent names to allow platform independent storage for caching, logging, configuration and permanent data storage.

Parameters:
  • dirname

    Environmental directory name. Allowed values are:

    user_cache_dir:Cache directory of user
    user_config_dir:
     Configuration directory of user
    user_data_dir:Data directory of user
    user_log_dir:Logging directory of user
    site_config_dir:
     Site global configuration directory
    site_data_dir:Site global data directory
    site_package_dir:
     Site global package directory
    site_temp_dir:Site global directory for temporary files
    package_dir:Current package directory
    package_data_dir:
     Current package data directory
  • *args – Optional arguments that specify the application, as required by the function ‘.env.update_dirs’.
  • **kwds – Optional keyword arguments that specify the application, as required by the function ‘.env.update_dirs’.
Returns:

String containing path of environmental directory or None if the pathname is not supported.

get_dirname(*args, pkgname: Optional[str] = None) → str

Extract directory name from a path like structure.

Parameters:*args – Path like arguments, respectively given by a tree of strings, which can be joined to a path.
Returns:String containing normalized directory path of file.

Examples

>>> get_dirname(('a', ('b', 'c'), 'd'), 'base.ext')
'a\\b\\c\\d'
get_dirs(*args, pkgname: Optional[str] = None, **kwds) → Dict[str, Any]

Get application specific environmental directories.

This function returns application specific system directories by platform independent names to allow platform independent storage for caching, logging, configuration and permanent data storage.

Parameters:
  • *args – Optional arguments that specify the application, as required by the function ‘.env.update_dirs’.
  • **kwds – Optional keyword arguments that specify the application, as required by the function ‘.env.update_dirs’.
Returns:

Dictionary containing paths of application specific environmental directories.

get_encoding() → str

Get preferred encoding used for text data.

This is a wrapper function to the standard library function locale.getpreferredencoding(). This function returns the encoding used for text data, according to user preferences. User preferences are expressed differently on different systems, and might not be available programmatically on some systems, so this function only returns a guess.

Returns:String representing the preferred encoding used for text data.
get_home() → pathlib.Path

Get path of current users home directory.

Returns:Path of current users home directory.
get_hostname() → str

Get hostname of the computer.

This is a wrapper function to the standard library function platform.node(). This function returns the computer’s hostname. If the value cannot be determined, an empty string is returned.

Returns:String representing the computer’s hostname or None.
get_osname() → str

Get name of the Operating System.

This is a wrapper function to the standard library function platform.system(). This function returns the OS name, e.g. ‘Linux’, ‘Windows’, or ‘Java’. If the value cannot be determined, an empty string is returned.

Returns:String representing the OS name or None.
get_temp_dir() → pathlib.Path

Get path to temporary file within the package temp directory.

get_temp_file(suffix: Optional[str] = None) → pathlib.Path

Get path to temporary file within the package temp directory.

get_username() → str

Login name of the current user.

This is a wrapper function to the standard library function getpass.getuser(). This function checks the environment variables LOGNAME, USER, LNAME and USERNAME, in order, and returns the value of the first one which is set to a non-empty string. If none are set, the login name from the password database is returned on systems which support the pwd module, otherwise, an exception is raised.

Returns:String representing the login name of the current user.
get_var(varname: str, *args, pkgname: Optional[str] = None, **kwds) → Optional[str]

Get environment or application variable.

Environment variables comprise static and runtime properties of the operating system like ‘username’ or ‘hostname’. Application variables in turn, are intended to describe the application distribution by authorship information, bibliographic information, status, formal conditions and notes or warnings. For mor information see PEP 345.

Parameters:
  • varname

    Name of environment variable. Typical application variable names are: ‘name’: The name of the distribution ‘version’: A string containing the distribution’s version number ‘status’: Development status of the distributed application.

    Typical values are ‘Prototype’, ‘Development’, or ‘Production’
    ’description’: A longer description of the distribution that can
    run to several paragraphs.
    ’keywords’: A list of additional keywords to be used to assist
    searching for the distribution in a larger catalog.
    ’url’: A string containing the URL for the distribution’s
    homepage.

    ’license’: Text indicating the license covering the distribution ‘copyright’: Notice of statutorily prescribed form that informs

    users of the distribution to published copyright ownership.
    ’author’: A string containing the author’s name at a minimum;
    additional contact information may be provided.
    ’email’: A string containing the author’s e-mail address. It can
    contain a name and e-mail address, as described in RFC 822.
    ’maintainer’: A string containing the maintainer’s name at a
    minimum; additional contact information may be provided.

    ’company’: The company, which created or maintains the distribution. ‘organization’: The organization, twhich created or maintains the

    distribution.
    ’credits’: list with strings, acknowledging further contributors,
    Teams or supporting organizations.
  • *args – Optional arguments that specify the application, as required by the function update_vars().
  • pkgname
  • **kwds – Optional keyword arguments that specify the application, as required by the function update_vars().
Returns:

String representing the value of the application variable.

get_vars(*args, pkgname: Optional[str] = None, **kwds) → Dict[str, Any]

Get dictionary with environment and application variables.

Environment variables comprise static and runtime properties of the operating system like ‘username’ or ‘hostname’. Application variables in turn, are intended to describe the application distribution by authorship information, bibliographic information, status, formal conditions and notes or warnings. For mor information see PEP 345.

Parameters:
  • *args – Optional arguments that specify the application, as required by update_vars().
  • **kwds – Optional keyword arguments that specify the application, as required by update_vars().
Returns:

Dictionary containing application variables.

is_dir(path: Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]]]]], pkgname: Optional[str] = None) → bool

Determine if given path points to a directory.

Extends pathlib.Path.is_dir() by nested paths and path variable expansion.

Parameters:path – Path like structure, which is expandable to a valid path
Returns:True if the path points to a regular file (or a symbolic link pointing to a regular file), False if it points to another kind of file.
is_file(path: Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]]]]], pkgname: Optional[str] = None) → bool

Determine if given path points to a file.

Extends pathlib.Path.is_file() by nested paths and path variable expansion.

Parameters:path – Path like structure, which is expandable to a valid path.
Returns:True if the path points to a directory (or a symbolic link pointing to a directory), False if it points to another kind of file.
join_path(*args) → pathlib.Path

Join nested iterable path-like structure to single path object.

Parameters:*args – Arguments containing nested iterable paths of strings and PathLike objects.
Returns:Single Path comprising all arguments.

Examples

>>> join_path(('a', ('b', 'c')), 'd')
Path('a\\b\\c\\d')
match_paths(paths: List[Union[str, os.PathLike]], pattern: str) → List[Union[str, os.PathLike]]

Filter pathlist to matches with wildcard pattern.

Parameters:
  • paths – List of paths, which is filtered to matches with pattern.
  • pattern – String pattern, containing Unix shell-style wildcards: ‘*’: matches arbitrary strings ‘?’: matches single characters [seq]: matches any character in seq [!seq]: matches any character not in seq
Returns:

Filtered list of paths.

Examples

>>> match_paths([Path('a.b'), Path('b.a')], '*.b')
[Path('a.b')]
mkdir(*args, pkgname: Optional[str] = None) → bool

Create directory.

Parameters:*args – Path like structure, which comprises the path of a new directory
Returns:True if the directory already exists, or the operation was successful.
rmdir(*args, pkgname: Optional[str] = None) → bool

Remove directory.

Parameters:*args – Path like structure, which identifies the path of a directory
Returns:True if the directory could be deleted
touch(path: Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]], Sequence[Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]]]]], parents: bool = True, mode: int = 438, exist_ok: bool = True, pkgname: Optional[str] = None) → bool

Create an empty file at the specified path.

Parameters:
  • path – Nested path-like object, which represents a valid filename in the directory structure of the operating system.
  • parents – Boolean value, which determines if missing parents of the path are created as needed.
  • mode – Integer value, which specifies the properties if the file. For more information see os.chmod().
  • exist_ok – Boolean value which determines, if the function returns False, if the file already exists.
Returns:

True if the file could be created, else False.

update_dirs(appname: Optional[str] = None, appauthor: Union[str, bool, None] = None, version: Optional[str] = None, pkgname: Optional[str] = None, **kwds) → None

Update application specific directories from name, author and version.

This function retrieves application specific directories from the package appdirs. Additionally the directory ‘site_package_dir’ is retrieved fom the standard library package distutils and ‘package_dir’ and ‘package_data_dir’ from the current top level module.

Parameters:
  • appname – is the name of application. If None, just the system directory is returned.
  • appauthor – is the name of the appauthor or distributing body for this application. Typically it is the owning company name. You may pass False to disable it. Only applied in windows.
  • version – is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be “<major>.<minor>”. Only applied when appname is present.
  • **kwds – Optional directory name specific keyword arguments. For more information see appdirs.
update_vars(filepath: Union[str, os.PathLike, None] = None, pkgname: Optional[str] = None) → None

Update environment and application variables.

Environment variables comprise static and runtime properties of the operating system like ‘username’ or ‘hostname’. Application variables in turn, are intended to describe the application distribution by authorship information, bibliographic information, status, formal conditions and notes or warnings. For mor information see PEP 345.

Parameters:filepath – Valid filepath to python module, that contains the application variables as module attributes. By default the current top level module is used.