feat: implement file adapter wrappers

This commit is contained in:
Ilgiz Kalmetyev 2026-04-17 23:07:20 +05:00
parent 03ded5d023
commit 8c03c75090
24 changed files with 412 additions and 1 deletions

View File

@ -0,0 +1,2 @@
hello
world

View File

@ -0,0 +1 @@
data

View File

@ -0,0 +1,2 @@
line-1
line-2

View File

@ -0,0 +1,2 @@
hello
world

View File

@ -0,0 +1,2 @@
line-1
line-2

View File

@ -0,0 +1 @@
abcdef

View File

@ -0,0 +1,2 @@
hello
world

View File

@ -0,0 +1,2 @@
first
second

View File

@ -0,0 +1,2 @@
hello
world

View File

@ -0,0 +1 @@
abcdef

View File

@ -0,0 +1,2 @@
first
second

View File

@ -0,0 +1 @@
data

View File

@ -0,0 +1,2 @@
first
second

View File

@ -0,0 +1,2 @@
line-1
line-2

View File

@ -0,0 +1 @@
abcdef

View File

@ -0,0 +1 @@
data

View File

@ -0,0 +1,2 @@
first
second

View File

@ -0,0 +1 @@
data

View File

@ -0,0 +1 @@
abcdef

View File

@ -0,0 +1,2 @@
line-1
line-2

View File

@ -47,6 +47,11 @@ application-specific implementation details and to support a universal
- `src/app/adapters/skeleton/config/` contains the universal typed YAML
configuration schema for the skeleton-first layout, plus the contract
documentation and reference example configs.
- `src/app/adapters/skeleton/wrappers/` contains the shared wrapper contract
layer and wrapper-context helpers used by concrete wrappers.
- `src/app/adapters/file_adapter/wrappers/` contains file-specific wrappers
for availability checks, byte/text reads, seek/tell helpers, and tail-style
reads built on the skeleton wrapper contracts.
- `src/app/adapters/base/` contains stage interfaces shared by adapter
implementations.
- `src/app/adapters/external_app/config/` contains the typed schema for the

View File

@ -1 +1,250 @@
"""File wrapper implementations."""
from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
from app.adapters.skeleton.base import BaseExternalWrapper
class FileWrapperError(Exception):
"""Base error for file wrappers."""
class FileWrapperNotFoundError(FileWrapperError):
"""Raised when a requested file does not exist."""
class FileWrapperStateError(FileWrapperError):
"""Raised when a file wrapper request is not valid for the file state."""
@dataclass(slots=True, frozen=True)
class FileAvailabilityRequest:
"""Request to inspect basic file availability."""
path: str | Path
@dataclass(slots=True, frozen=True)
class FileAvailabilityResult:
"""Snapshot returned by the availability wrapper."""
path: Path
exists: bool
is_file: bool
readable: bool
size: int | None = None
@dataclass(slots=True)
class FileAvailabilityWrapper(
BaseExternalWrapper[FileAvailabilityRequest, FileAvailabilityResult]
):
"""Check whether a file exists and can be opened."""
def invoke(self, request: FileAvailabilityRequest) -> FileAvailabilityResult:
path = _coerce_path(request.path)
if not path.exists():
raise FileWrapperNotFoundError(f"file not found: {path}")
stat = path.stat()
return FileAvailabilityResult(
path=path,
exists=True,
is_file=path.is_file(),
readable=os.access(path, os.R_OK),
size=stat.st_size,
)
@dataclass(slots=True, frozen=True)
class FileReadBytesRequest:
"""Request to read bytes from a file."""
path: str | Path
offset: int = 0
length: int | None = None
@dataclass(slots=True, frozen=True)
class FileReadTextRequest:
"""Request to read text from a file."""
path: str | Path
encoding: str = "utf-8"
errors: str = "strict"
offset: int = 0
length: int | None = None
normalize_newlines: bool = True
@dataclass(slots=True)
class FileReadBytesWrapper(BaseExternalWrapper[FileReadBytesRequest, bytes]):
"""Read a file as raw bytes."""
def invoke(self, request: FileReadBytesRequest) -> bytes:
path = _coerce_path(request.path)
_ensure_readable_file(path)
if request.offset < 0:
raise FileWrapperStateError("offset must not be negative")
with path.open("rb") as handle:
handle.seek(request.offset, os.SEEK_SET)
if request.length is None:
return handle.read()
return handle.read(request.length)
@dataclass(slots=True)
class FileReadTextWrapper(BaseExternalWrapper[FileReadTextRequest, str]):
"""Read a file as decoded text."""
def invoke(self, request: FileReadTextRequest) -> str:
data = FileReadBytesWrapper().invoke(
FileReadBytesRequest(
path=request.path,
offset=request.offset,
length=request.length,
)
)
text = data.decode(request.encoding, errors=request.errors)
if request.normalize_newlines:
text = text.replace("\r\n", "\n").replace("\r", "\n")
return text
@dataclass(slots=True, frozen=True)
class FileSeekTellRequest:
"""Request to seek and tell against a file."""
path: str | Path
offset: int = 0
whence: int = os.SEEK_SET
@dataclass(slots=True, frozen=True)
class FileSeekTellResult:
"""Snapshot returned by the seek/tell wrapper."""
path: Path
requested_offset: int
actual_offset: int
size: int
truncated: bool
@dataclass(slots=True)
class FileSeekTellWrapper(BaseExternalWrapper[FileSeekTellRequest, FileSeekTellResult]):
"""Seek within a file and report the resulting offset."""
def invoke(self, request: FileSeekTellRequest) -> FileSeekTellResult:
path = _coerce_path(request.path)
_ensure_readable_file(path)
if request.offset < 0 and request.whence == os.SEEK_SET:
raise FileWrapperStateError("offset must not be negative")
with path.open("rb") as handle:
handle.seek(request.offset, request.whence)
actual_offset = handle.tell()
size = path.stat().st_size
return FileSeekTellResult(
path=path,
requested_offset=request.offset,
actual_offset=actual_offset,
size=size,
truncated=actual_offset > size,
)
@dataclass(slots=True, frozen=True)
class FileTailRequest:
"""Request to read appended bytes from a file."""
path: str | Path
offset: int = 0
encoding: str = "utf-8"
errors: str = "strict"
normalize_newlines: bool = True
as_text: bool = True
@dataclass(slots=True, frozen=True)
class FileTailResult:
"""Snapshot returned by the tail wrapper."""
path: Path
start_offset: int
end_offset: int
size: int
truncated: bool
data: bytes | str
@dataclass(slots=True)
class FileTailWrapper(BaseExternalWrapper[FileTailRequest, FileTailResult]):
"""Read file content from a committed offset to end of file."""
def invoke(self, request: FileTailRequest) -> FileTailResult:
path = _coerce_path(request.path)
_ensure_readable_file(path)
if request.offset < 0:
raise FileWrapperStateError("offset must not be negative")
size = path.stat().st_size
start_offset = min(request.offset, size)
truncated = request.offset > size
with path.open("rb") as handle:
handle.seek(start_offset, os.SEEK_SET)
data = handle.read()
end_offset = start_offset + len(data)
if request.as_text:
content: bytes | str = data.decode(request.encoding, errors=request.errors)
if request.normalize_newlines:
content = content.replace("\r\n", "\n").replace("\r", "\n")
else:
content = data
return FileTailResult(
path=path,
start_offset=start_offset,
end_offset=end_offset,
size=size,
truncated=truncated,
data=content,
)
def _coerce_path(value: str | Path) -> Path:
if isinstance(value, str) and not value.strip():
raise FileWrapperStateError("path must not be empty")
path = Path(value).expanduser()
if not str(path):
raise FileWrapperStateError("path must not be empty")
return path
def _ensure_readable_file(path: Path) -> None:
if not path.exists():
raise FileWrapperNotFoundError(f"file not found: {path}")
if not path.is_file():
raise FileWrapperStateError(f"not a regular file: {path}")
if not os.access(path, os.R_OK):
raise FileWrapperStateError(f"file is not readable: {path}")
__all__ = [
"FileAvailabilityRequest",
"FileAvailabilityResult",
"FileAvailabilityWrapper",
"FileReadBytesRequest",
"FileReadBytesWrapper",
"FileReadTextRequest",
"FileReadTextWrapper",
"FileSeekTellRequest",
"FileSeekTellResult",
"FileSeekTellWrapper",
"FileTailRequest",
"FileTailResult",
"FileTailWrapper",
"FileWrapperError",
"FileWrapperNotFoundError",
"FileWrapperStateError",
]

View File

@ -1 +1,6 @@
"""Wrapper layer for the universal skeleton adapter."""
"""Shared wrapper contracts for the universal skeleton adapter."""
from app.adapters.skeleton.base import BaseExternalWrapper
from app.adapters.skeleton.model import WrapperCallContext
__all__ = ["BaseExternalWrapper", "WrapperCallContext"]

120
tests/test_file_wrappers.py Normal file
View File

@ -0,0 +1,120 @@
"""Tests for the file-specific wrapper layer."""
from __future__ import annotations
from pathlib import Path
from uuid import uuid4
import pytest
from app.adapters.file_adapter.wrappers import (
FileAvailabilityRequest,
FileAvailabilityResult,
FileAvailabilityWrapper,
FileReadBytesRequest,
FileReadBytesWrapper,
FileReadTextRequest,
FileReadTextWrapper,
FileSeekTellRequest,
FileSeekTellWrapper,
FileTailRequest,
FileTailWrapper,
FileWrapperError,
FileWrapperNotFoundError,
FileWrapperStateError,
)
from app.adapters.skeleton.base import BaseExternalWrapper
def _workspace_tmp(name: str) -> Path:
root = Path(__file__).resolve().parents[1] / ".tmp" / "file_wrappers" / name
root.mkdir(parents=True, exist_ok=True)
return root
def test_file_availability_wrapper_reports_existing_and_missing_files() -> None:
root = _workspace_tmp(uuid4().hex)
path = root / "sample.txt"
path.write_text("hello\nworld\n", encoding="utf-8")
wrapper = FileAvailabilityWrapper()
result = wrapper.invoke(FileAvailabilityRequest(path=path))
assert isinstance(wrapper, BaseExternalWrapper)
assert isinstance(result, FileAvailabilityResult)
assert result.path == path
assert result.exists is True
assert result.is_file is True
assert result.readable is True
assert result.size == path.stat().st_size
with pytest.raises(FileWrapperNotFoundError):
wrapper.invoke(FileAvailabilityRequest(path=root / "missing.txt"))
def test_file_read_wrappers_return_bytes_and_text() -> None:
root = _workspace_tmp(uuid4().hex)
path = root / "sample.txt"
path.write_bytes(b"line-1\r\nline-2\r\n")
bytes_wrapper = FileReadBytesWrapper()
text_wrapper = FileReadTextWrapper()
assert (
bytes_wrapper.invoke(FileReadBytesRequest(path=path))
== b"line-1\r\nline-2\r\n"
)
assert text_wrapper.invoke(FileReadTextRequest(path=path)) == "line-1\nline-2\n"
def test_file_seek_tell_wrapper_reports_offsets() -> None:
root = _workspace_tmp(uuid4().hex)
path = root / "sample.txt"
path.write_text("abcdef", encoding="utf-8")
wrapper = FileSeekTellWrapper()
result = wrapper.invoke(FileSeekTellRequest(path=path, offset=3))
assert result.path == path
assert result.requested_offset == 3
assert result.actual_offset == 3
assert result.size == 6
assert result.truncated is False
def test_file_tail_wrapper_reads_from_offset_and_detects_truncation() -> None:
root = _workspace_tmp(uuid4().hex)
path = root / "tail.txt"
path.write_bytes(b"first\nsecond\n")
wrapper = FileTailWrapper()
result = wrapper.invoke(FileTailRequest(path=path, offset=6))
assert result.path == path
assert result.start_offset == 6
assert result.end_offset == len(b"first\nsecond\n")
assert result.size == len(b"first\nsecond\n")
assert result.truncated is False
assert result.data == "second\n"
truncated = wrapper.invoke(FileTailRequest(path=path, offset=50))
assert truncated.start_offset == 13
assert truncated.end_offset == 13
assert truncated.truncated is True
assert truncated.data == ""
def test_file_wrappers_validate_bad_inputs() -> None:
root = _workspace_tmp(uuid4().hex)
assert issubclass(FileWrapperStateError, FileWrapperError)
path = root / "sample.txt"
path.write_text("data", encoding="utf-8")
with pytest.raises(FileWrapperStateError):
FileReadBytesWrapper().invoke(FileReadBytesRequest(path=path, offset=-1))
with pytest.raises(FileWrapperStateError):
FileSeekTellWrapper().invoke(FileSeekTellRequest(path=path, offset=-1))
with pytest.raises(FileWrapperStateError):
FileTailWrapper().invoke(FileTailRequest(path=path, offset=-1))
with pytest.raises(FileWrapperStateError):
FileAvailabilityWrapper().invoke(FileAvailabilityRequest(path=""))