hup.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:

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.

*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_config_dir:
user_cache_dir:	Cache directory of user
	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¶

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:

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.

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.

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:

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.

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:

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.

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.

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