File Information
File
Get detailed information about a single file or directory:path(str, required) - Path to file or directory
dict | None - File information or None if file doesn’t exist
Dict keys:
user(str) - Owner usernamegroup(str) - Group namemode(int) - Permissions as octal (e.g., 755)size(int) - File size in bytesmtime(datetime | None) - Modification timeatime(datetime | None) - Access timectime(datetime | None) - Change timetype(str) - File type: “file”, “directory”, “link”, “block”, “character”, “socket”, “fifo”link_target(str | None) - Target path for symbolic links
Directory
Get list of files in a directory:path(str, required) - Path to directory
list[str] | None - List of filenames, or None if directory doesn’t exist
Returns just filenames, not full paths. Use
os.path.join() to build full paths.Link
Get the target of a symbolic link:path(str, required) - Path to symbolic link
str | None - Target path, or None if not a link or doesn’t exist
File Contents
FindInFile
Search for a pattern in a file:path(str, required) - Path to filepattern(str, required) - Pattern to search for (plain text or regex)
list[str] | None - Matching lines, or None if file doesn’t exist
FindFiles
Find files matching a pattern:path(str, required) - Directory to search inpattern(str, required) - Filename pattern (glob style)
list[str] - List of matching file paths
FindLinks
Find symbolic links in a directory:path(str, required) - Directory to search
list[str] - List of symbolic link paths
FindDirectories
Find subdirectories:path(str, required) - Directory to search
list[str] - List of subdirectory paths
File Hashes
Sha1File
Get SHA1 hash of a file:path(str, required) - Path to file
str | None - SHA1 hash, or None if file doesn’t exist
Sha256File
Get SHA256 hash of a file:path(str, required) - Path to file
str | None - SHA256 hash, or None if file doesn’t exist
Md5File
Get MD5 hash of a file:path(str, required) - Path to file
str | None - MD5 hash, or None if file doesn’t exist
File System
BlockDevices
Get list of block devices:list[str] - List of block device paths
DiskUsage
Get disk usage information:path(str, required) - Path to check (file or directory)
dict - Disk usage information
Dict keys:
filesystem(str) - Filesystem devicesize(int) - Total size in bytesused(int) - Used space in bytesavailable(int) - Available space in bytesused_percent(int) - Percentage usedmounted_on(str) - Mount point
Usage Examples
Check File Exists Before Creating
Check File Permissions
Find and Process Config Files
Search Config Files
Check Disk Space
Verify File Hash
List Directory Contents
Complete Example
Here’s a comprehensive example using file facts:Source Reference
Location:src/pyinfra/facts/files.py
Key Facts
File- Get file information (line 138+)Directory- List directory contentsLink- Get symlink targetFindInFile- Search file contentsFindFiles- Find files by patternSha256File- Get file hashDiskUsage- Get disk usage
