shared: implementazione package identity

shared/identity/identifier.py

@@ -0,0 +1,97 @@
+"""
+SMAVS Shared Kernel - Identifier
+
+Defines the base Value Object used to uniquely identify every
+domain element inside the framework.
+
+All domain-specific identifiers inherit from this class.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID, uuid4
+
+__all__ = ["Identifier"]
+
+
+@dataclass(frozen=True, slots=True)
+class Identifier:
+    """
+    Base immutable identifier.
+
+    An Identifier represents the identity of a domain object.
+
+    Internally it stores a UUID while exposing a strongly typed
+    Value Object to the rest of the domain.
+    """
+
+    value: UUID
+
+    @classmethod
+    def new(cls) -> Identifier:
+        """
+        Create a new identifier.
+
+        Returns:
+            A newly generated identifier.
+        """
+        return cls(uuid4())
+
+    @classmethod
+    def from_string(cls, value: str) -> Identifier:
+        """
+        Create an identifier from its string representation.
+
+        Args:
+            value:
+                UUID string.
+
+        Returns:
+            The corresponding identifier.
+
+        Raises:
+            ValueError:
+                If the provided string is not a valid UUID.
+        """
+        return cls(UUID(value))
+
+    @classmethod
+    def from_uuid(cls, value: UUID) -> Identifier:
+        """
+        Create an identifier from an existing UUID.
+
+        Args:
+            value:
+                UUID instance.
+
+        Returns:
+            The corresponding identifier.
+        """
+        return cls(value)
+
+    def __str__(self) -> str:
+        """
+        Return the canonical string representation.
+        """
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        """
+        Return the developer representation.
+        """
+        return f"{self.__class__.__name__}('{self.value}')"
+
+    @property
+    def hex(self) -> str:
+        """
+        Return the hexadecimal representation.
+        """
+        return self.value.hex
+
+    @property
+    def urn(self) -> str:
+        """
+        Return the UUID URN representation.
+        """
+        return self.value.urn