Skip to main content

paths

Path utility functions.

def envset(name: str, default: Optional[bool] = False) -> Optional[bool]​

Return the boolean value of a given environment variable.

An environment variable is considered set if it is assigned to a value other than 'no', 'n', 'false', 'off', '0', or '0.0' (case insensitive).

If the environment variable is not defined, the default value is returned.

Parameters​

  • name : str

    The name of the environment variable to check.

  • default : bool, optional

    The default value to return if the environment variable is not defined. Default is False.

Returns​

  • bool or None

    The boolean value of the environment variable, or the default value if not defined.

def use_platform_dirs() -> bool​

Determine if platformdirs should be used for system-specific paths.

We plan for this to default to False in datalayer version 5 and to True in datalayer version 6.

Returns​

  • bool

    True if platformdirs should be used, False otherwise.

def get_home_dir() -> str​

Get the real path of the home directory.

Returns​

  • str

    The resolved path to the user's home directory.

def prefer_environment_over_user() -> bool​

Determine if environment-level paths should take precedence over user-level paths.

Returns​

  • bool

    True if environment-level paths should take precedence, False otherwise.

def datalayer_config_dir() -> str​

Get the Datalayer config directory for this platform and user.

Returns DATALAYER_CONFIG_DIR if defined, otherwise the appropriate directory for the platform.

Returns​

  • str

    The path to the Datalayer config directory.

def datalayer_data_dir() -> str​

Get the config directory for Datalayer data files for this platform and user.

These are non-transient, non-configuration files.

Returns DATALAYER_DATA_DIR if defined, else a platform-appropriate path.

Returns​

  • str

    The path to the Datalayer data directory.

def datalayer_runtime_dir() -> str​

Return the runtime dir for transient datalayer files.

Returns DATALAYER_RUNTIME_DIR if defined.

The default is now (data_dir)/runtime on all platforms; we no longer use XDG_RUNTIME_DIR after various problems.

Returns​

  • str

    The path to the Datalayer runtime directory.

def datalayer_path(*subdirs: str) -> List[str]​

Return a list of directories to search for data files.

DATALAYER_PATH environment variable has highest priority.

If the DATALAYER_PREFER_ENV_PATH environment variable is set, the environment-level directories will have priority over user-level directories.

If the Python site.ENABLE_USER_SITE variable is True, we also add the appropriate Python user site subdirectory to the user-level directories.

If *subdirs are given, that subdirectory will be added to each element.

Parameters​

  • *subdirs : str

    Optional subdirectories to append to each path element.

Returns​

  • List[str]

    A list of directories to search for data files.

Examples​

datalayer_path()
['~/.local/datalayer', '/usr/local/share/datalayer']
datalayer_path('kernels')
['~/.local/datalayer/kernels', '/usr/local/share/datalayer/kernels']

def datalayer_config_path() -> List[str]​

Return the search path for Datalayer config files as a list.

If the DATALAYER_PREFER_ENV_PATH environment variable is set, the environment-level directories will have priority over user-level directories.

If the Python site.ENABLE_USER_SITE variable is True, we also add the appropriate Python user site subdirectory to the user-level directories.

Returns​

  • List[str]

    A list of directories to search for config files.

def exists(path: str) -> bool​

Replacement for os.path.exists which works for host mapped volumes on Windows containers.

Parameters​

  • path : str

    The path to check for existence.

Returns​

  • bool

    True if the path exists, False otherwise.

def is_file_hidden_win(abs_path: str, stat_res: Optional[Any] = None) -> bool​

Check if a file is hidden on Windows.

This only checks the file itself; it should be called in combination with checking the directory containing the file.

Use is_hidden() instead to check the file and its parent directories.

Parameters​

  • abs_path : str

    The absolute path to check.

  • stat_res : os.stat_result, optional

    The result of calling stat() on abs_path. If not passed, this function will call stat() internally.

Returns​

  • bool

    True if the file is hidden, False otherwise.

def is_file_hidden_posix(abs_path: str, stat_res: Optional[Any] = None) -> bool​

Check if a file is hidden on POSIX systems.

This only checks the file itself; it should be called in combination with checking the directory containing the file.

Use is_hidden() instead to check the file and its parent directories.

Parameters​

  • abs_path : str

    The absolute path to check.

  • stat_res : os.stat_result, optional

    The result of calling stat() on abs_path. If not passed, this function will call stat() internally.

Returns​

  • bool

    True if the file is hidden, False otherwise.

def is_hidden(abs_path: str, abs_root: str = '') -> bool​

Check if a file is hidden or contained in a hidden directory.

This will start with the rightmost path element and work backwards to the given root to see if a path is hidden or in a hidden directory. Hidden is determined by either name starting with '.' or the UF_HIDDEN flag as reported by stat.

If abs_path is the same directory as abs_root, it will be visible even if that is a hidden folder. This only checks the visibility of files and directories within abs_root.

Parameters​

  • abs_path : str

    The absolute path to check for hidden directories.

  • abs_root : str, optional

    The absolute path of the root directory in which hidden directories should be checked for. Default is empty string.

Returns​

  • bool

    True if the file is hidden or in a hidden directory, False otherwise.

def win32_restrict_file_to_user(fname: str) -> None​

Secure a windows file to read-only access for the user.

Follows guidance from win32 library creator: http://timgolden.me.uk/python/win32_how_do_i/add-security-to-a-file.html

This method should be executed against an already generated file which has no secrets written to it yet.

Parameters​

  • fname : str

    The path to the file to secure.

Returns​

  • None

    This function does not return a value.

def get_file_mode(fname: str) -> int​

Retrieve the file mode corresponding to fname in a filesystem-tolerant manner.

Parameters​

  • fname : str

    The path to the file to get mode from.

Returns​

  • int

    The file mode with some bits masked for filesystem tolerance.

def secure_write(fname: str, binary: bool = False) -> Iterator[Any]​

Open a file in the most restricted pattern available for writing content.

This limits the file mode to 0o0600 and yields the resulting opened file handle.

Parameters​

  • fname : str

    The path to the file to write.

  • binary : bool, optional

    Indicates that the file is binary. Default is False.

Yields​

  • Any

    The opened file handle.

def issue_insecure_write_warning() -> None​

Issue an insecure write warning.