feat: add get_item method to BaseRepository with tests, examples and docs

examples/basic_usage.py

@@ -32,6 +32,16 @@ async def main() -> None:
     )
     print(f"Created: {user.name}, {user.email}")
 
+    # Read single item
+    single = await repository.get_item()
+    print(f"Single item: {single.name}, {single.email}")
+
+    # Read by filter
+    filtered = await repository.get_item(
+        filter_=UserFilter(email="alice@example.com"),
+    )
+    print(f"Filtered item: {filtered.name if filtered else None}")
+
     # Read all
     items = [item async for item in repository.get_items()]
     print(f"All items: {[(item.name, item.email) for item in items]}")

examples/container_usage.py

@@ -78,6 +78,10 @@ async def main() -> None:
     print(f"Orders: {[(order.user_id, order.total) for order in orders]}")
     print(f"Orders count: {len(orders)}")
 
+    # Get single user by name
+    single_user = await user_repo.get_item(filter_=UserFilter(name="Alice"))
+    print(f"Single user: {single_user.name if single_user else None}")
+
 
 if __name__ == "__main__":
     asyncio.run(main())

examples/dto_usage.py

@@ -47,6 +47,12 @@ async def main() -> None:
     )
     print(f"Created DTO: {user.model_dump()}")
 
+    # Read single DTO
+    single = await repository.get_item(
+        filter_=UserFilter(email="alice@example.com"),
+    )
+    print(f"Single DTO: {single.model_dump() if single else None}")
+
     # Read all — returned as DTOs
     items = [item async for item in repository.get_items()]
     print(f"Items as DTOs: {[item.model_dump() for item in items]}")

examples/filter_usage.py

@@ -40,8 +40,12 @@ async def main() -> None:
             BookTable(title=f"Book {index}", year=2020 + index),
         )
 
-    # Filter by year = 2025
+    # Get single item by filter
     year_filter = BookFilter(year=2025)
+    single = await repository.get_item(filter_=year_filter)
+    print(f"Single year = 2025: {single.title if single else None}")
+
+    # Filter by year = 2025
     filtered = [item async for item in repository.get_items(filter_=year_filter)]
     print(f"Year = 2025: {[book.title for book in filtered]}")
 

examples/transactions.py

@@ -54,6 +54,11 @@ async def main() -> None:
     count = await repository.get_items_count()
     print(f"Items after nested rollback: {count}")  # 2
 
+    # Read single item inside a transaction
+    async with repository.transaction():
+        item = await repository.get_item(filter_=ProductFilter(name="Laptop"))
+        print(f"Single in transaction: {item.name if item else None}")
+
 
 if __name__ == "__main__":
     asyncio.run(main())