doFolder.fileSystem module

File system operations module for doFolder.

This module provides comprehensive classes and functions for managing files and directories. It includes the main FileSystemItemBase abstract class and its concrete implementations File and Directory, along with utility functions for creating and identifying file system items.

Main classes: - FileSystemItemBase: Abstract base class for all file system items - File: Represents files with read/write/JSON operations - Directory: Represents directories with creation/traversal operations

Main functions: - createItem(): Factory function to create File or Directory objects - isFile()/isDir(): Type checking functions

class doFolder.fileSystem.Directory(path: str | Path, unExistsMode: UnExistsMode = UnExistsMode.WARN, errorMode: ErrorMode = ErrorMode.WARN, toAbsolute: bool = False, exceptType: ItemType | None = None)

Bases: FileSystemItemBase

Represents a directory in the file system.

Provides comprehensive directory operations including creating, deleting, copying, moving, and content management. Supports nested operations through path traversal and recursive iteration.

Added in version 2.0.0.

Changed in version 2.1.0: Directory now inherits directly from FileSystemItemBase instead of File.

copy(target: str | Path) → None

Copy directory and contents to target path.

Parameters:

target (Pathable) – Target path to copy to.

create(target: str | Path | Iterable[str], createType: ItemType = ItemType.FILE, *, existsErrorMode: ErrorMode = ErrorMode.WARN, errorMode: ErrorMode = ErrorMode.WARN) → File | Directory

Create a file or directory within this directory.

Supports nested path creation by automatically creating intermediate directories when necessary. The target path is relative to this directory.

Parameters:

  • target (RelativePathable) – Relative path to create.

  • createType (ItemType, optional) – Type to create (FILE or DIR). Defaults to FILE.

  • existsErrorMode (ErrorMode, optional) – How to handle existing paths. Defaults to WARN.

  • errorMode (ErrorMode, optional) – General error handling mode. Defaults to WARN.

Returns:

Created FileSystemItem (File or Directory).

Return type:

FileSystemItem

createDir(target: str | Path | Iterable[str], *, existsErrorMode: ErrorMode = ErrorMode.WARN, errorMode: ErrorMode = ErrorMode.WARN) → Directory

Create a directory within this directory.

Parameters:

  • target (RelativePathable) – Relative path to the directory.

  • existsErrorMode (ErrorMode, optional) – How to handle existing paths. Defaults to WARN.

  • errorMode (ErrorMode, optional) – General error handling mode. Defaults to WARN.

Returns:

Created Directory object.

Return type:

Directory

Raises:

PathTypeError – If created item is not a directory.

createFile(target: str | Path | Iterable[str], *, existsErrorMode: ErrorMode = ErrorMode.WARN, errorMode: ErrorMode = ErrorMode.WARN) → File

Create a file within this directory.

Parameters:

  • target (RelativePathable) – Relative path to the file.

  • existsErrorMode (ErrorMode, optional) – How to handle existing paths. Defaults to WARN.

  • errorMode (ErrorMode, optional) – General error handling mode. Defaults to WARN.

Returns:

Created File object.

Return type:

File

Raises:

PathTypeError – If created item is not a file.

createSelf() → None

Create directory if it doesn’t exist.

deepCall(target: str | Path | Iterable[str], func: str, *args, createMiddleDir: bool = False, **kwargs) → Any

Perform a deep operation on nested directory structure.

Handles path traversal through multiple directory levels, automatically creating intermediate directories when needed. This is the core method that enables nested operations like create(), get(), and has().

Parameters:

  • target (RelativePathable) – Relative path that may contain multiple directory levels.

  • func (str) – Method name to call on the final directory.

  • *args – Positional arguments for the target method.

  • createMiddleDir (bool, optional) – Whether to create intermediate directories. Defaults to False.

  • **kwargs – Keyword arguments for the target method.

Returns:

Result from the target method call.

Return type:

Any

Raises:

  • ValueError – If target path is invalid.

  • PathNotExistsError – If intermediate directory doesn’t exist.

  • PathTypeError – If intermediate path is not a directory.

delete() → None

Delete directory and all its contents.

get(target: str | Path | Iterable[str], *, exceptType: ItemType = ItemType.FILE, unExistsMode: UnExistsMode = UnExistsMode.WARN, errorMode: ErrorMode = ErrorMode.WARN) → File | Directory

Get a file or directory within this directory.

Parameters:

  • target (RelativePathable) – Relative path to the item.

  • exceptType (ItemType, optional) – Expected item type. Defaults to FILE.

  • unExistsMode (UnExistsMode, optional) – How to handle non-existent paths. Defaults to WARN.

  • errorMode (ErrorMode, optional) – General error handling mode. Defaults to WARN.

Returns:

FileSystemItem for the target.

Return type:

FileSystemItem

getDir(target: str | Path | Iterable[str], *, unExistsMode: UnExistsMode = UnExistsMode.WARN, errorMode: ErrorMode = ErrorMode.WARN) → Directory

Get a directory within this directory.

Parameters:

  • target (RelativePathable) – Relative path to the directory.

  • unExistsMode (UnExistsMode, optional) – How to handle non-existent paths. Defaults to WARN.

  • errorMode (ErrorMode, optional) – General error handling mode. Defaults to WARN.

Returns:

Directory object for the target.

Return type:

Directory

Raises:

PathTypeError – If target is not a directory.

getFile(target: str | Path | Iterable[str], *, unExistsMode: UnExistsMode = UnExistsMode.WARN, errorMode: ErrorMode = ErrorMode.WARN) → File

Get a file within this directory.

Parameters:

  • target (RelativePathable) – Relative path to the file.

  • unExistsMode (UnExistsMode, optional) – How to handle non-existent paths. Defaults to WARN.

  • errorMode (ErrorMode, optional) – General error handling mode. Defaults to WARN.

Returns:

File object for the target.

Return type:

File

Raises:

PathTypeError – If target is not a file.

has(target: str | Path | Iterable[str], *, allowedTargetType: ItemType | None = None) → bool

Check if a file or directory exists within this directory.

Parameters:

  • target (RelativePathable) – Relative path to check.

  • allowedTargetType (ItemType, optional) – Expected item type (FILE, DIR, or None for any).

Returns:

True if target exists and matches type (if specified).

Return type:

bool

property itemType: ItemType

Get item type.

Returns:

Always returns ItemType.DIR.

Return type:

ItemType

iterdir()

Iterate over direct children of the directory.

move(target: str | Path) → None

Move directory and contents to target path.

Parameters:

target (Pathable) – Target path to move to.

recursiveTraversal(hideDirectory: bool = True)

Recursively traverse directory and subdirectories.

Parameters:

hideDirectory (bool, optional) – Whether to exclude directories from results. Defaults to True.

Yields:

File – Files (if hideDirectory=True) or all items (if hideDirectory=False).

class doFolder.fileSystem.File(path: str | Path, unExistsMode: UnExistsMode = UnExistsMode.WARN, errorMode: ErrorMode = ErrorMode.WARN, toAbsolute: bool = False, exceptType: ItemType | None = None)

Bases: FileSystemItemBase

Represents a file in the file system.

Provides comprehensive file operations including reading, writing, copying, moving, deleting, and content management with various formats (text, binary, JSON).

Changed in version 2.1.0: File is now a subclass of FileSystemItemBase rather than the base class.

property content: bytes | NoReturn

Get file content as bytes.

Returns:

File content as bytes.

Return type:

bytes

copy(target: str | Path) → None

Copy file to target path.

Parameters:

target (Pathable) – Target path to copy to.

createSelf() → None

Create the file if it doesn’t exist.

delete() → None

Delete the file.

hash(algorithm: str = 'sha256') → str

Calculate file content hash.

Parameters:

algorithm (str, optional) – Hash algorithm to use. Defaults to “sha256”.

Returns:

Hash value as hexadecimal string.

Return type:

str

Changed in version 2.2.3: Uses doFolder.hashing module instead of hashlib directly.

io(mode: str = 'r')

Create a FileIO object for the file.

Parameters:

mode (str, optional) – File open mode. Defaults to “r”.

Returns:

FileIO object for the file.

Return type:

FileIO

Added in version 2.2.3.

property itemType: ItemType

Get item type.

Returns:

Always returns ItemType.FILE.

Return type:

ItemType

loadAsJson(encoding: str = 'utf-8', **kw) → Any

Load file content as JSON.

Parameters:

  • encoding (str, optional) – Text encoding to use. Defaults to “utf-8”.

  • **kw – Additional arguments for json.load().

Returns:

Parsed JSON data.

Return type:

Any

Added in version 2.0.3.

move(target: str | Path) → None

Move file to target path.

Parameters:

target (Pathable) – Target path to move to.

open(*args, **kwargs)

Open file with specified mode and options.

Parameters:

  • *args – Positional arguments for open().

  • **kwargs – Keyword arguments for open().

Returns:

File object for reading/writing.

Return type:

file

saveAsJson(data: Any, encoding: str = 'utf-8', *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw: Any) → None

Save data as JSON to file.

Parameters:

  • data (Any) – Data to save as JSON.

  • encoding (str, optional) – Text encoding to use. Defaults to “utf-8”.

  • skipkeys (bool, optional) – Skip non-serializable keys. Defaults to False.

  • ensure_ascii (bool, optional) – Ensure ASCII encoding. Defaults to True.

  • check_circular (bool, optional) – Check for circular references. Defaults to True.

  • allow_nan (bool, optional) – Allow NaN values. Defaults to True.

  • cls (type, optional) – Custom JSON encoder class. Defaults to None.

  • indent (int, optional) – Indentation level. Defaults to None.

  • separators (tuple, optional) – Custom separators tuple. Defaults to None.

  • default (callable, optional) – Custom serialization function. Defaults to None.

  • sort_keys (bool, optional) – Sort keys in output. Defaults to False.

  • **kw – Additional arguments for json.dump().

Added in version 2.0.3.

doFolder.fileSystem.FileSystemItem

Union type representing either a File or Directory object.

Added in version 2.1.0.

alias of File | Directory

class doFolder.fileSystem.FileSystemItemBase(path: str | Path, unExistsMode: UnExistsMode = UnExistsMode.WARN, errorMode: ErrorMode = ErrorMode.WARN, toAbsolute: bool = False, exceptType: ItemType | None = None)

Bases: ABC

Abstract base class for file and directory objects.

Provides common functionality for both files and directories, including path management, existence checking, and basic operations.

path

The path to the file or directory.

Type:

Path

Added in version 2.1.0.

checkExists(unExistsMode) → None

Verify path existence and handle according to unExistsMode.

Parameters:

unExistsMode (UnExistsMode) – Behavior when path doesn’t exist.

Raises:

  • PathNotExistsError – If path doesn’t exist and unExistsMode is ERROR.

  • ValueError – If unExistsMode is invalid.

checkItemType(itemType: ItemType) → bool

Check if item type matches expected type.

Parameters:

itemType (ItemType) – Expected item type.

Returns:

True if types match, False otherwise.

Return type:

bool

abstractmethod copy(target: str | Path) → None

Copy item to target path.

Parameters:

target (Pathable) – Target path to copy to.

abstractmethod createSelf() → None

Create the file system item.

abstractmethod delete() → None

Delete the item.

exists() → bool

Check if item exists.

Returns:

True if item exists, False otherwise.

Return type:

bool

property extension: str

Get file extension.

Returns:

File extension (suffix).

Return type:

str

isDir()

Check if this object is a Directory.

Changed in version 2.2.3: This method determines the object type rather than the actual path type.

isFile()

Check if this object is a File.

Changed in version 2.2.3: This method determines the object type rather than the actual path type.

abstract property itemType: ItemType

Get the item type.

Returns:

FILE or DIR enum value.

Return type:

ItemType

abstractmethod move(target: str | Path) → None

Move item to target path.

Parameters:

target (Pathable) – Target path to move to.

property name: str

Get item name.

Returns:

Name of the file or directory.

Return type:

str

parent() → Directory

Get parent directory.

Returns:

Directory object of the parent.

Return type:

Directory

path: Path
property state

Get file/directory state information.

Returns:

os.stat_result object with file statistics.

Return type:

os.stat_result

torch()

Create the file system item if it doesn’t exist.

Added in version 2.2.0.

doFolder.fileSystem.FileSystemItemLike

Union type for objects that can be converted to FileSystemItem.

Includes path strings/objects and existing FileSystemItem instances.

Added in version 2.2.0.

alias of str | Path | FileSystemItem

class doFolder.fileSystem.Folder(*args, **kwargs)

Bases: Directory

Legacy alias for Directory class.

Deprecated since version 2.0: Use Directory class instead. This class exists only for migration convenience from version 1.0.

doFolder.fileSystem.createItem(path: str | Path, unExistsMode: UnExistsMode = UnExistsMode.WARN, errorMode: ErrorMode = ErrorMode.WARN, toAbsolute: bool = False, exceptType: ItemType | None = None) → File | Directory

Create a file system item based on the given path.

Automatically detects whether the path points to a file or directory and creates the appropriate object. If the path doesn’t exist, behavior is controlled by unExistsMode parameter.

Parameters:

  • path (Pathable) – Path to the file or directory.

  • unExistsMode (UnExistsMode, optional) – Behavior when path doesn’t exist. Defaults to WARN.

  • errorMode (ErrorMode, optional) – Error handling mode. Defaults to WARN.

  • toAbsolute (bool, optional) – Convert path to absolute. Defaults to False.

  • exceptType (ItemType, optional) – Expected item type (FILE or DIR). Defaults to None.

Returns:

File or Directory object based on the path type.

Return type:

FileSystemItem

doFolder.fileSystem.isDir(target: FileSystemItemBase) → _tt.TypeIs[Directory]

Check if target is a directory.

Parameters:

target (FileSystemItemBase) – The file system item to check.

Returns:

True if target is a directory, False otherwise.

Return type:

bool

doFolder.fileSystem.isFile(target: FileSystemItemBase) → _tt.TypeIs[File]

Check if target is a file.

Parameters:

target (FileSystemItemBase) – The file system item to check.

Returns:

True if target is a file, False otherwise.

Return type:

bool

doFolder.fileSystem.toFileSystemItem(fr: str | Path | File | Directory) → File | Directory

Convert FileSystemItemLike to FileSystemItem.

Parameters:

fr (FileSystemItemLike) – Object to convert (path or FileSystemItem).

Returns:

FileSystemItem object.

Return type:

FileSystemItem

Added in version 2.2.0.