Paths

flutils offers the following path utility functions.

flutils.chmod(path, mode_file=None, mode_dir=None, include_parent=False)[source]

Change the mode of a path.

This function processes the given path with normalize_path.

If the given path does NOT exist, nothing will be done.

This function will NOT change the mode of:

  • symlinks (symlink targets that are files or directories will be changed)
  • sockets
  • fifo
  • block devices
  • char devices
Parameters:
  • path (str or bytes or pathlib.PosixPath or pathlib.WindowsPath) – The path of the file or directory to have it’s mode changed. This value can be a glob pattern.
  • mode_file (int, optional) – The mode applied to the given path that is a file or a symlink target that is a file. Defaults to 0o600.
  • mode_dir (int, optional) – The mode applied to the given path that is a directory or a symlink target that is a directory. Defaults to 0o700.
  • include_parent (bool, optional) – A value of True will chmod the parent directory of the given path that contains a a glob pattern. Defaults to False.
Returns:

Nothing
Return type:

None

Examples

>>> from flutils import chmod
>>> chmod('~/tmp/flutils.tests.osutils.txt', 0o660)

Supports a glob pattern. So to recursively change the mode of a directory just do:

>>> chmod('~/tmp/**', mode_file=0o644, mode_dir=0o770)

To change the mode of a directory’s immediate contents:

>>> chmod('~/tmp/*')
flutils.chown(path, user=None, group=None, include_parent=False)[source]

Change ownership of a path.

This function processes the given path with normalize_path.

If the given path does NOT exist, nothing will be done.

Parameters:
  • path (str or bytes or pathlib.PosixPath or pathlib.WindowsPath) – The path of the file or directory that will have it’s ownership changed. This value can be a glob pattern.
  • user (str or int, optional) – The “login name” used to set the owner of path. A value of '-1' will leave the owner unchanged. Defaults to the “login name” of the current user.
  • group (str or int, optional) – The group name used to set the group of path. A value of '-1' will leave the group unchanged. Defaults to the current user’s group.
  • include_parent (bool, optional) – A value of True will chown the parent directory of the given path that contains a glob pattern. Defaults to False.
Raises:
  • OSError – If the given user does not exist as a “login name” for this operating system.
  • OSError – If the given group does not exist as a “group name” for this operating system.
Returns:

Nothing
Return type:

None

Examples

>>> from flutils import chown
>>> chown('~/tmp/flutils.tests.osutils.txt')

Supports a glob pattern. So to recursively change the ownership of a directory just do:

>>> chown('~/tmp/**')

To change ownership of all the directory’s immediate contents:

>>> chown('~/tmp/*', user='foo', group='bar')
flutils.directory_present(path, mode=None, user=None, group=None)[source]

Ensure the state of the given path is present and a directory.

This function processes the given path with normalize_path.

If the given path does NOT exist, it will be created as a directory.

If the parent paths of the given path do not exist, they will also be created with the mode, user and group.

If the given path does exist as a directory, the mode, user, and :group will be applied.

Parameters:
  • path (str or bytes or pathlib.PosixPath or pathlib.WindowsPath) – The path of the directory.
  • mode (int, optional) – The mode applied to the path. Defaults to 0o700.
  • user (str or int, optional) – The “login name” used to set the owner of the given path. A value of '-1' will leave the owner unchanged. Defaults to the “login name” of the current user.
  • group (str or int, optional) – The group name used to set the group of the given path. A value of '-1' will leave the group unchanged. Defaults to the current user’s group.
Raises:
  • ValueError – if the given path contains a glob pattern.
  • ValueError – if the given path is not an absolute path.
  • FileExistsError – if the given path exists and is not a directory.
  • FileExistsError – if a parent of the given path exists and is not a directory.
Returns:

PosixPath or WindowsPath depending on the system.


Note

PurePath objects are immutable. Therefore, any PosixPath or WindowsPath objects given to this function will not be the same objects returned.
Return type:

pathlib.PurePath
flutils.exists_as(path)[source]

Return a string describing the file type if it exists.

This function processes the given path with normalize_path.

Parameters:path (str or bytes or pathlib.PosixPath or pathlib.WindowsPath) – The path to check existance.
Returns:one of the following values:
'':if the given path does NOT exist; or, is a broken symbolic link; or, other errors (such as permission errors) are propagated.
'directory':if the given path points to a directory or is a symbolic link pointing to a directory.
'file':if the given path points to a regular file or is a symbolic link pointing to a regular file.
'block device':if the given path points to a block device or is a symbolic link pointing to a block device.
'char device':if the given path points to a character device or is a symbolic link pointing to a character device.
'FIFO':if the given path points to a FIFO or is a symbolic link pointing to a FIFO.
'socket':if the given path points to a Unix socket or is a symbolic link pointing to a Unix socket.
Return type:str

Example

>>> from flutils import exists_as
>>> exists_as('~/tmp')
'directory'
flutils.find_paths(pattern)[source]

Find all paths that match the given glob pattern.

This function pre-processes the given pattern with normalize_path.

Parameters:pattern (str or bytes or pathlib.PosixPath or pathlib.WindowsPath) – The path to find; which may contain a glob pattern.
Returns:A generator that yields pathlib.PosixPath or pathlib.WindowsPath.
Return type:generator

Example

>>> from flutils import find_paths
>>> list(find_paths('~/tmp/*'))
[PosixPath('/home/test_user/tmp/file_one'),
PosixPath('/home/test_user/tmp/dir_one')]
flutils.get_os_group(name=None)[source]

Get an operating system group object.

Parameters:

name (str or int, optional) – The “group name” or gid. Defaults to the current users’s group.
Raises:
  • OSError – If the given name does not exist as a “group name” for this operating system.
  • OSError – If the given name is a gid and it does not exist.
Returns:

A tuple like object.
Return type:

struct_group

Example

>>> from flutils import get_os_group
>>> get_os_group('bar')
grp.struct_group(gr_name='bar', gr_passwd='*', gr_gid=2001,
gr_mem=['foo'])
flutils.get_os_user(name=None)[source]

Return an user object representing an operating system user.

Parameters:

name (str or int, optional) – The “login name” or uid. Defaults to the current user’s “login name”.
Raises:
  • OSError – If the given name does not exist as a “login name” for this operating system.
  • OSError – If the given name is an uid and it does not exist.
Returns:

A tuple like object.
Return type:

struct_passwd

Example

>>> from flutils import get_os_user
>>> get_os_user('foo')
pwd.struct_passwd(pw_name='foo', pw_passwd='********', pw_uid=1001,
pw_gid=2001, pw_gecos='Foo Bar', pw_dir='/home/foo',
pw_shell='/usr/local/bin/bash')
flutils.normalize_path(path)[source]

Normalize a given path.

The given path will be normalized in the following process.

  1. bytes will be converted to a str using the encoding given by getfilesystemencoding().
  2. PosixPath and WindowsPath will be converted to a str using the as_posix() method.
  3. An initial component of ~ will be replaced by that user’s home directory.
  4. Any environment variables will be expanded.
  5. Non absolute paths will have the current working directory from os.getcwd() to change the current working directory before calling this function.
  6. Redundant separators and up-level references will be normalized, so that A//B, A/B/, A/./B and A/foo/../B all become A/B.
Parameters:path (str or bytes or pathlib.PosixPath or pathlib.WindowsPath) – The path to be normalized.
Returns:PosixPath or WindowsPath depending on the system.

Note

PurePath objects are immutable. Therefore, any PosixPath or WindowsPath objects given to this function will not be the same objects returned.
Return type:pathlib.PurePath

Example

>>> from flutils import normalize_path
>>> normalize_path('~/tmp/foo/../bar')
PosixPath('/home/test_user/tmp/bar')
flutils.path_absent(path)[source]

Ensure the given path does NOT exist.

If the given path does exist, it will be deleted.

If the given path is a directory, this function will recursively delete all of the directory’s contents.

This function processes the given path with normalize_path.

Parameters:path (str or bytes or pathlib.PosixPath or pathlib.WindowsPath) – The path to remove. This value can also be a glob pattern.
Returns:Nothing
Return type:None