Dosctrings

cooperative_cuisine/orders.py

@@ -55,6 +55,7 @@ from cooperative_cuisine.hooks import (
     ORDER_EXPIRED,
 )
 from cooperative_cuisine.items import Item, Plate, ItemInfo
+from cooperative_cuisine.state_representation import OrderState
 
 log = logging.getLogger(__name__)
 """The logger for this module."""
@@ -279,16 +280,16 @@ class OrderManager:
             if order.meal.name == meal.name:
                 return order, index
 
-    def order_state(self) -> list[dict]:
+    def order_state(self) -> list[OrderState]:
         """Similar to the `to_dict` in `Item` and `Counter`. Relevant for the state of the environment"""
         return [
-            {
-                "id": order.uuid,
-                "category": ORDER_CATEGORY,
-                "meal": order.meal.name,
-                "start_time": order.start_time.isoformat(),
-                "max_duration": order.max_duration.total_seconds(),
-            }
+            OrderState(
+                id=order.uuid,
+                category=ORDER_CATEGORY,
+                meal=order.meal.name,
+                start_time=order.start_time.isoformat(),
+                max_duration=order.max_duration.total_seconds(),
+            )
             for order in self.open_orders
         ]
 

cooperative_cuisine/state_representation.py

@@ -4,110 +4,183 @@ Type hint classes for the representation of the json state.
 import json
 from datetime import datetime
 from enum import Enum
+from typing import Any
 
 from pydantic import BaseModel
 from typing_extensions import Literal, TypedDict
 
 
 class OrderState(TypedDict):
+    """Format of the state representation of an order."""
+
     id: str
+    """ID of the order."""
     category: Literal["Order"]
+    """Category of the order."""
     meal: str
+    """Name of the ordered meal."""
     start_time: datetime  # isoformat str
+    """Time of the creation of the order."""
     max_duration: float
+    """Maximum duration of the order."""
 
 
 class EffectState(TypedDict):
+    """Format of the state representation of an effect."""
+
     id: str
+    """ID of th effect."""
     type: str
+    """Type of the effect."""
     progress_percentage: float | int
+    """Progressed percentage of the effect."""
     inverse_progress: bool
+    """Progress in reverse."""
 
 
 class ItemState(TypedDict):
+    """Format of the state representation of an item."""
+
     id: str
+    """ID of the item."""
     category: Literal["Item"] | Literal["ItemCookingEquipment"]
+    """Category of the item."""
     type: str
+    """Type of the item."""
     progress_percentage: float | int
+    """Progressed percentage of the item."""
     inverse_progress: bool
+    """Progress in reverse."""
     active_effects: list[EffectState]
+    """Active effects of the item."""
     # add ItemType Meal ?
 
 
 class CookingEquipmentState(TypedDict):
+    """Format of the state representation of cooking equipment."""
+
     content_list: list[ItemState]
+    """List of contents of the cooking equipment."""
     content_ready: None | ItemState
+    """Is the content ready to be released?"""
 
 
 class CounterState(TypedDict):
+    """Format of the state representation of a counter."""
+
     id: str
+    """ID of the counter."""
     category: Literal["Counter"]
+    """Category of the counter."""
     type: str
+    """Type of the counter."""
     pos: list[float]
+    """Position of the counter."""
     orientation: list[float]
+    """Orientation / facing direction of the counter, currently only visual."""
     occupied_by: None | list[
         ItemState | CookingEquipmentState
     ] | ItemState | CookingEquipmentState
+    """What is occupying the counter, what is lying/standing on it."""
     active_effects: list[EffectState]
+    """Active effects of the counter."""
     # list[ItemState] -> type in ["Sink", "PlateDispenser"]
 
 
 class PlayerState(TypedDict):
+    """Format of the state representation of a player."""
+
     id: str
+    """ID of the player."""
     pos: list[float]
+    """Position of the player."""
     facing_direction: list[float]
+    """The direction the player is facing."""
     holding: ItemState | CookingEquipmentState | None
+    """What the player is currently holding."""
     current_nearest_counter_pos: list[float] | None
+    """Position of the currently nearest counter to the player."""
     current_nearest_counter_id: str | None
+    """ID of the currently nearest counter to the player."""
 
 
 class KitchenInfo(BaseModel):
-    """Basic information of the kitchen."""
+    """Format of the state representation of basic information of the kitchen."""
 
     width: float
+    """Width of the kitchen. One counter counts as one unit of measurement."""
     height: float
+    """Height of the kitchen. One counter counts as one unit of measurement."""
 
 
 class ViewRestriction(BaseModel):
+    """Format of the state representation of a view restriction from the players perspectives.
+    Currently as a view cone, like a flashlight in the dark."""
+
     direction: list[float]
+    """Direction of what the player can see."""
     position: list[float]
+    """Starting position of the view cone."""
     angle: int  # degrees
+    """Angle of the view cone."""
     counter_mask: None | list[bool]
+    """Mask of which counters are in view. Currently unused."""
     range: float | None
+    """Range of the view."""
 
 
 class InfoMsgLevel(Enum):
+    """Level of importance of the messages displayed to the players."""
+
     Normal = "Normal"
     Warning = "Warning"
     Success = "Success"
 
 
 class InfoMsg(TypedDict):
+    """Info messages for the players to be displayed."""
+
     msg: str
+    """The actual message for the player."""
     start_time: datetime
+    """Start time of the message."""
     end_time: datetime
+    """End time of the message, when the message will disappear."""
     level: InfoMsgLevel
+    """Importance level of the message."""
 
 
 class StateRepresentation(BaseModel):
     """The format of the returned state representation."""
 
     players: list[PlayerState]
+    """Information about the players in the environment."""
     counters: list[CounterState]
+    """Information about the counters in the environment."""
     kitchen: KitchenInfo
+    """General information about the kitchen."""
     score: float | int
+    """The score achieved by the players."""
     orders: list[OrderState]
+    """Current orders in the environment."""
     ended: bool
+    """If the environment has ended."""
     env_time: datetime  # isoformat str
+    """Current time of the environment, relative to the start time of the env."""
     remaining_time: float
+    """Remaining time for the players to act in the environment."""
     view_restrictions: None | list[ViewRestriction]
+    """Restriction of the view for the players."""
     served_meals: list[tuple[str, str]]
+    """List of already served meals in the environment."""
     info_msg: list[tuple[str, str]]
+    """Info messages for the players to be displayed."""
     # is added:
     # all_players_ready: bool
 
 
-def create_json_schema():
+def create_json_schema() -> dict[str, Any]:
+    """Create a json scheme of the state representation of an environment."""
     return StateRepresentation.model_json_schema()