stdpath Module

Module Description

Provides functionality for calculating paths which are compliant with the standard filesystem layout of a particular OS platform. Significant effort is made to comply with published filesystem standards as well as Python conventions. Currently, the following OS platforms are supported:

The functions contained in this module follow a regular naming convention, which provides hints as to their purpose. This convention can be expressed as follows.

  • Functions, which return paths where the core OS files are typically located, have the word oscore in their names.
  • Functions, which return paths where the OS distribution files are typically located, have the word osdist in their names.
  • Functions, which return paths associated with the default locations where a superuser or systems adminstrator would install software not packaged as part of the OS distribution, have the word common in their names.
  • The suffix install_root denotes that a returned path refers to a top-level directory under which other directories for things, such as configuration information and package resources, can be found.
  • The suffix pythonic denotes that a returned path is calculated in accordance with PEP 370 and may rely upon the site module.
  • The suffix base denotes that a returned path refers to an upper-level directory of a certain flavor, such as for configuration information or package resources, which is potentially common to many pieces of software and not tied to a particular one.
  • Functions, which return paths associated with the location of a particular piece of software, have the word my in their names.
  • Functions, which return paths relative to the current user’s home directory, have the word user in their names.

Most of the functions can be instructed to operate in a return None on failure mode or a raise exception on failure mode. By default, these functions return None on failure to determine a path. However, all functions raise a UnsupportedFilesystemLayout exception if they lack the logic necessary to support the filesystem layout of a particular OS platform.

Here is a list of higher level functions, which users of this module will most likely be interested in:

Please see their documentation and the Examples section for details on using them.

Exception Classes

class utilia.filesystem.stdpath.UnsupportedFilesystemLayout(reason_format, *reason_args)

Error if the standard filesystem layout associated with the current OS is unknown or unsupported.

Inherits from utilia.filesystem.Error_BASE and utilia.Exception_WithReason.

reason_args

Arguments to be substituted into the format string for presentation as the reason for the exception. The arguments are substituted into reason_format.

reason_format

Format string, containing zero or more format-style substitution tokens, for presentation as the reason for the exception. The substitions come from reason_args.

translated(translator)

Returns a translated string expressing the reason for the exception.

class utilia.filesystem.stdpath.UndeterminedFilesystemPath(reason_format, *reason_args)

Error if unable to ascertain a reasonably standard path for something.

Inherits from utilia.filesystem.Error_BASE and utilia.Exception_WithReason.

reason_args

Arguments to be substituted into the format string for presentation as the reason for the exception. The arguments are substituted into reason_format.

reason_format

Format string, containing zero or more format-style substitution tokens, for presentation as the reason for the exception. The substitions come from reason_args.

translated(translator)

Returns a translated string expressing the reason for the exception.

Elementary Functions

utilia.filesystem.stdpath.which_fs_layout()

Returns a classification of the expected filesystem layout according to the OS in use, if there is a classifier for that OS.

The possible filesystem layout classifications are as follows:

Classification Operating Systems
POSIX Linux
MacOS X Darwin
Windows Windows
Return type:string
Raises :UnsupportedFilesystemLayout, if there is no classifier implemented for the OS in use.
utilia.filesystem.stdpath.concatenated_software_path_fragment(software_name, vendor_name=None, version=None, error_on_none=False)

Returns a concatenation of the name of a software product with an optional name of the software product’s vendor and an optional version string for the software product as a filesystem path fragment typical for the operating system architecture.

Parameters:
  • software_name (string) – Consider the name of this software product when constructing a path fragment which identifies it.
  • vendor_name (string) – Consider the name of this software vendor when constructing a path fragment which identifies a software product.
  • version (string) – Consider this version string when constructing a path fragment which identifies a software product.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :

Public Base Paths

utilia.filesystem.stdpath.whereis_oscore_install_root(error_on_none=False)

Returns the path to the installation root for the core OS components, if it can be determined. Returns None, otherwise.

Environment variables or API calls may help determine this path on certain operating systems. In other cases, this path is fixed.

Below is a table of typical paths by filesystem layout classification:

Classification Path
POSIX /
MacOS X /
Windows C:\Windows\System32
Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_osdist_install_root(error_on_none=False)

Returns the path to the installation root of the OS distribution, if it can be determined. Returns None, otherwise.

Environment variables or API calls may help determine this path on certain operating systems. In other cases, this path is fixed.

Below is a table of typical paths by filesystem layout classification:

Classification Path
POSIX /usr
MacOS X /System
Windows C:\Windows
Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_common_install_root(error_on_none=False)

Returns the path to the typical default root for a shared or sitewide software installation by the superuser or systems administrator, if it can be determined. Returns None, otherwise.

Environment variables or API calls may help determine this path on certain operating systems. In other cases, this path is fixed.

Below is a table of typical paths by filesystem layout classification:

Classification Path
POSIX /usr/local
MacOS /Library
Windows C:\Program Files
Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_common_temp_base(error_on_none=False)

Returns the path to the temporary storage area available for use by everyone on the system.

Below is a table of typical paths by filesystem layout classification:

Classification Path
POSIX /tmp
MacOS X /tmp
Windows  
Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_oscore_config_base(error_on_none=False)

Returns the path to the typical top-level directory under which the configuration information resides for the core OS components, if it can be determined. Returns None, otherwise.

Below is a table of typical paths by filesystem layout classification:

Classification Path
POSIX /etc
MacOS X /System/Preferences
Windows C:\Windows\System32\Config
Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_osdist_config_base(error_on_none=False)

Returns the path to the typical top-level directory under which the configuration information resides for the core OS components, if it can be determined. Returns None, otherwise.

Below is a table of typical paths by filesystem layout classification:

Classification Path
POSIX /etc
MacOS X /System/Preferences
Windows  
Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_common_config_base(error_on_none=False)

Returns the path to the typical top-level directory under which the configuration information resides for software installed by the superuser or systems administrator, if it can be determined. Returns None, otherwise.

Below is a table of typical paths by filesystem layout classification:

Classification Path
POSIX /usr/local/etc
MacOS X /Library/Preferences
Windows  
Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :

User Base Paths

utilia.filesystem.stdpath.whereis_user_home(error_on_none=False)

Returns the path to the current user’s home directory, if it can be determined. Returns None, otherwise.

Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_user_temp_base(error_on_none=False)

Returns the path to the current user’s temporary storage area.

Parameters:

error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.

Return type:

string or None

Raises :

Other Base Paths

utilia.filesystem.stdpath.whereis_preferred_temp_base(prefer_common=False, error_on_none=False)

Returns:

Parameters:
  • prefer_common (boolean) – If True, the common path, if it exists, will be preferred over the user path.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :

Public Derived Paths

utilia.filesystem.stdpath.whereis_my_common_config_at_base(base_path, specific_path=None, error_on_none=False)

Returns a path to the directory, where the shared configuration information for the specific software is stored.

Parameters:
  • base_path (string) – Calculate path, using this path as the base.
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_common_config(specific_path=None, error_on_none=False)

Returns a path to the directory, where the shared configuration information for the specific software is stored. (This path is relative to the current OS platform’s standard shared location for configuration information.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_common_config_pythonic(specific_path=None, error_on_none=False)

Returns a path to the directory, where the shared configuration information for the specific software is stored. (This path is relative to the current Python’s installation base directory.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_common_resources_at_base(base_path, specific_path=None, error_on_none=False)

Returns a path to the directory, where the shared resources for the specific software are stored.

Parameters:
  • base_path (string) – Calculate path, using this path as the base.
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_common_resources(specific_path=None, error_on_none=False)

Returns a path to the directory, where the shared resources for the specific software are stored. (This path is relative to the current OS platform’s standard shared location for resources.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_common_resources_pythonic(specific_path=None, error_on_none=False)

Returns a path to the directory, where the shared resources for the specific software are stored. (This path is relative to the current Python’s installation base directory.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :

User Derived Paths

utilia.filesystem.stdpath.whereis_my_user_config_at_base(base_path, specific_path=None, error_on_none=False)

Returns a path to the directory, where the current user’s configuration information for the specific software is stored.

Parameters:
  • base_path (string) – Calculate path, using this path as the base.
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_user_config(specific_path=None, error_on_none=False)

Returns a path to the directory, where the current user’s configuration information for the specific software is stored. (This path is relative to the current OS platform’s standard per-user location for configuration information.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_user_config_pythonic(specific_path=None, error_on_none=False)

Returns a path to the directory, where the current user’s configuration information for the specific software are stored. (This path is relative to Python’s user base directory, as specified by PEP 370.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_user_resources_at_base(base_path, specific_path=None, error_on_none=False)

Returns a path to the directory, where the current user’s resources for the specific software are stored.

Parameters:
  • base_path (string) – Calculate path, using this path as the base.
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_user_resources(specific_path=None, error_on_none=False)

Returns a path to the directory, where the current user’s resources for the specific software are stored. (This path is relative to the current OS platform’s standard per-user location for resources.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_user_resources_pythonic(specific_path=None, error_on_none=False)

Returns a path to the directory, where the current user’s resources for the specific software are stored. (This path is relative to Python’s user base directory, as specified by PEP 370.)

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :

Other Derived Paths

utilia.filesystem.stdpath.whereis_my_saved_data_at_base(base_path, specific_path=None, error_on_none=False)

Returns a path to the directory where works, created by the current user, will be stored.

Parameters:
  • base_path (string) – Calculate path, using this path as the base.
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_saved_data(specific_path=None, error_on_none=False)

Returns a path to the directory where works, created by the user of the specific software, will be stored.

Uses whereis_user_home() internally.

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :
utilia.filesystem.stdpath.whereis_my_temp(specific_path=None, prefer_common=False, error_on_none=False)

Returns the path to the preferred temporary storage for the specific software.

The path calculation relies on results from the whereis_preferred_temp_base() and the concatenated_software_path_fragment() functions.

Parameters:
  • specific_path (string) – Calculate path, using this path as the most specific part.
  • prefer_common (boolean) – If True, the common path, if it exists, will be preferred over the user path.
  • error_on_none (boolean) – If True, cause an exception to be raised if the return value would be None.
Return type:

string or None

Raises :

Examples

Todo

Create examples.