Add get method for retrieving file metadata in clients

- Added `get` method in both synchronous and asynchronous clients to
  fetch file metadata by file identifier (`PdfRestFileID` or string
  input).
- Implemented validation for invalid file IDs in both sync and async
  clients.
- Enriched test cases to ensure coverage for valid and invalid
  scenarios, including both sync and async executions.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/client.py

@@ -27,6 +27,7 @@
     PdfRestErrorResponse,
     PdfRestFile,
     PdfRestFileBasedResponse,
+    PdfRestFileID,
     UpResponse,
 )
 
@@ -206,6 +207,12 @@ def _resolve_file_id(file_ref: PdfRestFile | str) -> str:
     return file_ref.id if isinstance(file_ref, PdfRestFile) else str(file_ref)
 
 
+def _normalize_file_id(file_ref: PdfRestFileID | str) -> PdfRestFileID:
+    if isinstance(file_ref, PdfRestFileID):
+        return file_ref
+    return PdfRestFileID(str(file_ref))
+
+
 ClientType = TypeVar("ClientType", httpx.Client, httpx.AsyncClient)
 
 
@@ -742,6 +749,11 @@ class _FilesClient:
     def __init__(self, client: _SyncApiClient) -> None:
         self._client = client
 
+    def get(self, file_ref: PdfRestFileID | str) -> PdfRestFile:
+        """Retrieve file metadata given a file identifier."""
+        file_id = _normalize_file_id(file_ref)
+        return self._client.fetch_file_info(str(file_id))
+
     def create(self, files: UploadFiles) -> list[PdfRestFile]:
         """Upload one or more files by content.
 
@@ -857,6 +869,11 @@ def __init__(
         self._client = client
         self._concurrency_limit = concurrency_limit
 
+    async def get(self, file_ref: PdfRestFileID | str) -> PdfRestFile:
+        """Retrieve file metadata given a file identifier."""
+        file_id = _normalize_file_id(file_ref)
+        return await self._client.fetch_file_info(str(file_id))
+
     async def create(self, files: UploadFiles) -> list[PdfRestFile]:
         """Upload one or more files by content.
 

tests/test_files.py

@@ -14,7 +14,7 @@
 import pytest_asyncio
 
 from pdfrest import AsyncPdfRestClient, PdfRestClient
-from pdfrest.models import PdfRestFile
+from pdfrest.models import PdfRestFile, PdfRestFileID
 
 from .resources import get_test_resource_path
 
@@ -145,6 +145,45 @@ def live_async_file(
     )
 
 
+@pytest.mark.parametrize(
+    "file_ref",
+    [
+        pytest.param(PdfRestFileID.generate(), id="pdfrest-file-id"),
+        pytest.param(str(uuid.uuid4()), id="raw-str"),
+    ],
+)
+def test_files_get_fetches_info(file_ref: PdfRestFileID | str) -> None:
+    file_id = str(file_ref)
+    info_payload = _build_file_info_payload(file_id, "report.pdf")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "GET" and request.url.path == f"/resource/{file_id}":
+            assert request.url.params["format"] == "info"
+            return httpx.Response(200, json=info_payload)
+        msg = f"Unexpected request: {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    with PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
+        file_repr = client.files.get(file_ref)
+
+    _assert_file_matches_payload(file_repr, info_payload)
+
+
+def test_files_get_rejects_invalid_id() -> None:
+    transport = httpx.MockTransport(
+        lambda request: (_ for _ in ()).throw(
+            AssertionError("Request should not be sent for invalid IDs.")
+        )
+    )
+
+    with (
+        PdfRestClient(api_key=VALID_API_KEY, transport=transport) as client,
+        pytest.raises(ValueError, match="Invalid PdfRestPrefixedUUID4"),
+    ):
+        client.files.get("not-a-valid-id")
+
+
 def test_files_create_uses_upload_and_info() -> None:
     uploaded_file_id = str(uuid.uuid4())
     info_payload = _build_file_info_payload(uploaded_file_id, "report.pdf")
@@ -698,6 +737,45 @@ def handler(request: httpx.Request) -> httpx.Response:
     _assert_file_matches_payload(response[0], info_payload)
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "file_ref",
+    [
+        pytest.param(PdfRestFileID.generate(), id="pdfrest-file-id"),
+        pytest.param(str(uuid.uuid4()), id="raw-str"),
+    ],
+)
+async def test_async_files_get_fetches_info(file_ref: PdfRestFileID | str) -> None:
+    file_id = str(file_ref)
+    info_payload = _build_file_info_payload(file_id, "report.pdf")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "GET" and request.url.path == f"/resource/{file_id}":
+            assert request.url.params["format"] == "info"
+            return httpx.Response(200, json=info_payload)
+        msg = f"Unexpected request: {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    async with AsyncPdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
+        file_repr = await client.files.get(file_ref)
+
+    _assert_file_matches_payload(file_repr, info_payload)
+
+
+@pytest.mark.asyncio
+async def test_async_files_get_rejects_invalid_id() -> None:
+    transport = httpx.MockTransport(
+        lambda request: (_ for _ in ()).throw(
+            AssertionError("Request should not be sent for invalid IDs.")
+        )
+    )
+
+    async with AsyncPdfRestClient(api_key=VALID_API_KEY, transport=transport) as client:
+        with pytest.raises(ValueError, match="Invalid PdfRestPrefixedUUID4"):
+            await client.files.get("not-a-valid-id")
+
+
 @pytest.mark.asyncio
 async def test_async_files_create_from_paths() -> None:
     uploaded_ids = [str(uuid.uuid4()), str(uuid.uuid4())]