[Port] add describe() for logging

masque/ports.py

@@ -143,6 +143,33 @@ class Port(PivotableImpl, PositionableImpl, Mirrorable, Flippable, Copyable):
         self.rotation = rotation
         return self
 
+    def describe(self) -> str:
+        """
+        Returns a human-readable description of the port's state including cardinal directions.
+        """
+        deg = numpy.rad2deg(self.rotation) if self.rotation is not None else "any"
+
+        cardinal = ""
+        travel_dir = ""
+
+        if self.rotation is not None:
+            dirs = {0: "East (+x)", 90: "North (+y)", 180: "West (-x)", 270: "South (-y)"}
+            # normalize to [0, 360)
+            deg_norm = deg % 360
+
+            # Find closest cardinal
+            closest = min(dirs.keys(), key=lambda x: abs((deg_norm - x + 180) % 360 - 180))
+            if numpy.isclose((deg_norm - closest + 180) % 360 - 180, 0, atol=1e-3):
+                cardinal = f" ({dirs[closest]})"
+
+            # Travel direction (rotation + 180)
+            t_deg = (deg_norm + 180) % 360
+            closest_t = min(dirs.keys(), key=lambda x: abs((t_deg - x + 180) % 360 - 180))
+            if numpy.isclose((t_deg - closest_t + 180) % 360 - 180, 0, atol=1e-3):
+                travel_dir = f" (Travel -> {dirs[closest_t]})"
+
+        return f"pos=({self.x:g}, {self.y:g}), rot={deg:g}{cardinal}{travel_dir}"
+
     def __repr__(self) -> str:
         if self.rotation is None:
             rot = 'any'
@@ -210,11 +237,11 @@ class PortList(metaclass=ABCMeta):
 
     def _log_port_update(self, name: str) -> None:
         """ Log the current state of the named port """
-        port_logger.info("Port %s: %s", name, self.ports[name])
+        port_logger.debug("Port %s: %s", name, self.ports[name].describe())
 
     def _log_port_removal(self, name: str) -> None:
         """ Log that the named port has been removed """
-        port_logger.info("Port %s: removed", name)
+        port_logger.debug("Port %s: removed", name)
 
     def _log_bulk_update(self, label: str) -> None:
         """ Log all current ports at DEBUG level """