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