Filesystem

Utilities for file metadata operations and crash-safe atomic writes.

Overview 

FileMetadataReader is a static utility class under buvis.pybase.filesystem. It surfaces creation and first-commit datetimes with platform-aware fallbacks. No instantiation is required.

atomic_write_text and atomic_write_bytes write a file via a sibling temp file, fsync, and os.replace, so an interrupted write cannot leave a truncated target.

Quick Start 

from pathlib import Path
from buvis.pybase.filesystem import FileMetadataReader

project_root = Path(__file__).resolve().parent

creation_dt = FileMetadataReader.get_creation_datetime(project_root / "pyproject.toml")
first_commit = FileMetadataReader.get_first_commit_datetime(project_root / "pyproject.toml")

print(creation_dt, first_commit)

from pathlib import Path
from buvis.pybase.filesystem import atomic_write_text

atomic_write_text(Path("notes.md"), "# Notes\n")

API Reference 

FileMetadataReader 

class buvis.pybase.filesystem.FileMetadataReader

Bases: object

Utility reader that exposes static helpers for file metadata.

The class is not meant to be instantiated; callers just need to invoke the static helpers to obtain timestamps such as the file creation datetime or the first commit datetime in a Git repository. Creation-time resolution is platform specific (Windows uses st_ctime while Unix systems prefer st_birthtime with a fallback to modification time).

Example

>>> FileMetadataReader.get_creation_datetime(Path("example.txt"))
datetime(2024, 7, 8, 12, 34, tzinfo=...)

static get_creation_datetime(file_path: Path) → datetime

Retrieve the creation date of a file, falling back to modification date if creation date is unavailable.

Parameters:: file_path (Path) – Path to the file.
Returns:: Datetime when file was created.
Return type:: datetime

static get_first_commit_datetime(file_path: Path) → datetime | None

Retrieve the date a file was first added to a Git repository located at the parent directory of file_path.

Parameters:

file_path (Path) – Path to the file.

Returns:

Datetime of the first commit involving the file: or None if the file wasn’t committed to any Git repository.

Return type:

datetime | None

atomic_write_text 

buvis.pybase.filesystem.atomic_write_text(path: Path, data: str, *, encoding: str = 'utf-8', mode: int = 420) → None

Write data to path atomically.

If path already exists, its current permission bits are preserved on the replacement file. Otherwise the new file is created with mode.

atomic_write_bytes 

buvis.pybase.filesystem.atomic_write_bytes(path: Path, data: bytes) → None

Write data to path atomically.

Binary sibling of atomic_write_text(). If path already exists, its current permission bits are preserved on the replacement file. Otherwise the new file is created with mode 0o644.

Examples 

FileMetadataReader Example 

FileMetadataReader can guard metadata-dependent builds while accounting for non-git working trees.

from pathlib import Path
from buvis.pybase.filesystem import FileMetadataReader

project_root = Path(__file__).resolve().parent
config_file = project_root / "pyproject.toml"

created = FileMetadataReader.get_creation_datetime(config_file)
print(f"{config_file.name} born at {created.isoformat()}")

first_commit = FileMetadataReader.get_first_commit_datetime(config_file)
if first_commit is None:
    raise RuntimeError(
        f"{config_file} lives outside a Git repository; commit metadata unavailable."
    )
print(f"First commit touching {config_file.name} occurred on {first_commit.date()}")