feat: implement file adapter wrappers
This commit is contained in:
parent
03ded5d023
commit
8c03c75090
|
|
@ -0,0 +1,2 @@
|
|||
hello
|
||||
world
|
||||
|
|
@ -0,0 +1 @@
|
|||
data
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
line-1
|
||||
line-2
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
hello
|
||||
world
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
line-1
|
||||
line-2
|
||||
|
|
@ -0,0 +1 @@
|
|||
abcdef
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
hello
|
||||
world
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
first
|
||||
second
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
hello
|
||||
world
|
||||
|
|
@ -0,0 +1 @@
|
|||
abcdef
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
first
|
||||
second
|
||||
|
|
@ -0,0 +1 @@
|
|||
data
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
first
|
||||
second
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
line-1
|
||||
line-2
|
||||
|
|
@ -0,0 +1 @@
|
|||
abcdef
|
||||
|
|
@ -0,0 +1 @@
|
|||
data
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
first
|
||||
second
|
||||
|
|
@ -0,0 +1 @@
|
|||
data
|
||||
|
|
@ -0,0 +1 @@
|
|||
abcdef
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
line-1
|
||||
line-2
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
]
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
|
|
|
|||
|
|
@ -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=""))
|
||||
Loading…
Reference in New Issue