Changeset bf30018 in flexoentity

Timestamp:

11/04/25 08:05:04 (2 months ago)

Author:

Enrico Schwass <ennoausberlin@…>

Branches:

master

Children:

4af65b0

Parents:

5c72356

Message:

minor fixes

Location:

flexoentity

Files:

• domain.py (modified) (4 diffs)
• flexo_entity.py (modified) (24 diffs)

flexoentity/domain.py

@@ -1 +1 @@
 from dataclasses import dataclass
-from flexoentity.flexo_entity import FlexOID, FlexoEntity, EntityType, EntityState
+from flexoentity import FlexOID, FlexoEntity, EntityType, EntityState
 
 
 @dataclass
 class Domain(FlexoEntity):
+    """
+    I am a helper class to provide more information than just a
+    domain abbreviation in FlexOID, doing mapping and management
+    """
+    ENTITY_TYPE = EntityType.DOMAIN
+
     fullname: str = ""
     description: str = ""
     classification: str = "UNCLASSIFIED"
-    owner: str = "unknown"
 
     @classmethod
     def default(cls):
-        return cls(domain="GEN")
+        """I return an default instance of myself"""
+        return cls("GENERIC")
 
     def __post_init__(self):
@@ -28 +34 @@
             )
 
-
-        
     @property
     def text_seed(self) -> str:
-        """Deterministic text seed for ID generation."""
-        return f"{self.fullname}|{self.classification}|{self.owner}"
+        """
+        I provide a deterministic text seed for ID generation.
+        FIXME: There might be a better text seed, json probably
+        """
+        return f"{self.fullname}|{self.classification}|{self.owner_id}"
 
     def to_dict(self):
+        """I return a dictionary representing my state"""
         base = super().to_dict()
         base.update({
@@ -41 +49 @@
             "description": self.description,
             "classification": self.classification,
-            "owner": self.owner
         })
         return base
@@ -47 +54 @@
     @classmethod
     def from_dict(cls, data):
+        """I return a new instance of myself, created from state provided by a dictionary"""
         return cls(
             fullname=data.get("fullname", ""),
             description=data.get("description", ""),
             classification=data.get("classification", "UNCLASSIFIED"),
-            owner=data.get("owner", "unknown"),
         )

flexoentity/flexo_entity.py

@@ -17 +17 @@
     - state       (single capital letter)
 
-- My derived properties (`state`, `entity_type`, `version`) read from that ID.
+- My derived properties (state, entity_type, version) read from that ID.
   They are never stored separately, so I cannot become inconsistent.
 
-- My attributes `origin`, `originator_id`, and `owner_id` express authorship
+- My attributes origin, originator_id, and owner_id express authorship
   and workflow context:
-    - `origin` links to the FlexOID of the entity I was derived from
-    - `originator_id` identifies the original creator (UUID)
-    - `owner_id` identifies the current responsible user or process (UUID)
-
-- My optional `domain` field is a semantic hint, useful for filtering or
+    - origin links to the FlexOID of the entity I was derived from
+    - originator_id identifies the original creator (UUID)
+    - owner_id identifies the current responsible user or process (UUID)
+
+- My domain field is a semantic hint, useful for filtering or
   multi-tenant setups, but the canonical domain remains encoded in my ID.
 
@@ -49 +49 @@
   - My identity never changes; only my content or ownership does.
   - My lifecycle transitions (approve, sign, publish) are represented by new
-    FlexOIDs, not by mutating state attributes.
+    FlexOIDs, not by mutating my own attributes.
   - My audit trail and access control live in the provenance layer, not the ID.
 
@@ -73 +73 @@
 
 class EntityType(Enum):
+    """
+    I map a fixed number of entity types to a single unique letter,
+    that structures different types 
+    """
     GENERIC =  "G"
     DOMAIN = "D"
@@ -89 +93 @@
     @classmethod
     def from_letter(cls, a_letter):
+        """I am a convenience constructor method for EntityType(a_letter)"""
         return cls(a_letter)
-
-    # FIXME: Add more mappings
-    def short(self) -> str:
-        mapping = {
-            EntityType.MEDIA: "M",
-            EntityType.DOMAIN: "DOM",
-            EntityType.CATALOG:  "CAT",
-        }
-        return mapping[self]
 
 # ──────────────────────────────────────────────────────────────────────────────
@@ -106 +102 @@
 
 class EntityState(Enum):
+    """I describe the life cycle states for all entity types"""
     DRAFT = "D"
     APPROVED = "A"
@@ -116 +113 @@
 
 
-@dataclass(kw_only=True)
+@dataclass()
 class FlexoEntity(ABC):
     """
     I represent a mutable entity identified by an immutable FlexOID.
 
-    My `flexo_id` is the single source of truth for what I am:
+    My flexo_id is the single source of truth for what I am:
       - it encodes my domain, entity type, version, and lifecycle state.
     I never store those values separately, but derive them on demand.
 
     I extend the raw identity with provenance and authorship data:
-      - `origin`        → the FlexOID of the entity I was derived from
-      - `originator_id` → the UUID of the first creator
-      - `owner_id`      → the UUID of the current responsible person or system
-      - `domain`        → optional semantic domain hint (for filtering or indexing)
+      - origin        -> the FlexOID of the entity I was derived from
+      - originator_id -> the UUID of the first creator
+      - owner_id      -> the UUID of the current responsible person or system
+      - domain        -> FIXME: Explain reasons, why keep domain mutable. semantic
+                            domain hint (for filtering or indexing)
 
     I am designed to be traceable and reproducible:
-      - My identity (`flexo_id`) never mutates.
+      - My identity (flexo_id) never mutates.
       - My lifecycle transitions are represented by new FlexOIDs.
       - My provenance (origin, originator_id, owner_id) can change over time
@@ -139 +137 @@
     Behavior
     ─────────
-    - `state` and `entity_type` are read-only views derived from my FlexOID.
-    - `to_dict()` and `from_dict()` serialize me with human-readable fields
+    - state and entity_type are read-only views derived from my FlexOID.
+    - to_dict() and from_dict() serialize me with human-readable fields
       while preserving the canonical FlexOID.
     - Subclasses (such as questions, media items, or catalogs) extend me with
       domain-specific content and validation, but not with new identity rules.
+    - Subclasses have to define a class attribute ENTITY_TYPE to allow specific instance creation
 
     I am the living, editable layer that connects identity with accountability.
@@ -157 +156 @@
 
     def with_new_owner(self, new_owner: UUID):
-        """Return a clone of this entity with a different owner."""
+        """I return a clone of this entity with a different owner."""
         copy = replace(self)
         copy.owner_id = new_owner
@@ -165 +164 @@
     @abstractmethod
     def text_seed(self) -> str:
-        """Canonicalized text used for ID generation."""
+        """I provide a canonicalized text used for ID generation."""
         raise NotImplementedError("Subclasses must define text_seed property")
 
     @property
     def state(self) -> EntityState:
+        """I return the state derived from my FlexOID"""
         return EntityState(self.flexo_id.state_code)
 
     @property
     def entity_type(self) -> EntityType:
-        return EntityType(self.flexo_id.entity_type) 
+        """I return the entity type derived from my FlexOID"""
+        return EntityType(self.flexo_id.entity_type)
 
     def canonical_seed(self) -> str:
+        """
+        I use a helper method to flatten my text_seed.
+        NOTE:This might become superfluous when text_seed provides this by itself. Redesign possible
+        """
         return canonical_seed(self.text_seed)
 
@@ -182 +187 @@
     @abstractmethod
     def default(cls):
-        """Return a minimal valid instance of this entity (DRAFT state)."""
+        """I return a minimal valid instance of this entity (in DRAFT state)."""
         raise NotImplementedError("Subclasses must implement default()")
 
     def domain_code(self) -> str:
-        """Return canonical domain code for serialization and ID generation."""
+        """
+        I return a canonical domain code for serialization and ID generation.
+        As domains have their own domain code, I need to distinguish between Domains and
+        other FlexoEntities to avoid cyclic structures.
+        FIXME: Write a better comment
+        """
         return self.domain.domain if hasattr(self.domain, "domain") else self.domain
 
@@ -193 +203 @@
         Optionally generate a new FlexOID and fingerprint if none exist.
 
-        I check for subclass attributes `ENTITY_TYPE` and `INITIAL_STATE`.
-        If they exist, I use them to generate a draft FlexOID.
+        I check for subclass attribute ENTITY_TYPE.
+        If it exist, I use it to generate a draft FlexOID.
         Otherwise, I skip ID generation — leaving it to the subclass.
         """
@@ -202 +212 @@
             return
 
-        # Skip if subclass doesn’t declare ENTITY_TYPE / INITIAL_STATE
+        # Skip if subclass doesn’t declare ENTITY_TYPE or initial state
         etype = getattr(self.__class__, "ENTITY_TYPE", None)
         if not etype:
@@ -210 +220 @@
         # Generate a new draft FlexOID
         self.flexo_id = FlexOID.safe_generate(
-            self.domain_code(),
-            etype.value,
-            EntityState.DRAFT.value,
-            self.text_seed,
-            1,
+            domain=self.domain_code(),
+            entity_type=etype.value,
+            estate=EntityState.DRAFT.value,
+            text=self.text_seed,
+            version=1,
         )
 
@@ -234 +244 @@
             "fingerprint": self.fingerprint,
             "origin": self.origin,
+            "originator_id": str(self.originator_id),
+            "owner_id": str(self.owner_id)
         }
 
@@ -239 +251 @@
     def from_dict(cls, data):
         from flexoentity.domain import Domain  # avoid circular import
-        domain = data["domain"]
-        abbrev, fullname = (lambda p: (p[0], p[1] if len(p) > 1 else ""))(domain.split("_", 1))
-        domain_obj = Domain(
-            domain=abbrev
-        )
+        domain_obj = Domain(data.get("domain", "GENERIC"))
         obj = cls(
             domain=domain_obj,
@@ -250 +258 @@
         obj.fingerprint = data.get("fingerprint", "")
         obj.origin = data.get("origin")
+        obj.originator_id = UUID(int=int(data.get("originator_id", "0")))
+        obj.owner_id = UUID(int=int(data.get("owner_id", "0")))
         return obj
-      
+
     def to_json(self, *, indent: int | None = None) -> str:
-        """Serialize entity (and its FlexOID) into JSON."""
+        """I serialize myself (and my FlexOID) into JSON."""
         return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
 
     @classmethod
     def from_json(cls, data_str: str) -> "FlexoEntity":
-        """Deserialize from a JSON string."""
+        """I create a new instance from a JSON string."""
         data = json.loads(data_str)
         return cls.from_dict(data)
@@ -265 +275 @@
     def should_version(state) -> bool:
         """
-        Determine if a given lifecycle state should trigger a version increment.
+        FIXME: This is now superfluous, because lifecycle changes should not increment
+        version at all.
+        I determine if a given lifecycle state should trigger a version increment.
 
         Entities typically version when they move into more stable or
@@ -277 +289 @@
         )
     def _compute_fingerprint(self) -> str:
-        """Always recompute the entity's content fingerprint."""
+        """I always recompute the entity's content fingerprint."""
         seed = self.canonical_seed()
         return hashlib.blake2s(seed.encode("utf-8"), digest_size=8).hexdigest().upper()
 
     def _update_fingerprint(self) -> bool:
-        """Update FlexOID if the content fingerprint changed."""
+        """
+        FIXME: I am not sure if this is correct behaviour.
+        I Update FlexOID if the content fingerprint changed.
+        """
         new_fp = self._compute_fingerprint()
         if new_fp != self.fingerprint:
@@ -296 +311 @@
     def _transition(self, target_state: EntityState):
         """
-        Internal helper for state transitions with version/fingerprint checks
+        I am an internal helper for state transitions with version/fingerprint checks
         and forward-only enforcement.
         """
@@ -326 +341 @@
     @property
     def version(self) -> int:
-        """Extract numeric version from the FlexO-ID string."""
+        """I extract numeric version from the FlexO-ID string."""
         try:
             return int(str(self.flexo_id).rsplit("@", 1)[-1])
@@ -333 +348 @@
 
     def bump_version(self):
-        """Increment version number on the ID."""
+        """I increment the version number on the ID."""
         self.flexo_id = FlexOID.next_version(self.flexo_id)
 
     def lineage(self, repo):
-        """Return full ancestry chain [origin → ... → self]."""
+        """I return full ancestry chain [origin → ... → self]."""
         chain = [self]
         current = self
@@ -347 +362 @@
     def approve(self):
         """
-        Move from DRAFT to APPROVED state.
+        I move from DRAFT to APPROVED state.
         Draft entities receive a new permanent FlexOID with incremented version.
         """
-        
         if self.state == EntityState.DRAFT:
             new_fid = FlexOID.safe_generate(self.domain_code(),
@@ -366 +380 @@
     def sign(self):
         """
-        Mark entity as approved and signed without bumping version.
+        I mark entity as approved and signed without bumping version.
         Only changes the state letter in the FlexOID.
+        FIXME: We need a signature here
         """
         if self.state != EntityState.APPROVED:
@@ -378 +393 @@
     def publish(self):
         """
-        Move from APPROVED or APPROVED_AND_SIGNED to PUBLISHED.
+        I move from APPROVED or APPROVED_AND_SIGNED to PUBLISHED.
         
         Uses allowed_transitions() to verify legality,