mycorrhizal 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

mycorrhizal/common/mermaid.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+Shared Mermaid diagram formatting utilities.
+
+This module provides common formatting functions for generating Mermaid diagrams
+across Mycorrhizal systems (Septum, Mycelium, etc.). Using these utilities ensures:
+- Consistent visual styling across all systems
+- Single source of truth for formatting logic
+- Bug fixes apply to all systems
+
+Usage:
+    from mycorrhizal.common.mermaid import format_state_node, format_transition
+
+    node = format_state_node("state1", "IdleState", is_initial=True)
+    edge = format_transition("state1", "state2", "START")
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def format_state_node(node_id: str, state_name: str, is_initial: bool = False) -> str:
+    """
+    Format a state node for Mermaid diagrams.
+
+    Args:
+        node_id: The unique identifier for this node (e.g., "fsm1_IdleState")
+        state_name: The display name for the state (e.g., "IdleState")
+        is_initial: Whether this is the initial/entry state
+
+    Returns:
+        Mermaid node definition as a string
+
+    Example:
+        >>> format_state_node("state1", "IdleState", is_initial=True)
+        '    state1(["IdleState (initial)"])'
+        >>> format_state_node("state2", "Running", is_initial=False)
+        '    state2(["Running"])'
+    """
+    display_name = state_name
+    if is_initial:
+        display_name = f"{state_name} (initial)"
+
+    # Use stadium shape (rounded rectangle) for states: node_id(["label"])
+    return f'    {node_id}(["[{display_name}]"])'
+
+
+def format_transition(
+    from_id: str,
+    to_id: str,
+    label: Optional[str] = None,
+    style: Optional[str] = None
+) -> str:
+    """
+    Format a transition edge for Mermaid diagrams.
+
+    Args:
+        from_id: Source node ID
+        to_id: Target node ID
+        label: Optional transition label (e.g., event name)
+        style: Optional edge style (e.g., ".thick" for thick lines)
+
+    Returns:
+        Mermaid edge definition as a string
+
+    Example:
+        >>> format_transition("state1", "state2", "START")
+        '    state1 -->|START| state2'
+        >>> format_transition("state1", "state2")
+        '    state1 --> state2'
+    """
+    edge = f"    {from_id} -->"
+    if label:
+        edge = f"{edge}|{label}|"
+    edge = f"{edge} {to_id}"
+
+    if style:
+        edge = f"{edge}{style}"
+
+    return edge
+
+
+def format_subgraph(subgraph_id: str, title: str, content: list[str]) -> str:
+    """
+    Format a subgraph for grouping related nodes.
+
+    Args:
+        subgraph_id: Unique identifier for the subgraph
+        title: Display title for the subgraph
+        content: List of lines containing the subgraph content
+
+    Returns:
+        Mermaid subgraph definition as a string
+
+    Example:
+        >>> content = [
+        ...     '    state1(["Idle"])',
+        ...     '    state2(["Running"])'
+        ... ]
+        >>> format_subgraph("FSM1", "My FSM", content)
+        '    subgraph FSM1 ["My FSM"]\\n    state1(["Idle"])\\n    state2(["Running"])\\n    end'
+    """
+    lines = [f'    subgraph {subgraph_id} ["{title}"]']
+    lines.extend(content)
+    lines.append("    end")
+    return "\n".join(lines)
+
+
+def format_comment(text: str) -> str:
+    """
+    Format a comment for Mermaid diagrams.
+
+    Args:
+        text: Comment text
+
+    Returns:
+        Mermaid comment as a string
+
+    Example:
+        >>> format_comment("This is a comment")
+        '    %% This is a comment'
+    """
+    return f"    %% {text}"

mycorrhizal/common/wrappers.py

@@ -54,7 +54,7 @@ class BaseWrapper:
     and error handling.
     """
 
-    __slots__ = ('_bb', '_allowed_fields', '_private_attrs')
+    __slots__ = ('_bb', '_allowed_fields', '_private_attrs', '__weakref__')
 
     def __init__(
         self,

mycorrhizal/hypha/core/builder.py

@@ -6,7 +6,7 @@ NetBuilder provides the API for declaratively constructing Petri net specificati
 Used within @pn.net decorated functions.
 """
 
-from typing import Optional, Callable, List, Dict, Type, Any
+from typing import Optional, Callable, List, Dict, Type, Any, Union
 from .specs import (
     NetSpec,
     PlaceSpec,
@@ -54,14 +54,52 @@ class NetBuilder:
 
     def place(
         self,
-        name: str,
+        name_or_func: Union[str, Callable, None] = None,
         type: PlaceType = PlaceType.BAG,
         state_factory: Optional[Callable] = None,
-    ) -> PlaceRef:
-        """Declare a regular place"""
-        place_spec = PlaceSpec(name, type, state_factory=state_factory)
-        self.spec.places[name] = place_spec
-        return PlaceRef(name, self.spec)
+    ) -> Union[PlaceRef, Callable]:
+        """Declare a regular place.
+
+        Can be used in three ways:
+
+        1. As a method call (returns PlaceRef for use in arcs):
+           queue = builder.place("queue", type=PlaceType.QUEUE)
+
+        2. As a decorator without parens (infers name from function):
+           @builder.place
+           def queue(bb):
+               return bb.tokens
+
+        3. As a decorator with custom name:
+           @builder.place("custom_name")
+           def my_func(bb):
+               return bb.tokens
+        """
+        # Case 1: Used as decorator without parens - first arg is the function
+        if callable(name_or_func):
+            func = name_or_func
+            place_name = func.__name__
+            place_spec = PlaceSpec(place_name, type, handler=func, state_factory=state_factory)
+            self.spec.places[place_name] = place_spec
+            return PlaceRef(place_name, self.spec)
+
+        # Case 2 & 3: Used with explicit name (as method call or decorator with args)
+        # or called without any args (need to return decorator)
+        if isinstance(name_or_func, str):
+            name = name_or_func
+            place_spec = PlaceSpec(name, type, state_factory=state_factory)
+            self.spec.places[name] = place_spec
+            # Return PlaceRef - it's callable via __call__ for decorator use
+            return PlaceRef(name, self.spec)
+
+        # Case 4: Called without any args - shouldn't happen but handle gracefully
+        # This would be like @builder.place() with empty parens
+        def decorator(func: Callable) -> PlaceRef:
+            place_name = func.__name__
+            place_spec = PlaceSpec(place_name, type, handler=func, state_factory=state_factory)
+            self.spec.places[place_name] = place_spec
+            return PlaceRef(place_name, self.spec)
+        return decorator
 
     def io_input_place(self):
         """Decorator for IOInputPlace with async generator"""
@@ -98,7 +136,17 @@ class NetBuilder:
         guard: Optional[GuardSpec] = None,
         state_factory: Optional[Callable] = None,
     ):
-        """Decorator for transition function"""
+        """Decorator for transition function.
+
+        Args:
+            guard: Optional guard specification
+            state_factory: Optional state factory for transition state
+
+        Usage:
+            @builder.transition()
+            async def my_transition(consumed, bb, timebase):
+                yield {output: token}
+        """
 
         def decorator(func: Callable) -> TransitionRef:
             name = func.__name__