feat: add support for the /read-event-type endpoint (#110)

* feat: add support for the `/read-event-type` endpoint

* chore: fix typo

* Update README.md

---------

Co-authored-by: Golo Roden <[email protected]>

Author: matthiasharzer

README.md

@@ -498,6 +498,14 @@ async for event_type in event_types:
 await event_types.aclose()
 ```
 
+### Listing a Specific Event Type
+
+To list a specific event type, call the `read_event_type` function with the event type as an argument. The function returns the detailed event type, which includes the schema:
+
+```python
+event_type = await client.read_event_type("io.eventsourcingdb.library.book-acquired")
+```
+
 ### Using Testcontainers
 
 Import the `Container` class, create an instance, call the `start` function to run a test container, get a client, run your test code, and finally call the `stop` function to stop the test container:

eventsourcingdb/client.py

@@ -294,6 +294,38 @@ async def read_subjects(
                     f'was received \'{message}\'.'
                 )
 
+    async def read_event_type(self, event_type: str) -> EventType:
+        request_body = json.dumps({
+            'eventType': event_type
+        })
+
+        response: Response = await self.http_client.post(
+            path='/api/v1/read-event-type',
+            request_body=request_body,
+        )
+
+        async with response:
+            if response.status_code != HTTPStatus.OK:
+                raise ServerError(
+                    f'Unexpected response status: {response}'
+                )
+
+            response_data = await response.body.read()
+            response_data = bytes.decode(response_data, encoding='utf-8')
+            response_json = json.loads(response_data)
+
+            if not isinstance(response_json, dict):
+                raise ServerError(
+                    f'Failed to parse response \'{response_json}\' to dict.')
+
+            try:
+                return EventType.parse(response_json)
+            except ValidationError as validation_error:
+                raise ServerError(str(validation_error)) from validation_error
+            except Exception as other_error:
+                raise InternalError(str(other_error)) from other_error
+
+
     async def read_event_types(self) -> AsyncGenerator[EventType]:
         response: Response
         try:

tests/test_read_event_type.py

@@ -0,0 +1,69 @@
+import re
+import pytest
+
+from eventsourcingdb import EventCandidate, EventType
+from eventsourcingdb.errors.server_error import ServerError
+
+from .conftest import TestData
+from .shared.database import Database
+
+
+class TestReadEventType:
+    @staticmethod
+    @pytest.mark.asyncio
+    async def test_fails_if_the_event_type_does_not_exist(
+        database: Database,
+    ) -> None:
+        with pytest.raises(ServerError, match=re.compile("^Server error occurred: Unexpected response status: status_code=404 Not Found")):
+            await database.get_client().read_event_type("non.existent.event.type")
+
+    @staticmethod
+    @pytest.mark.asyncio
+    async def test_fails_if_the_event_type_is_malformed(
+        database: Database,
+    ) -> None:
+        with pytest.raises(ServerError, match=re.compile("^Server error occurred: Unexpected response status: status_code=400 Bad Request")):
+            await database.get_client().read_event_type("malformed.event.type.")
+
+    @staticmethod
+    @pytest.mark.asyncio
+    async def test_read_an_existing_event_type(
+        database: Database,
+        test_data: TestData,
+    ) -> None:
+        client = database.get_client("with_authorization")
+        await client.write_events(
+            [
+                EventCandidate(
+                    source=test_data.TEST_SOURCE_STRING,
+                    subject="/account",
+                    type="com.foo.bar",
+                    data={},
+                ),
+                EventCandidate(
+                    source=test_data.TEST_SOURCE_STRING,
+                    subject="/account/user",
+                    type="com.bar.baz",
+                    data={},
+                ),
+                EventCandidate(
+                    source=test_data.TEST_SOURCE_STRING,
+                    subject="/account/user",
+                    type="com.baz.leml",
+                    data={},
+                ),
+                EventCandidate(
+                    source=test_data.TEST_SOURCE_STRING,
+                    subject="/",
+                    type="com.quux.knax",
+                    data={},
+                ),
+            ]
+        )
+
+        event_type = await client.read_event_type("com.foo.bar")
+
+        assert isinstance(event_type, EventType)
+        assert event_type.event_type == "com.foo.bar"
+        assert event_type.is_phantom is False
+        assert event_type.schema is None