Paths

flutils offers the following path utility functions:

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, bytes or Path) – 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.

Return type

None

Examples

>>> from flutils.pathutils 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/*')
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, bytes or Path) – 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.

Return type

None

Examples

>>> from flutils.pathutils 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')
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, bytes or Path) – 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.

Return type

Path

Note

Path objects are immutable. Therefore, any given path of type Path will not be the same object returned.

Example

>>> from flutils.pathutils import directory_present
>>> directory_present('~/tmp/test_path')
PosixPath('/Users/len/tmp/test_path')
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, bytes or Path) – The path to check for existence.

Return type

str

  • '' (empty string): 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.

Example

>>> from flutils.pathutils import exists_as
>>> exists_as('~/tmp')
'directory'
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, bytes or Path) – The path to find; which may contain a glob pattern.

Return type

Generator

Yields

pathlib.PosixPath or pathlib.WindowsPath

Example

>>> from flutils.pathutils import find_paths
>>> list(find_paths('~/tmp/*'))
[PosixPath('/home/test_user/tmp/file_one'),
PosixPath('/home/test_user/tmp/dir_one')]
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.

Return type

struct_group

  • A tuple like object.

Example

>>> from flutils.pathutils import get_os_group
>>> get_os_group('bar')
grp.struct_group(gr_name='bar', gr_passwd='*', gr_gid=2001,
gr_mem=['foo'])
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.

Return type

struct_passwd

  • A tuple like object.

Example

>>> from flutils.pathutils 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')
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, bytes or Path) – The path to be normalized.

Return type

Path

Note

Path objects are immutable. Therefore, any given path of type Path will not be the same object returned.

Example

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

Ensure the given path does NOT exist.

New in version 0.4.

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, bytes or Path) – The path to remove.

Return type

None

Example

>>> from flutils.pathutils import path_absent
>>> path_absent('~/tmp/test_path')