zms._fileutil

module documentation

(source)

_fileutil.py - ZMS File System Utilities

This module provides file-system utility functions for ZMS, including path handling, file reading/writing, ZEXP import/export, ZIP archive creation/extraction, and data size formatting.

License: GNU General Public License v2 or later, Organization: ZMS Publishing

Function	`absoluteOSPath`	Convert a relative path to an absolute path, resolving '..' segments.
Function	`buildZipArchive`	Build a ZIP archive from files matching a pattern and return data.
Function	`executeCommand`	Execute a shell command in the given directory.
Function	`exportObj`	Export an object's data to a file on disk.
Function	`extractFileExt`	Extract the file extension from a path.
Function	`extractFilename`	Extract the filename from a file path.
Function	`extractZipArchive`	Unpack a ZIP archive to the directory containing the archive file.
Function	`findExtension`	Search a directory (optionally recursively) for a file with the given extension.
Function	`getDataSizeStr`	Format a file size in bytes as a human-readable string.
Function	`getFilePath`	Extract the directory path from a full file path (removing filename).
Function	`getOSPath`	Normalize a path string to use OS-appropriate separators.
Function	`getZipArchive`	Extract files from a ZIP archive and return a list of extracted files.
Function	`import_zexp`	Import a ZEXP file into the current container and normalize sort IDs.
Function	`importZexp`	Import a ZEXP file from the INSTANCE_HOME/import folder.
Function	`mkDir`	Create a directory and any necessary parent directories.
Function	`readDir`	List directory contents with metadata.
Function	`readFile`	Read a file and return its data along with content-type information.
Function	`readPath`	Read directory contents and return a list of file/directory info dicts.
Function	`remove`	Remove a file or directory.
Function	`tail_lines`	Read the last N lines from a file, similar to 'tail -N filename'.
Function	`writeZipFile`	Recursively write files matching a filter pattern to a ZIP archive.

def absoluteOSPath(path): (source) ¶

Convert a relative path to an absolute path, resolving '..' segments.

Parameters
path:`str`	File path (may contain '..' segments)
Returns
`str`	Absolute path with resolved parent references

def buildZipArchive(files, get_data=True): (source) ¶

Build a ZIP archive from files matching a pattern and return data.

Parameters
files:`str`	File path pattern (e.g. '/path/to/dir/*.txt')
get_data:`bool`	If True, return archive data; if False, return temp filename
Returns
`bytes` or `str`	ZIP archive data (bytes) or temporary file path

def executeCommand(path, command): (source) ¶

Execute a shell command in the given directory.

Parameters
path:`str`	Working directory for the command
command:`str`	Shell command to execute

def exportObj(obj, filename): (source) ¶

Export an object's data to a file on disk.

Supports MyBlob objects, Zope objects, ImageFile objects, file-like objects, and raw data.

Parameters
obj	The object to export
filename:`str`	Destination file path
Returns
`bytes` or `None`	The exported data, or None if no data

def extractFileExt(path): (source) ¶

Extract the file extension from a path.

Parameters
path:`str`	File path
Returns
`str`	File extension (without dot)

def extractFilename(path, sep=None, undoable=False): (source) ¶

Extract the filename from a file path.

Parameters
path:`str`	File path
sep:`str` or `None`	Custom separator (default: OS separator)
undoable:`bool`	Whether special characters should be preserved
Returns
`str`	Filename portion of the path

def extractZipArchive(file): (source) ¶

Unpack a ZIP archive to the directory containing the archive file.

Skips macOS metadata files (__MACOSX/, .DS_Store).

Parameters
file:`str`	Path to the ZIP archive file
Returns
`list`	List of extracted file paths

def findExtension(extension, path, deep=1): (source) ¶

Search a directory (optionally recursively) for a file with the given extension.

Parameters
extension:`str`	File extension to search for (without dot)
path:`str`	Directory path to search in
deep:`int`	Whether to search subdirectories recursively
Returns
`str` or `None`	Full path to the first matching file, or None

def getDataSizeStr(len): (source) ¶

Format a file size in bytes as a human-readable string.

Parameters
len:`int` or `float`	File size in bytes
Returns
`str`	Human-readable size string (e.g. '1KB', '2.5 MB')

def getFilePath(path): (source) ¶

Extract the directory path from a full file path (removing filename).

Parameters
path:`str`	Full file path
Returns
`str`	Directory path

def getOSPath(path, chs=list(range(32)) + [34, 39, 60, 62, 63, 127], undoable=False): (source) ¶

Normalize a path string to use OS-appropriate separators.

Parameters
path:`str` or `bytes`	File path to normalize
chs:`list`	List of character codes to strip (unused)
undoable:`bool`	Whether special characters should be preserved
Returns
`str`	Normalized path

def getZipArchive(f): (source) ¶

Extract files from a ZIP archive and return a list of extracted files.

Creates a temporary directory, extracts the archive, reads the contents, then cleans up.

Parameters
f	ZIP file data or object to extract
Returns
`list`	List of file info dicts (from `readPath`)

def import_zexp(self, zexp, new_id, id_prefix, _sort_id=0): (source) ¶

Import a ZEXP file into the current container and normalize sort IDs.

Parameters
self:`OFS.ObjectManager`	The container object to import into
zexp	The ZEXP file object to import
new_id:`str`	Target ID for the imported object
id_prefix:`str`	ID prefix for sort-ID normalization
_sort_id:`int`	Initial sort ID

def importZexp(self, filename): (source) ¶

Import a ZEXP file from the INSTANCE_HOME/import folder.

Parameters
self:`OFS.ObjectManager`	The container object to import into
filename:`str`	Name of the ZEXP file in the import folder

def mkDir(path): (source) ¶

Create a directory and any necessary parent directories.

Parameters
path:`str`	Directory path to create

def readDir(path): (source) ¶

List directory contents with metadata.

Parameters
path:`str`	Directory path to list
Returns
`list`	List of dicts with keys: path, file, mtime, size, type ('d' or 'f'), sorted by type (directories first)

def readFile(filename, mode='b', threshold=2 << 16): (source) ¶

Read a file and return its data along with content-type information.

Uses a filestream_iterator for files larger than the threshold.

Parameters
filename:`str`	Path to the file to read
mode:`str`	File open mode ('b' for binary, 't' for text)
threshold:`int`	Size threshold in bytes for using filestream_iterator (-1 to always read into memory)
Returns
`tuple`	Tuple of (data, content_type, encoding, file_size)

def readPath(path, data=True, recursive=True): (source) ¶

Read directory contents and return a list of file/directory info dicts.

Parameters
path:`str`	Directory path (may include glob wildcards)
data:`bool`	Whether to read file data
recursive:`bool`	Whether to recurse into subdirectories
Returns
`list`	List of dicts with keys: local_filename, filename, mtime, size, content_type, encoding, data (if requested), isdir

def remove(path, deep=0): (source) ¶

Remove a file or directory.

Parameters
path:`str`	Path to remove
deep:`int`	Unused (directories are always removed recursively)

def tail_lines(filename, linesback=10, returnlist=0): (source) ¶

Read the last N lines from a file, similar to 'tail -N filename'.

Parameters
filename:`str`	Path to the file to read
linesback:`int`	Number of lines to read from end of file
returnlist:`int`	If true, return a list of lines; otherwise a string
Returns
`str` or `list`	Last N lines as a string or list

def writeZipFile(zf, basepath, path, filter): (source) ¶

Recursively write files matching a filter pattern to a ZIP archive.

Parameters
zf:`zipfile.ZipFile`	Open ZipFile object to write to
basepath:`str`	Base path for computing archive names
path:`str`	Current directory path to scan
filter:`str`	Semicolon-separated glob patterns to match files