def 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.
"""
user_id = None
user_home_path = None
fsl = which_fs_layout( )
if fsl in [ "POSIX", "MacOS X", ]:
user_id = envvars.get( "USER", None )
user_home_path = expand_user_path( "~" )
if "~" == user_home_path: user_home_path = None
elif fsl in [ "Windows", ]:
user_id = envvars.get( "UserName", None )
user_home_path = envvars.get( "UserProfile", None )
else: __raise_UnsupportedFilesystemLayout( fsl )
if (None is user_home_path) and error_on_none:
if user_id:
error_reason_format = \
_TD_( "Unknown home directory for user '{0}'." )
error_reason_args = [ user_id ]
else:
error_reason_format = _TD_( "Unknown ID of current user." )
error_reason_args = [ ]
raise UndeterminedFilesystemPath(
error_reason_format, *error_reason_args
)
return user_home_path
def 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.
"""
# Note: Conversion of whitespaces to underscores is performed on POSIX
# operating systems to facilitate command-line navigation.
# This is considered to be less important on the MacOS X and
# Windows operating systems, which ship with Finder and Explorer
# respectively.
# Note: No conversion of decimal points to underscores is performed on
# Windows operating systems, because directory names are being
# returned rather than file names and so there are no concerns about
# name extensions.
path_fragment = None
error_reason_format = _TD_( "Empty software-specific path fragment." )
fsl = which_fs_layout( )
if not software_name:
error_reason_format = _TD_( "Software name is unspecified." )
else:
if vendor_name:
vendor_name = vendor_name.strip( )
if fsl in [ "POSIX", ]:
vendor_name = __whitespace_to_underscore( vendor_name )
elif fsl in [ "MacOS X", ]: pass
elif fsl in [ "Windows", ]: pass
else: __raise_UnsupportedFilesystemLayout( fsl )
software_name = software_name.strip( )
if fsl in [ "POSIX", ]:
software_name = __whitespace_to_underscore( software_name )
elif fsl in [ "MacOS X", ]: pass
elif fsl in [ "Windows", ]: pass
else: __raise_UnsupportedFilesystemLayout( fsl )
if version:
version = version.strip( )
if fsl in [ "POSIX", ]:
version = __whitespace_to_underscore( version )
elif fsl in [ "MacOS X", ]: pass
elif fsl in [ "Windows", ]: pass
else: __raise_UnsupportedFilesystemLayout( fsl )
path_fragment = \
join_filtered_path( vendor_name, software_name, version )
if error_on_none and (None is path_fragment):
raise UndeterminedFilesystemPath( error_reason_format )
return path_fragment
def 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:
.. csv-table::
:header: "Classification", "Path"
:widths: 20, 80
"POSIX", "/tmp"
"MacOS X", "/tmp"
"Windows", ""
"""
temp_base_path = None
location = _TD_( "common temporary storage area" )
fsl = which_fs_layout( )
if fsl in [ "POSIX", "MacOS X" ]: temp_base_path = "/tmp"
elif fsl in [ "Windows", ]: pass
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, temp_base_path, location
)
return temp_base_path
def 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
:py:func:`whereis_preferred_temp_base` and the
:py:func:`concatenated_software_path_fragment` functions.
"""
base_path = None
full_path = None
evname = None
base_path = \
whereis_preferred_temp_base(
error_on_none = error_on_none, prefer_common = prefer_common
)
full_path = join_filtered_path( base_path, specific_path )
__decide_upon_error_on_none(
error_on_none, full_path,
_TD_( "temporary storage area" ),
evname, specific_path
)
return full_path
def 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.
"""
fsl = which_fs_layout( )
full_path = None
evname = None
if base_path:
if fsl in [ "POSIX", ]: pass
elif fsl in [ "MacOS X", "Windows", ]:
full_path = \
join_filtered_path( base_path, "Documents", specific_path )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, full_path, _TD_( "saved data" ), evname, specific_path
)
return full_path
def _whereis_common_installation( context ):
"""
Returns path to the appropriate Windows "program files" folder in
the context of the bit width for the Windows OS.
"""
import platform
os_bit_width = 64 if "64bit" in platform.architecture( ) else 32
app_bit_width = 64 if sys.maxsize > 2 ** 32 else 32
# TODO: Get desired bit widths from context,
# setting context defaults as computed above.
evname = None
if 64 == os_bit_width:
if 64 == app_bit_width: evname = "ProgramFiles"
else: evname = "ProgramFiles(x86)"
else: evname = "ProgramFiles"
the_path = _envvars.get( evname )
if None is the_path:
context.raise_UndeterminedPathError(
_TD_( "Windows common installation directory" )
)
return the_path
def 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:
.. csv-table::
:header: "Classification", "Path"
:widths: 20, 80
"POSIX", "/usr/local/etc"
"MacOS X", "/Library/Preferences"
"Windows", ""
"""
cbp_evname = None
config_base_path = None
location = _TD_( "common configuration information" )
fsl = which_fs_layout( )
if fsl in [ "POSIX", ]: config_base_path = "/usr/local/etc"
elif fsl in [ "MacOS X", ]: config_base_path = "/Library/Preferences"
elif fsl in [ "Windows", ]: pass
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, config_base_path, location, cbp_evname
)
return config_base_path
def 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.
"""
fsl = which_fs_layout( )
full_path = None
evname = None
if base_path:
if fsl in [ "POSIX", ]:
if "/" == base_path:
full_path = \
join_filtered_path( base_path, "etc", specific_path )
else:
full_path = \
join_filtered_path( base_path, "share", specific_path )
elif fsl in [ "MacOS X", ]:
base_path_orig = base_path
base_path = __computed_MacOS_X_python_prefix( base_path )
if base_path.startswith( "/System" ): base_path = "/Library"
posix_flavor = \
(base_path_orig == base_path) and ("/Library" != base_path)
if posix_flavor:
if "/" == base_path:
full_path = \
join_filtered_path( base_path, "etc", specific_path )
else:
full_path = \
join_filtered_path( base_path, "share", specific_path )
else:
full_path = \
join_filtered_path(
base_path, "Application Support", specific_path
)
elif fsl in [ "Windows", ]:
if specific_path:
full_path = \
join_filtered_path( base_path, specific_path, "Resources" )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, full_path,
_TD_( "shared resources" ),
evname, specific_path
)
return full_path
def __decide_upon_error_on_none(
error_on_none, path,
location, evname = None, specific_path = None
):
"""
Raises an 'UndeterminedFilesystemPath' exception, if the
'error_on_none' argument is true and the supplied path is empty.
"""
if error_on_none and (None is path):
if specific_path:
if evname:
error_reason_format = _TD_(
"Undetermined path to {0} for '{1}'."
" (Environment variable, '{2}', not set.)"
)
error_reason_args = [ location, specific_path, evname ]
else:
error_reason_format = _TD_(
"Undetermined path to {0} for '{1}'."
)
error_reason_args = [ location, specific_path ]
else:
if evname:
error_reason_format = _TD_(
"Undetermined path to {0}."
" (Environment variable, '{1}', not set.)"
)
error_reason_args = [ location, evname ]
else:
error_reason_format = _TD_( "Undetermined path to {0}." )
error_reason_args = [ location ]
raise UndeterminedFilesystemPath(
error_reason_format, *error_reason_args
)
def _whereis_user_Python_package( context ):
"""
Returns the path to a particular Python package relative to the user's
site packages directory specified by :pep:`370` and provided by the
:py:mod:`site <CPython3:site>` module.
"""
python_package_name = context.get_with_default( "Python_package_name" )
if None is python_package_name:
context.raise_UndeterminedPathError(
_TD_( "Python package" ), specify_software = True
)
return _join_path( site.USER_SITE, python_package_name )
def whereis_preferred_temp_base(
prefer_common = False,
error_on_none = False
):
"""
Returns:
* the result from a call to :py:func:`whereis_common_temp_base`,
if it is not ``None`` and the ``prefer_common`` argument is
``True``;
* the result from a call to :py:func:`whereis_user_temp_base`,
if it is not ``None``;
* the result from a call to :py:func:`whereis_common_temp_base`,
if it is not ``None``;
* or ``None``, if all else fails.
"""
temp_base_path = None
error_reason_format = \
_TD_( "Undetermined path to preferred temporary storage." )
error_reason_args = [ ]
utbp = stbp = None
try: utbp = whereis_user_temp_base( error_on_none = error_on_none )
except UndeterminedFilesystemPath as exc:
error_reason_format = exc.error_reason_format
error_reason_args = exc.error_reason_args
try: stbp = whereis_common_temp_base( error_on_none = error_on_none )
except UndeterminedFilesystemPath as exc:
error_reason_format = exc.error_reason_format
error_reason_args = exc.error_reason_args
if stbp and prefer_common: temp_base_path = stbp
elif utbp: temp_base_path = utbp
elif stbp: temp_base_path = stbp
if (None is temp_base_path) and error_on_none:
raise UndeterminedFilesystemPath(
error_reason_format, *error_reason_args
)
return temp_base_path
def 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.)
"""
fsl = which_fs_layout( )
base_path = sys.prefix
full_path = None
evname = None
if base_path:
# NOTE: Possible PEP 370 violation.
if fsl in [ "POSIX", ]:
full_path = join_filtered_path( base_path, "etc", specific_path )
elif fsl in [ "MacOS X", ]:
base_path_orig = base_path
base_path = __computed_MacOS_X_python_prefix( base_path )
if base_path.startswith( "/System" ): base_path = "/Library"
posix_flavor = \
(base_path_orig == base_path) and ("/Library" != base_path)
if posix_flavor:
full_path = \
join_filtered_path( base_path, "etc", specific_path )
else:
full_path = \
join_filtered_path(
base_path, "Preferences", specific_path
)
elif fsl in [ "Windows", ]:
full_path = \
join_filtered_path( base_path, "Config", specific_path )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, full_path,
_TD_( "Pythonic shared configuration information" ),
evname, specific_path
)
return full_path
def _whereis_common_Python_package( context ):
"""
Returns the path to a particular Python package relative to the primary
site packages directory for a given Python installation and version.
"""
python_package_name = context.get_with_default( "Python_package_name" )
if None is python_package_name:
context.raise_UndeterminedPathError(
_TD_( "Python package" ), specify_software = True
)
return _join_path(
context.get_with_default( "Python_prefix_path" ),
"Lib",
"site-packages",
python_package_name
)
def whereis_temp( self, context = None ):
""" """
context = self._find_context( context )
base_path, specific_path = \
self._choose_common_path_parts( context )
if base_path and context.get_with_default( "temp_on_base_path" ):
base_path = _join_path( base_path, "Temp" )
else: base_path = None
if None is base_path:
base_path = _envvars.get( "TMP", _envvars.get( "TEMP" ) )
if None is base_path:
context.raise_UndeterminedPathError(
_TD_( "temporary storage" )
)
if specific_path: return _join_path( base_path, specific_path )
return base_path
def whereis_user_temp_base( error_on_none = False ):
"""
Returns the path to the current user's temporary storage area.
"""
utbp_evname = None
temp_base_path = None
location = _TD_( "user-specific temporary storage area" )
fsl = which_fs_layout( )
if fsl in [ "POSIX", "MacOS X", ]: pass
elif fsl in [ "Windows", ]:
utbp_evname = "Temp"
temp_base_path = envvars.get( utbp_evname, None )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, temp_base_path, location, utbp_evname
)
return temp_base_path
def __computed_Windows_program_files_path( error_on_none = False ):
"""
Returns the correct path to the "Program Files" directory,
depending on whether the OS is 32-bit or 64-bit and the running Python
is 32-bit or 64-bit.
"""
common_base_path = None
location = _TD_( "Windows program files" )
evname = None
if "64bit" in platform.architecture( ):
if sys.maxsize > 2**32: evname = "ProgramFiles"
else: evname = "ProgramFiles(x86)"
else: evname = "ProgramFiles"
common_base_path = envvars.get( evname, None )
__decide_upon_error_on_none(
error_on_none, common_base_path, location, evname
)
return common_base_path
def 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`.)
"""
fsl = which_fs_layout( )
base_path = site.USER_BASE
full_path = None
evname = None
if base_path:
# NOTE: Possible PEP 370 violation.
if fsl in [ "POSIX", ]:
full_path = join_filtered_path( base_path, "share", specific_path )
elif fsl in [ "MacOS X", ]:
posix_flavor = \
sys.prefix == __computed_MacOS_X_python_prefix( sys.prefix )
if posix_flavor: mid_path = "share"
else: mid_path = "Application Support"
full_path = \
join_filtered_path( base_path, mid_path, specific_path )
elif fsl in [ "Windows", ]:
full_path = \
join_filtered_path( base_path, "Resources", specific_path )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, full_path,
_TD_( "Pythonic user-specific resources" ),
evname, specific_path
)
return full_path
def 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:
.. csv-table::
:header: "Classification", "Path"
:widths: 20, 80
"POSIX", "/"
"MacOS X", "/"
"Windows", "C:\\\\Windows\\\\System32"
"""
irp_evname = None
install_root_path = None
location = _TD_( "OS core installation root" )
fsl = which_fs_layout( )
if fsl in [ "POSIX", "MacOS X", ]:
install_root_path = "/"
elif fsl in [ "Windows", ]:
irp_evname = "SystemRoot"
install_root_path = envvars.get( irp_evname, None )
if install_root_path:
install_root_path = join_path( install_root_path, "System32" )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, install_root_path, location, irp_evname
)
return install_root_path
def _calculate_path( self ):
""" """
error_on_none = \
self.get_with_default( "error_on_none" )
software_name = \
self.get_with_default( "software_name" )
software_provider_name = \
self.get_with_default( "software_provider_name" )
software_version = \
self.get_with_default( "software_version" )
if not software_name:
if error_on_none:
raise UndeterminedPathError(
_TD_( "Missing software name for calculated path." )
)
else: return None
return _join_path( *filter(
None,
[ software_provider_name, software_name, software_version ]
) )
def 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.
"""
fsl = which_fs_layout( )
full_path = None
evname = None
if base_path:
if fsl in [ "POSIX", ]:
full_path = \
join_filtered_path( base_path, ".local/share", specific_path )
elif fsl in [ "MacOS X", ]:
posix_flavor = \
sys.prefix == __computed_MacOS_X_python_prefix( sys.prefix )
if posix_flavor: mid_path = ".local/share"
else: mid_path = "Application Support"
full_path = \
join_filtered_path( base_path, mid_path, specific_path )
elif fsl in [ "Windows", ]:
if specific_path:
full_path = \
join_filtered_path( base_path, specific_path, "Resources" )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, full_path,
_TD_( "user-specific resources" ),
evname, specific_path
)
return full_path
def 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:
.. csv-table::
:header: "Classification", "Path"
:widths: 20, 80
"POSIX", "/etc"
"MacOS X", "/System/Preferences"
"Windows", "C:\\\\Windows\\\\System32\\\\Config"
"""
cbp_evname = None
config_base_path = None
location = _TD_( "OS core configuration information" )
fsl = which_fs_layout( )
if fsl in [ "POSIX", ]: config_base_path = "/etc"
elif fsl in [ "MacOS X", ]: config_base_path = "/System/Preferences"
elif fsl in [ "Windows", ]:
cbp_evname = "SystemRoot"
config_base_path = envvars.get( cbp_evname, None )
if config_base_path:
config_base_path = \
join_path( config_base_path, "System32", "Config" )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, config_base_path, location, cbp_evname
)
return config_base_path
def 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:
.. csv-table::
:header: "Classification", "Path"
:widths: 20, 80
"POSIX", "/usr/local"
"MacOS", "/Library"
"Windows", "C:\\\\Program Files"
"""
irp_evname = None
install_root_path = None
location = _TD_( "common installation root" )
fsl = which_fs_layout( )
if "POSIX" == fsl: install_root_path = "/usr/local"
elif "MacOS X" == fsl: install_root_path = "/Library"
elif "Windows" == fsl:
install_root_path = \
__computed_Windows_program_files_path( error_on_none = error_on_none )
else: __raise_UnsupportedFilesystemLayout( fsl )
__decide_upon_error_on_none(
error_on_none, install_root_path, location, irp_evname
)
return install_root_path
