oct.git.audit.AuditLogger Class Reference

Public Member Functions
None	__init__ (self, Path project_root)
None	write (self, AuditRecord record)
Path|None	current_path (self)

Protected Member Functions
None	_ensure_logs_dir (self)
Path	_new_filename (self)
int	_current_file_size (self)
None	_rotate_if_needed (self)
list[Path]	_list_existing_files (self)
None	_prune_old_files (self)

Protected Attributes
Path	_project_root = Path(project_root)
Path	_logs_dir = resolve_logs_dir(self._project_root)
Path|None	_current_path = None

Detailed Description

Append-only rotating JSONL logger for ``oct git`` commands.

One instance corresponds to one project root. The constructor does
not open a file — the first :meth:`write` call lazily materialises
the ``logs/`` directory and the current audit file. This lets a
command that never reaches the write stage (e.g. a CLI parse error)
leave no side-effects on disk.

Rotation strategy
-----------------
- **Size rotation:** before each write, if the current file is at or
  above :data:`AUDIT_MAX_SIZE_BYTES`, close it and open a new
  timestamped file. The rotating write itself goes into the new
  file, not the old one.
- **Count pruning:** after any rotation, if the number of
  ``git-audit-*.jsonl`` files in the logs directory exceeds
  :data:`AUDIT_MAX_FILES`, delete the oldest (lexical order) until
  the count is within the limit.

Error handling
--------------
Any IO error during :meth:`write` — creating the directory, opening
the file, serialising the record, writing the line, or rotating —
is caught and logged via ``_dbg("GIT", ..., 1)``. The method never
raises; audit logging is best-effort observability and must not
mask command failures.

Definition at line 165 of file audit.py.

Constructor & Destructor Documentation

__init__()

None oct.git.audit.AuditLogger.__init__	(		self,
		Path	project_root )

Definition at line 194 of file audit.py.

Member Function Documentation

_current_file_size()

int oct.git.audit.AuditLogger._current_file_size ( self )

protected

Return the current audit file's size in bytes, 0 if missing.

Definition at line 231 of file audit.py.

Here is the caller graph for this function:

_ensure_logs_dir()

None oct.git.audit.AuditLogger._ensure_logs_dir ( self )

protected

Create ``<project>/logs/`` on demand. Idempotent.

Definition at line 206 of file audit.py.

Here is the caller graph for this function:

_list_existing_files()

list[Path] oct.git.audit.AuditLogger._list_existing_files ( self )

protected

Return all ``git-audit-*.jsonl`` files in sorted order.

Sort is lexical, which matches chronological thanks to the
fixed-width ``YYYYMMDD-HHMMSS`` timestamp format.

Definition at line 261 of file audit.py.

Here is the caller graph for this function:

_new_filename()

Path oct.git.audit.AuditLogger._new_filename ( self )

protected

Return a fresh ``git-audit-YYYYMMDD-HHMMSS.jsonl`` path.

Uses the current UTC timestamp. If the resulting filename
already exists (unlikely but possible at sub-second rotation or
in a fast loop), disambiguate by appending a monotonic suffix
``-<counter>`` so no two rotations collide.

Definition at line 211 of file audit.py.

Here is the caller graph for this function:

_prune_old_files()

None oct.git.audit.AuditLogger._prune_old_files ( self )

protected

Delete the oldest files until count <= :data:`AUDIT_MAX_FILES`.

Deletion is best-effort: an ``OSError`` from a concurrent
reader holding a handle on Windows is logged but not re-raised.

Definition at line 271 of file audit.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_rotate_if_needed()

None oct.git.audit.AuditLogger._rotate_if_needed ( self )

protected

Open a fresh file if the current one is missing or full.

Called at the top of :meth:`write`. After opening a new file,
delegates to :meth:`_prune_old_files` so count-based rotation
runs at the same moment size-based rotation does (cheapest
common path).

Definition at line 240 of file audit.py.

Here is the call graph for this function:

Here is the caller graph for this function:

current_path()

Path | None oct.git.audit.AuditLogger.current_path

(

self

)

Current audit filename (``None`` before first write).

Definition at line 318 of file audit.py.

write()

None oct.git.audit.AuditLogger.write	(		self,
		AuditRecord	record )

Serialise ``record`` and append it as one JSONL line.

Never raises. On IO failure, logs an error via ``_dbg`` at
level 1 and returns. The caller is never blocked by audit log
misbehaviour.

Definition at line 292 of file audit.py.

Here is the call graph for this function:

Member Data Documentation

_current_path

Path | None oct.git.audit.AuditLogger._current_path = None

protected

Definition at line 201 of file audit.py.

_logs_dir

Path oct.git.audit.AuditLogger._logs_dir = resolve_logs_dir(self._project_root)

protected

Definition at line 200 of file audit.py.

_project_root

Path oct.git.audit.AuditLogger._project_root = Path(project_root)

protected

Definition at line 196 of file audit.py.

---

The documentation for this class was generated from the following file:

• G:/PythonApps/Option_C/oct/oct/git/audit.py