Filesystem

Utilities for file metadata operations.

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.

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)

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

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()}")