watchdog.utils.dirsnapshot

module:

watchdog.utils.dirsnapshot

synopsis:

Directory snapshots and comparison.

author:

yesudeep@google.com (Yesudeep Mangalapilly)

author:

Mickaël Schoentgen <contact@tiger-222.fr>

Where are the moved events? They “disappeared”

This implementation does not take partition boundaries into consideration. It will only work when the directory tree is entirely on the same file system. More specifically, any part of the code that depends on inode numbers can break if partition boundaries are crossed. In these cases, the snapshot diff will represent file/directory movement as created and deleted events.

Classes

class watchdog.utils.dirsnapshot.DirectorySnapshot(path: str, *, recursive: bool = True, stat: Callable[[str], os.stat_result] = <built-in function stat>, listdir: Callable[[str | None], Iterator[os.DirEntry]] = <built-in function scandir>)

Bases: object

A snapshot of stat information of files in a directory.

Parameters:

• path (str) – The directory path for which a snapshot should be taken.

• recursive (bool) – True if the entire directory tree should be included in the snapshot; False otherwise.

• stat –

  Use custom stat function that returns a stat structure for path. Currently only st_dev, st_ino, st_mode and st_mtime are needed.

  A function taking a path as argument which will be called for every entry in the directory tree.

• listdir – Use custom listdir function. For details see os.scandir.

inode(path: bytes | str) → tuple[int, int]

Returns an id for path.

isdir(path: bytes | str) → bool

Returns True if the path is a directory.

mtime(path: bytes | str) → float

Returns the last modification time for path.

path(uid: tuple[int, int]) → bytes | str | None

Returns path for id. None if id is unknown to this snapshot.

property paths: set[bytes | str]

Set of file/directory paths in the snapshot.

size(path: bytes | str) → int

Returns the size of the file identified by path.

stat_info(path: bytes | str) → stat_result

Returns a stat information object for the specified path from the snapshot.

Attached information is subject to change. Do not use unless you specify stat in constructor. Use inode(), mtime(), isdir() instead.

Parameters:

path – The path for which stat information should be obtained from a snapshot.

class watchdog.utils.dirsnapshot.DirectorySnapshotDiff(ref: DirectorySnapshot, snapshot: DirectorySnapshot, *, ignore_device: bool = False)

Bases: object

Compares two directory snapshots and creates an object that represents the difference between the two snapshots.

Parameters:

• ref (DirectorySnapshot) – The reference directory snapshot.

• snapshot (DirectorySnapshot) – The directory snapshot which will be compared with the reference snapshot.

• ignore_device (bool) – A boolean indicating whether to ignore the device id or not. By default, a file may be uniquely identified by a combination of its first inode and its device id. The problem is that the device id may (or may not) change between system boots. This problem would cause the DirectorySnapshotDiff to think a file has been deleted and created again but it would be the exact same file. Set to True only if you are sure you will always use the same device.

class ContextManager(path: str, *, recursive: bool = True, stat: Callable[[str], os.stat_result] = <built-in function stat>, listdir: Callable[[str | None], Iterator[os.DirEntry]] = <built-in function scandir>, ignore_device: bool = False)

Bases: object

Context manager that creates two directory snapshots and a diff object that represents the difference between the two snapshots.

Parameters:

• path (str) – The directory path for which a snapshot should be taken.

• recursive (bool) – True if the entire directory tree should be included in the snapshot; False otherwise.

• stat –

  Use custom stat function that returns a stat structure for path. Currently only st_dev, st_ino, st_mode and st_mtime are needed.

  A function taking a path as argument which will be called for every entry in the directory tree.

• listdir – Use custom listdir function. For details see os.scandir.

• ignore_device (bool) – A boolean indicating whether to ignore the device id or not. By default, a file may be uniquely identified by a combination of its first inode and its device id. The problem is that the device id may (or may not) change between system boots. This problem would cause the DirectorySnapshotDiff to think a file has been deleted and created again but it would be the exact same file. Set to True only if you are sure you will always use the same device.

property dirs_created: list[bytes | str]

List of directories that were created.

property dirs_deleted: list[bytes | str]

List of directories that were deleted.

property dirs_modified: list[bytes | str]

List of directories that were modified.

property dirs_moved: list[tuple[bytes | str, bytes | str]]

List of directories that were moved.

Each event is a two-tuple the first item of which is the path that has been renamed to the second item in the tuple.

property files_created: list[bytes | str]

List of files that were created.

property files_deleted: list[bytes | str]

List of files that were deleted.

property files_modified: list[bytes | str]

List of files that were modified.

property files_moved: list[tuple[bytes | str, bytes | str]]

List of files that were moved.

Each event is a two-tuple the first item of which is the path that has been renamed to the second item in the tuple.

class watchdog.utils.dirsnapshot.EmptyDirectorySnapshot

Bases: DirectorySnapshot

Class to implement an empty snapshot. This is used together with DirectorySnapshot and DirectorySnapshotDiff in order to get all the files/folders in the directory as created.

static path(_: Any) → None

Mock up method to return the path of the received inode. As the snapshot is intended to be empty, it always returns None.

Returns:

None.

property paths: set

Mock up method to return a set of file/directory paths in the snapshot. As the snapshot is intended to be empty, it always returns an empty set.

Returns:

An empty set.