gedcom-x 0.5.5__py3-none-any.whl → 0.5.7__py3-none-any.whl

gedcomx/Serialization.py

@@ -1,401 +1,816 @@
-from typing import Dict
+from __future__ import annotations
+from functools import lru_cache
 
-from .Logging import get_logger
+import enum
+import logging
+import types
+from collections.abc import Sized
+from typing import Any, Dict, List, Set, Tuple, Union, Annotated, ForwardRef, get_args, get_origin
+from typing import Any, Callable, Mapping, List, Dict, Tuple, Set
+from typing import List, Optional
 
-log = get_logger(__name__)
-log.setLevel("DEBUG")
-log.info("Logger initialized.")
+"""
+======================================================================
+ Project: Gedcom-X
+ File:    Serialization.py
+ Author:  David J. Cartwright
+ Purpose: Serialization/Deserialization of gedcomx Objects
 
-from collections.abc import Sized
-from typing import Any, get_origin, get_args, List, Set, Tuple, Dict, Union, ForwardRef, Annotated
-import types
+ Created: 2025-08-25
+ Updated:
+   - 2025-08-31: cleaned up imports and documentation
+   
+======================================================================
+"""
 
-import enum
+"""
+======================================================================
+GEDCOM Module Types
+======================================================================
+"""
+from .Address import Address
+from .Agent import Agent
+from .Attribution import Attribution
+from .Conclusion import ConfidenceLevel
+from .Date import Date
+from .Document import Document, DocumentType, TextType
+from .EvidenceReference import EvidenceReference
+from .Event import Event, EventType, EventRole, EventRoleType
+from .Extensions.rs10.rsLink import _rsLinkList
+from .Fact import Fact, FactType, FactQualifier
+from .Gender import Gender, GenderType
+from .Identifier import IdentifierList, Identifier
+from .LoggingHub import hub, ChannelConfig
+from .Name import Name, NameType, NameForm, NamePart, NamePartType, NamePartQualifier
+from .Note import Note
+from .OnlineAccount import OnlineAccount
+from .Person import Person
+from .PlaceDescription import PlaceDescription
+from .PlaceReference import PlaceReference
+from .Qualifier import Qualifier
+from .Relationship import Relationship, RelationshipType
 from .Resource import Resource
-from .Identifier import IdentifierList
+from .SourceDescription import SourceDescription, ResourceType, SourceCitation, Coverage
+from .SourceReference import SourceReference
+from .TextValue import TextValue
 from .URI import URI
+#======================================================================
+
+log = logging.getLogger("gedcomx")
+deserialization = "gedcomx.deserialization"
+
+hub.start_channel(
+    ChannelConfig(
+        name=deserialization,
+        path=f"logs/{deserialization}.log",
+        level=logging.DEBUG,
+        rotation="size:10MB:3",   # rotate by size, keep 3 backups
+    )
+)
 
 _PRIMITIVES = (str, int, float, bool, type(None))
 
 def _has_parent_class(obj) -> bool:
     return hasattr(obj, '__class__') and hasattr(obj.__class__, '__bases__') and len(obj.__class__.__bases__) > 0
 
-
 class Serialization:
-
+ 
     @staticmethod
     def serialize_dict(dict_to_serialize: dict) -> dict:
         """
-        Iterates through the dict, serilaizing all Gedcom Types into a json compatible value
-        
-        Parameters
-        ----------
-        dict_to_serialize: dict
-            dict that has been created from any Gedcom Type Object's _as_dict_ property
-
-        Raises
-        ------
-        ValueError
-            If `id` is not a valid UUID.
+        Walk a dict and serialize nested GedcomX objects to JSON-compatible values.
+        - Uses `_as_dict_` on your objects when present
+        - Recurse into dicts / lists / sets / tuples
+        - Drops None and empty containers
         """
         def _serialize(value):
             if isinstance(value, (str, int, float, bool, type(None))):
                 return value
-            elif isinstance(value, dict):
+            if hasattr(value, "_as_dict_"):
+                # Expect your objects expose a snapshot via _as_dict_
+                return value._as_dict_
+            if isinstance(value, dict):
                 return {k: _serialize(v) for k, v in value.items()}
-            elif isinstance(value, (list, tuple, set)):
+            if isinstance(value, (list, tuple, set)):
                 return [_serialize(v) for v in value]
-            elif hasattr(value, "_as_dict_"):
-                return value._as_dict_
-            else:
-                return str(value)  # fallback for unknown objects
-        
-        if dict_to_serialize and isinstance(dict_to_serialize,dict):
-            for key, value in dict_to_serialize.items():
-                if value is not None:
-                    dict_to_serialize[key] = _serialize(value)
-        
+            # Fallback: string representation
+            return str(value)
+
+        if isinstance(dict_to_serialize, dict):
+            cooked = {
+                k: _serialize(v)
+                for k, v in dict_to_serialize.items()
+                if v is not None
+            }
+            # prune empty containers (after serialization)
             return {
-                    k: v
-                    for k, v in dict_to_serialize.items()
-                    if v is not None and not (isinstance(v, Sized) and len(v) == 0)
-                }
+                k: v
+                for k, v in cooked.items()
+                if not (isinstance(v, Sized) and len(v) == 0)
+            }
         return {}
-   
+
+    # --- tiny helpers --------------------------------------------------------
     @staticmethod
-    def _coerce_value(value: Any, typ: Any) -> Any:
-        """Coerce `value` to `typ`:
-        - primitives: pass through
-        - containers: recurse into elements
-        - objects: call typ._from_json_(dict) if available and value is dict
-        - already-instantiated objects of typ: pass through
-        - otherwise: return value unchanged
+    def _is_resource(obj: Any) -> bool:
         """
-        def is_enum_type(T) -> bool:
-            """Return True if T (possibly a typing construct) is or contains an Enum type."""
-            origin = get_origin(T)
+        try:
+            from Resource import Resource
+        except Exception:
+            class Resource: pass
+        """
+        return isinstance(obj, Resource)
 
-            # Unwrap Union/Optional/PEP 604 (A | B)
-            if origin in (Union, types.UnionType):
-                return any(is_enum_type(a) for a in get_args(T))
+    @staticmethod
+    def _has_resource_value(x: Any) -> bool:
+        if Serialization._is_resource(x):
+            return True
+        if isinstance(x, (list, tuple, set)):
+            return any(Serialization._has_resource_value(v) for v in x)
+        if isinstance(x, dict):
+            return any(Serialization._has_resource_value(v) for v in x.values())
+        return False
 
-            # Unwrap Annotated[T, ...]
-            if origin is Annotated:
-                return is_enum_type(get_args(T)[0])
+    @staticmethod
+    def _resolve_structure(x: Any, resolver: Callable[[Any], Any]) -> Any:
+        """Return a deep copy with Resources resolved via resolver(Resource)->Any."""
+        if Serialization._is_resource(x):
+            return resolver(x)
+        if isinstance(x, list):
+            return [Serialization._resolve_structure(v, resolver) for v in x]
+        if isinstance(x, tuple):
+            return tuple(Serialization._resolve_structure(v, resolver) for v in x)
+        if isinstance(x, set):
+            return {Serialization._resolve_structure(v, resolver) for v in x}
+        if isinstance(x, dict):
+            return {k: Serialization._resolve_structure(v, resolver) for k, v in x.items()}
+        return x
 
-            # Resolve forward refs / strings if you use them
-            if isinstance(T, ForwardRef):
-                T = globals().get(T.__forward_arg__, T)
-            if isinstance(T, str):
-                T = globals().get(T, T)
+    @classmethod
+    def apply_resource_resolutions(cls, inst: Any, resolver: Callable[[Any], Any]) -> None:
+        """Resolve any queued attribute setters stored on the instance."""
+        setters: List[Callable[[Any], None]] = getattr(inst, "_resource_setters", [])
+        for set_fn in setters:
+            set_fn(inst, resolver)
+        # Optional: clear after applying
+        inst._resource_setters = []
 
-            # Finally check enum-ness
-            try:
-                return issubclass(T, enum.Enum)
-            except TypeError:
-                return False  # not a class (e.g., typing.List[int], etc.)
-        log.debug(f"Coercing value '{value}' of type '{type(value).__name__}' to '{typ}'")
-
-        def _resolve(t):
-            # resolve ForwardRef('Resource') -> actual object if already in globals()
-            if isinstance(t, ForwardRef):
-                return globals().get(t.__forward_arg__, t)
-            return t
-
-        if is_enum_type(typ):
-            log.debug(f"Enum type detected: {typ}")
-            return typ(value)  # cast to enum
-        
-        origin = get_origin(typ)
-        if origin in (Union, types.UnionType):
-            args = tuple(_resolve(a) for a in get_args(typ))
-        else:
-            args = (_resolve(typ),)
-        log.debug(f"Origin: {origin}, args: {args}")
-        
-        if Resource in args and isinstance(value, dict):
-            if Resource in args:
-                log.info(f"Deserializing Resource from value: {value}")
-                return Resource(uri=value.get('resource'), id=value.get('resourceId', None))
-
-        if isinstance(value, _PRIMITIVES):
-            if Resource in args:
-                log.info(f"Deserializing Resource from value: {value}")
-                return Resource(uri=value)
-            if URI in args:
-                log.info(f"Deserializing URI from value: {value}")
-                return URI.from_url(value)
-            return value
+    # --- your deserialize with setters --------------------------------------
+    @classmethod
+    def deserialize(
+        cls,
+        data: Dict[str, Any],
+        class_type: type,
+        *,
+        resolver: Callable[[Any], Any] | None = None,  # pass a function to resolve Resources now
+        queue_setters: bool = True                     # also stash setters on instance for later
+    ) -> Any:
+        class_fields = cls.get_class_fields(class_type.__name__)
+        result: Dict[str, Any] = {}
+        # collect setters that know how to assign back to attributes
+        pending_setters: List[Callable[[Any, Callable[[Any], Any]], None]] = []
+
+        for name, typ in class_fields.items():
+            if name not in data:
+                continue
+            coerced = cls._coerce_value(data[name], typ)
+            result[name] = coerced
+
+            # if this attribute (or inside it) has Resource(s), prepare a setter
+            if cls._has_resource_value(coerced):
+                def make_setter(attr_name: str, raw_value: Any):
+                    # capture references to the *exact* object we just built for this attribute
+                    def _setter(instance: Any, _resolver: Callable[[Any], Any]) -> None:
+                        resolved = cls._resolve_structure(raw_value, _resolver)
+                        setattr(instance, attr_name, resolved)
+                    return _setter
+                pending_setters.append(make_setter(name, coerced))
+
+        # build the instance
+        inst = class_type(**result)
+
+        # apply now, if resolver provided
+        if resolver is not None and pending_setters:
+            for set_fn in pending_setters:
+                set_fn(inst, resolver)
+
+        # optionally store for later (gives you a real attribute assignment later)
+        if queue_setters:
+            # merge if already present
+            existing = getattr(inst, "_resource_setters", [])
+            inst._resource_setters = [*existing, *pending_setters]
+
+        return inst
+
+    @staticmethod
+    def get_class_fields(cls_name) -> Dict:
+        # NOTE: keep imports local to avoid circulars
         
-        if IdentifierList in args:
-                log.error(f"Deserializing IdentifierList from value: {value}")
-                return IdentifierList._from_json_(value)
-  
-        if origin in (list, List):
-            elem_args = get_args(typ)          # NOT get_args(args)
-            elem_t = elem_args[0] if elem_args else Any
-            log.debug(f"List: {typ}, elem={elem_t}")
-            return [Serialization._coerce_value(v, elem_t) for v in (value or [])]
-
-        if origin in (set, Set):
-            (elem_t,) = args or (Any,)
-            return { Serialization._coerce_value(v, elem_t) for v in (value or []) }
-
-        if origin in (tuple, Tuple):
-            if not args:
-                return tuple(value)
-            if len(args) == 2 and args[1] is Ellipsis:  # Tuple[T, ...]
-                elem_t = args[0]
-                return tuple(Serialization._coerce_value(v, elem_t) for v in (value or []))
-            return tuple(Serialization._coerce_value(v, t) for v, t in zip(value, args))
-
-        if origin in (dict, Dict):
-            k_t, v_t = args or (Any, Any)
-            return {
-                Serialization._coerce_value(k, k_t): Serialization._coerce_value(v, v_t)
-                for k, v in (value or {}).items()
+
+        fields = {
+            "GedcomX": {"persons": List[Person]},
+            "Conclusion": {
+                "id": str,
+                "lang": str,
+                "sources": List["SourceReference"],
+                "analysis": Document | Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "uri": "Resource",
+                "max_note_count": int,
+                "links": _rsLinkList,
+            },
+            "Subject": {
+                "id": str,
+                "lang": str,
+                "sources": List["SourceReference"],
+                "analysis": Resource,
+                "notes": List["Note"],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "extracted": bool,
+                "evidence": List[EvidenceReference],
+                "media": List[SourceReference],
+                "identifiers": IdentifierList,
+                "uri": Resource,
+                "links": _rsLinkList,
+            },
+            "Person": {
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "extracted": bool,
+                "evidence": List[EvidenceReference],
+                "media": List[SourceReference],
+                "identifiers": IdentifierList,
+                "private": bool,
+                "gender": Gender,
+                "names": List[Name],
+                "facts": List[Fact],
+                "living": bool,
+                "links": _rsLinkList,
+                #"uri": URI,
+            },
+            "SourceReference": {
+                "description": Resource,
+                "descriptionId": str,
+                "attribution": Attribution,
+                "qualifiers": List[Qualifier],
+            },
+            "Attribution": {
+                "contributor": Resource,
+                "modified": str,
+                "changeMessage": str,
+                "creator": Resource,
+                "created": str,
+            },
+            "SourceDescription": {
+                "id": str,
+                "resourceType": ResourceType,
+                "citations": List[SourceCitation],
+                "mediaType": str,
+                "about": URI,
+                "mediator": Resource,
+                "publisher": Resource,          # forward-ref to avoid circular import
+                "authors": List[Resource],
+                "sources": List[SourceReference],         # SourceReference
+                "analysis": Resource,          # analysis is typically a Document (kept union to avoid cycle)
+                "componentOf": SourceReference,           # SourceReference
+                "titles": List[TextValue],
+                "notes": List[Note],
+                "attribution": Attribution,
+                "rights": List[Resource],
+                "coverage": List[Coverage],               # Coverage
+                "descriptions": List[TextValue],
+                "identifiers": IdentifierList,
+                "created": Date,
+                "modified": Date,
+                "published": Date,
+                "repository": Agent,                    # forward-ref
+                "max_note_count": int,
+            },
+            "Gender": {
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "type": GenderType,
+            },
+            "PlaceReference": {
+                "original": str,
+                "description": URI,
+            },
+            "Relationship": {
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "extracted": bool,
+                "evidence": List[EvidenceReference],
+                "media": List[SourceReference],
+                "identifiers": IdentifierList,
+                "type": RelationshipType,
+                "person1": Resource,
+                "person2": Resource,
+                "facts": List[Fact],
+            },
+            "Document": {
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "type": DocumentType,
+                "extracted": bool,
+                "textType": TextType,
+                "text": str,
+            },
+            "PlaceDescription": {
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "extracted": bool,
+                "evidence": List[EvidenceReference],
+                "media": List[SourceReference],
+                "identifiers": List[IdentifierList],
+                "names": List[TextValue],
+                "type": str,
+                "place": URI,
+                "jurisdiction": Resource,
+                "latitude": float,
+                "longitude": float,
+                "temporalDescription": Date,
+                "spatialDescription": Resource,
+            },
+            "Agent": {
+                "id": str,
+                "identifiers": IdentifierList,
+                "names": List[TextValue],
+                "homepage": URI,
+                "openid": URI,
+                "accounts": List[OnlineAccount],
+                "emails": List[URI],
+                "phones": List[URI],
+                "addresses": List[Address],
+                "person": object | Resource,  # intended Person | Resource
+                "attribution": object,         # GEDCOM5/7 compatibility
+                "uri": URI | Resource,
+            },
+            "Event": {
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "extracted": bool,
+                "evidence": List[EvidenceReference],
+                "media": List[SourceReference],
+                "identifiers": List[Identifier],
+                "type": EventType,
+                "date": Date,
+                "place": PlaceReference,
+                "roles": List[EventRole],
+            },
+            "EventRole": {
+                "id:": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "person": Resource,
+                "type": EventRoleType,
+                "details": str,
+            },
+            "Resource":{
+                "resource":URI,
+                "id":str
+            },
+            "Qualifier":{
+                "name":str,
+                "value":str
+            },
+            "KnownSourceReference":{
+                "name":str,
+                "value":str
+            },
+            "Name": {
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "type": NameType,
+                "nameForms": List[NameForm],  # use string to avoid circulars if needed
+                "date": Date,
+            },
+            "NameForm": {
+                "lang": str,
+                "fullText": str,
+                "parts": List[NamePart],  # use "NamePart" as a forward-ref to avoid circulars
+            },
+            "NamePart": {
+                "type": NamePartType,
+                "value": str,
+                "qualifiers": List["NamePartQualifier"],  # quote if you want to avoid circulars
+            },
+            "Fact":{
+                "id": str,
+                "lang": str,
+                "sources": List[SourceReference],
+                "analysis": Resource | Document,
+                "notes": List[Note],
+                "confidence": ConfidenceLevel,
+                "attribution": Attribution,
+                "type": FactType,
+                "date": Date,
+                "place": PlaceReference,
+                "value": str,
+                "qualifiers": List[FactQualifier],
+                "links": _rsLinkList,
             }
+        }
+        return fields.get(cls_name, {})
+
+
+    @classmethod
+    def _coerce_value(cls, value: Any, Typ: Any) -> Any:
+        """Coerce `value` into `Typ` using the registry (recursively), with verbose logging."""
+        log.debug("COERCE enter: value=%r (type=%s) -> Typ=%r", value, type(value).__name__, Typ)
 
-        # If `typ` has _from_json_ and value is a dict, use it
-        if hasattr(typ, "_from_json_") and isinstance(value, dict):
-            log.info(f"Deserializing {typ} from json method with value: {value}")
-            return typ._from_json_(value)
+        # Enums
+        if cls._is_enum_type(Typ):
+            U = cls._resolve_forward(cls._unwrap(Typ))
+            log.debug("COERCE enum: casting %r to %s", value, getattr(U, "__name__", U))
+            try:
+                ret = U(value)
+                log.debug("COERCE enum: success -> %r", ret)
+                return ret
+            except Exception:
+                log.exception("COERCE enum: failed to cast %r to %s", value, U)
+                return value
 
-        # If already the right type, keep it
+        # Unwrap typing once
+        T = cls._resolve_forward(cls._unwrap(Typ))
+        origin = get_origin(T) or T
+        args = get_args(T)
+        log.debug("COERCE typing: unwrapped Typ=%r -> T=%r, origin=%r, args=%r", Typ, T, origin, args)
+
+        # Late imports to reduce circulars (and to allow logging if they aren't available)
+        '''
         try:
-            if isinstance(value, typ):
+            from gedcomx.Resource import Resource
+            from gedcomx.URI import URI
+            from gedcomx.Identifier import IdentifierList
+            _gx_import_ok = True
+        except Exception as _imp_err:
+            _gx_import_ok = False
+            Resource = URI = IdentifierList = object  # fallbacks avoid NameError
+            log.debug("COERCE imports: gedcomx types not available (%r); using object fallbacks", _imp_err)
+        '''
+
+        # Strings to Resource/URI
+        if isinstance(value, str):
+            if T is Resource:
+                log.debug("COERCE str->Resource: %r", value)
+                try:
+                    ret = Resource(uri=value)
+                    log.debug("COERCE str->Resource: built %r", ret)
+                    return ret
+                except Exception:
+                    log.exception("COERCE str->Resource: failed for %r", value)
+                    return value
+            if T is URI:
+                log.debug("COERCE str->URI: %r", value)
+                try:
+                    ret: Any = URI.from_url(value)
+                    log.debug("COERCE str->URI: built %r", ret)
+                    return ret
+                except Exception:
+                    log.exception("COERCE str->URI: failed for %r", value)
+                    return value
+            log.debug("COERCE str passthrough: target %r is not Resource/URI", T)
+            return value
+
+        # Dict to Resource
+        if T is Resource and isinstance(value, dict):
+            log.debug("COERCE dict->Resource: %r", value)
+            try:
+                ret = Resource(uri=value.get("resource"), id=value.get("resourceId"))
+                log.debug("COERCE dict->Resource: built %r", ret)
+                return ret
+            except Exception:
+                log.exception("COERCE dict->Resource: failed for %r", value)
+                return value
+
+        # IdentifierList special
+        if T is IdentifierList:
+            log.debug("COERCE IdentifierList: %r", value)
+            try:
+                ret = IdentifierList._from_json_(value)
+                log.debug("COERCE IdentifierList: built %r", ret)
+                return ret
+            except Exception:
+                log.exception("COERCE IdentifierList: _from_json_ failed for %r", value)
+                return value
+
+        # Containers
+        if cls._is_list_like(T):
+            elem_t = args[0] if args else Any
+            log.debug("COERCE list-like: len=%s, elem_t=%r", len(value or []), elem_t)
+            try:
+                ret = [cls._coerce_value(v, elem_t) for v in (value or [])]
+                log.debug("COERCE list-like: result sample=%r", ret[:3] if isinstance(ret, list) else ret)
+                return ret
+            except Exception:
+                log.exception("COERCE list-like: failed for value=%r elem_t=%r", value, elem_t)
+                return value
+
+        if cls._is_set_like(T):
+            elem_t = args[0] if args else Any
+            log.debug("COERCE set-like: len=%s, elem_t=%r", len(value or []), elem_t)
+            try:
+                ret = {cls._coerce_value(v, elem_t) for v in (value or [])}
+                log.debug("COERCE set-like: result size=%d", len(ret))
+                return ret
+            except Exception:
+                log.exception("COERCE set-like: failed for value=%r elem_t=%r", value, elem_t)
+                return value
+
+        if cls._is_tuple_like(T):
+            log.debug("COERCE tuple-like: value=%r, args=%r", value, args)
+            try:
+                if not value:
+                    log.debug("COERCE tuple-like: empty/None -> ()")
+                    return tuple(value or ())
+                if len(args) == 2 and args[1] is Ellipsis:
+                    elem_t = args[0]
+                    ret = tuple(cls._coerce_value(v, elem_t) for v in (value or ()))
+                    log.debug("COERCE tuple-like variadic: size=%d", len(ret))
+                    return ret
+                ret = tuple(cls._coerce_value(v, t) for v, t in zip(value, args))
+                log.debug("COERCE tuple-like fixed: size=%d", len(ret))
+                return ret
+            except Exception:
+                log.exception("COERCE tuple-like: failed for value=%r args=%r", value, args)
+                return value
+
+        if cls._is_dict_like(T):
+            k_t = args[0] if len(args) >= 1 else Any
+            v_t = args[1] if len(args) >= 2 else Any
+            log.debug("COERCE dict-like: keys=%s, k_t=%r, v_t=%r", len((value or {}).keys()), k_t, v_t)
+            try:
+                ret = {
+                    cls._coerce_value(k, k_t): cls._coerce_value(v, v_t)
+                    for k, v in (value or {}).items()
+                }
+                log.debug("COERCE dict-like: result size=%d", len(ret))
+                return ret
+            except Exception:
+                log.exception("COERCE dict-like: failed for value=%r k_t=%r v_t=%r", value, k_t, v_t)
+                return value
+
+        # Objects via registry
+        if isinstance(T, type) and isinstance(value, dict):
+            fields = cls.get_class_fields(T.__name__) or {}
+            log.debug(
+                "COERCE object: class=%s, input_keys=%s, registered_fields=%s",
+                T.__name__, list(value.keys()), list(fields.keys())
+            )
+            if fields:
+                kwargs = {}
+                present = []
+                for fname, ftype in fields.items():
+                    if fname in value:
+                        resolved = cls._resolve_forward(cls._unwrap(ftype))
+                        log.debug("COERCE object.field: %s.%s -> %r, raw=%r", T.__name__, fname, resolved, value[fname])
+                        try:
+                            coerced = cls._coerce_value(value[fname], resolved)
+                            kwargs[fname] = coerced
+                            present.append(fname)
+                            log.debug("COERCE object.field: %s.%s coerced -> %r", T.__name__, fname, coerced)
+                        except Exception:
+                            log.exception("COERCE object.field: %s.%s failed", T.__name__, fname)
+                unknown = [k for k in value.keys() if k not in fields]
+                if unknown:
+                    log.debug("COERCE object: %s unknown keys ignored: %s", T.__name__, unknown)
+                try:
+                    log.debug("COERCE object: instantiate %s(**%s)", T.__name__, present)
+                    ret = T(**kwargs)
+                    log.debug("COERCE object: success -> %r", ret)
+                    return ret
+                except TypeError as e:
+                    log.error("COERCE object: instantiate %s failed with kwargs=%s: %s", T.__name__, list(kwargs.keys()), e)
+                    log.debug("COERCE object: returning partially coerced dict")
+                    return kwargs
+
+        # Already correct type?
+        try:
+            if isinstance(value, T):
+                log.debug("COERCE passthrough: value already instance of %r", T)
                 return value
         except TypeError:
-            log.debug(f"Could not coerce value '{value}' to type '{typ}'")
-            pass  # `typ` may be a typing construct not valid for isinstance
+            log.debug("COERCE isinstance not applicable: T=%r", T)
 
-        # Fallback: leave as-is
-        log.debug(f"Returning '{type(value)}' type")
+        log.debug("COERCE fallback: returning original value=%r (type=%s)", value, type(value).__name__)
         return value
 
+
+        # Dict to Resource
+        if T is Resource and isinstance(value, dict):
+            log.debug("COERCE dict->Resource: %r", value)
+            try:
+                ret = Resource(uri=value.get("resource"), id=value.get("resourceId"))
+                log.debug("COERCE dict->Resource: built %r", ret)
+                return ret
+            except Exception:
+                log.exception("COERCE dict->Resource: failed for %r", value)
+                return value
+
+        # IdentifierList special
+        if T is IdentifierList:
+            log.debug("COERCE IdentifierList: %r", value)
+            try:
+                ret = IdentifierList._from_json_(value)
+                log.debug("COERCE IdentifierList: built %r", ret)
+                return ret
+            except Exception:
+                log.exception("COERCE IdentifierList: _from_json_ failed for %r", value)
+                return value
+
+        # Containers
+        if self._is_list_like(T):
+            elem_t = args[0] if args else Any
+            log.debug("COERCE list-like: len=%s, elem_t=%r", len(value or []), elem_t)
+            try:
+                ret = [self._coerce_value(v, elem_t) for v in (value or [])]
+                log.debug("COERCE list-like: result sample=%r", ret[:3] if isinstance(ret, list) else ret)
+                return ret
+            except Exception:
+                log.exception("COERCE list-like: failed for value=%r elem_t=%r", value, elem_t)
+                return value
+
+        if self._is_set_like(T):
+            elem_t = args[0] if args else Any
+            log.debug("COERCE set-like: len=%s, elem_t=%r", len(value or []), elem_t)
+            try:
+                ret = {self._coerce_value(v, elem_t) for v in (value or [])}
+                log.debug("COERCE set-like: result size=%d", len(ret))
+                return ret
+            except Exception:
+                log.exception("COERCE set-like: failed for value=%r elem_t=%r", value, elem_t)
+                return value
+
+        if self._is_tuple_like(T):
+            log.debug("COERCE tuple-like: value=%r, args=%r", value, args)
+            try:
+                if not value:
+                    log.debug("COERCE tuple-like: empty/None -> ()")
+                    return tuple(value or ())
+                if len(args) == 2 and args[1] is Ellipsis:
+                    elem_t = args[0]
+                    ret = tuple(self._coerce_value(v, elem_t) for v in (value or ()))
+                    log.debug("COERCE tuple-like variadic: size=%d", len(ret))
+                    return ret
+                ret = tuple(self._coerce_value(v, t) for v, t in zip(value, args))
+                log.debug("COERCE tuple-like fixed: size=%d", len(ret))
+                return ret
+            except Exception:
+                log.exception("COERCE tuple-like: failed for value=%r args=%r", value, args)
+                return value
+
+        if self._is_dict_like(T):
+            k_t = args[0] if len(args) >= 1 else Any
+            v_t = args[1] if len(args) >= 2 else Any
+            log.debug("COERCE dict-like: keys=%s, k_t=%r, v_t=%r", len((value or {}).keys()), k_t, v_t)
+            try:
+                ret = {
+                    self._coerce_value(k, k_t): self._coerce_value(v, v_t)
+                    for k, v in (value or {}).items()
+                }
+                log.debug("COERCE dict-like: result size=%d", len(ret))
+                return ret
+            except Exception:
+                log.exception("COERCE dict-like: failed for value=%r k_t=%r v_t=%r", value, k_t, v_t)
+                return value
+
+        # Objects via registry
+        if isinstance(T, type) and isinstance(value, dict):
+            fields = self.get_class_fields(T.__name__) or {}
+            log.debug(
+                "COERCE object: class=%s, input_keys=%s, registered_fields=%s",
+                T.__name__, list(value.keys()), list(fields.keys())
+            )
+            if fields:
+                kwargs = {}
+                present = []
+                for fname, ftype in fields.items():
+                    if fname in value:
+                        resolved = self._resolve_forward(self._unwrap(ftype))
+                        log.debug("COERCE object.field: %s.%s -> %r, raw=%r", T.__name__, fname, resolved, value[fname])
+                        try:
+                            coerced = self._coerce_value(value[fname], resolved)
+                            kwargs[fname] = coerced
+                            present.append(fname)
+                            log.debug("COERCE object.field: %s.%s coerced -> %r", T.__name__, fname, coerced)
+                        except Exception:
+                            log.exception("COERCE object.field: %s.%s failed", T.__name__, fname)
+                unknown = [k for k in value.keys() if k not in fields]
+                if unknown:
+                    log.debug("COERCE object: %s unknown keys ignored: %s", T.__name__, unknown)
+                try:
+                    log.debug("COERCE object: instantiate %s(**%s)", T.__name__, present)
+                    ret = T(**kwargs)
+                    log.debug("COERCE object: success -> %r", ret)
+                    return ret
+                except TypeError as e:
+                    log.warning("COERCE object: instantiate %s failed with kwargs=%s: %s", T.__name__, list(kwargs.keys()), e)
+                    log.debug("COERCE object: returning partially coerced dict")
+                    return kwargs
+
+        # Already correct type?
+        try:
+            if isinstance(value, T):
+                log.debug("COERCE passthrough: value already instance of %r", T)
+                return value
+        except TypeError:
+            log.debug("COERCE isinstance not applicable: T=%r", T)
+
+        log.debug("COERCE fallback: returning original value=%r (type=%s)", value, type(value).__name__)
+        return value
+
+    # -------------------------- TYPE HELPERS --------------------------
+
     @staticmethod
-    def get_class_fields(cls_name) -> Dict:
-        from typing import List, Optional
-        from gedcomx.Attribution import Attribution
-        from gedcomx.Document import Document  , DocumentType, TextType 
-        from gedcomx.Note import Note
-        from gedcomx.Resource import Resource
-        from gedcomx.SourceReference import SourceReference
-        from gedcomx.extensions.rs10.rsLink import _rsLinkList
-        from gedcomx.Conclusion import ConfidenceLevel
-        from gedcomx.EvidenceReference import EvidenceReference
-        from gedcomx.Identifier import IdentifierList
-        from gedcomx.Gender import  Gender, GenderType
-        from gedcomx.Fact import Fact
-        from gedcomx.Name import Name  
-        from gedcomx.URI import URI
-        from gedcomx.Qualifier import Qualifier 
-        from gedcomx.PlaceDescription import PlaceDescription
-        from gedcomx.PlaceReference import PlaceReference   
-        from gedcomx.Person import Person
-        from gedcomx.Relationship import Relationship, RelationshipType
-        from gedcomx.Identifier import Identifier   
-        from gedcomx.Date import Date
-        from gedcomx.TextValue import TextValue
-        from gedcomx.Address import Address
-        from gedcomx.OnlineAccount import OnlineAccount
-        from gedcomx.Event import Event, EventType, EventRole
-        from .SourceDescription import SourceDescription
-
-        fields = { 'Conclusion' : {
-                                    "id": str,
-                                    "lang": str,
-                                    "sources": List["SourceReference"],
-                                    "analysis": Document | Resource,
-                                    "notes": List[Note],
-                                    "confidence": ConfidenceLevel,
-                                    "attribution": Attribution,
-                                    "uri": "Resource",
-                                    "max_note_count": int,
-                                    "links": _rsLinkList
-                                    },
-                    'Subject' : {
-                                    "id": str,
-                                    "lang": str,
-                                    "sources": List["SourceReference"],
-                                    "analysis": Resource,
-                                    "notes": List["Note"],
-                                    "confidence": ConfidenceLevel,
-                                    "attribution": Attribution,
-                                    "extracted": bool,
-                                    "evidence": List[EvidenceReference],
-                                    "media": List[SourceReference],
-                                    "identifiers": IdentifierList,
-                                    "uri": Resource,
-                                    "links": _rsLinkList
-                                },
-                    'Person' : {
-                                    "id": str,
-                                    "lang": str,
-                                    "sources": List[SourceReference],
-                                    "analysis": Resource,
-                                    "notes": List[Note],
-                                    "confidence": ConfidenceLevel,
-                                    "attribution": Attribution,
-                                    "extracted": bool,
-                                    "evidence": List[EvidenceReference],
-                                    "media": List[SourceReference],
-                                    "identifiers": IdentifierList,
-                                    "private": bool,
-                                    "gender": Gender,
-                                    "names": List[Name],
-                                    "facts": List[Fact],
-                                    "living": bool,
-                                    "links": _rsLinkList,
-                                    'uri': Resource
-                                },
-                    'SourceReference' : {
-                                    "description": SourceDescription | URI | Resource,
-                                    "descriptionId": str,
-                                    "attribution": Attribution,
-                                    "qualifiers": List[Qualifier],
-},
-                    'Attribution' : {
-                                    "contributor": Resource | Attribution,
-                                    "modified": str,
-                                    "changeMessage": str,
-                                    "creator": Resource | Attribution,
-                                    "created": str  
-        },
-                    'Gender' : {
-                                    "id": str,
-                                    "lang": str,
-                                    "sources": List[SourceReference],
-                                    "analysis": Resource,
-                                    "notes": List[Note],
-                                    "confidence": ConfidenceLevel,
-                                    "attribution": Attribution,
-                                    "type": GenderType,
-                                                    },
-                    'PlaceReference' : {
-                                    "original": str,
-                                    "description": PlaceDescription | URI,
-                                    },
-                    'Relationship' : {
-                                    "id": str,
-                                    "lang": str,
-                                    "sources": List[SourceReference],
-                                    "analysis": Document | Resource,
-                                    "notes": List[Note],
-                                    "confidence": ConfidenceLevel,
-                                    "attribution": Attribution,
-                                    "extracted": bool,
-                                    "evidence": List[EvidenceReference],
-                                    "media": List[SourceReference],
-                                    "identifiers": IdentifierList,
-                                    "type": RelationshipType,
-                                    "person1": Person | Resource,
-                                    "person2": Person | Resource,
-                                    "facts": List[Fact],
-},
-                    'Document' : {
-                                    "id": str,
-                                    "lang": str,
-                                    "sources": List[SourceReference],
-                                    "analysis": Resource,
-                                    "notes": List[Note],
-                                    "confidence": ConfidenceLevel,
-                                    "attribution": Attribution,
-                                    "type": DocumentType,
-                                    "extracted": bool,
-                                    "textType": TextType,
-                                    "text": str,
-                                },
-                    'PlaceDescription' : {
-                                    "id": str,
-                                    "lang": str,
-                                    "sources": List[SourceReference],
-                                    "analysis": Resource,
-                                    "notes": List[Note],
-                                    "confidence": ConfidenceLevel,
-                                    "attribution": Attribution,
-                                    "extracted": bool,
-                                    "evidence": List[EvidenceReference],
-                                    "media": List[SourceReference],
-                                    "identifiers": List[IdentifierList],
-                                    "names": List[TextValue],
-                                    "type": str,
-                                    "place": URI,
-                                    "jurisdiction": Resource | PlaceDescription,
-                                    "latitude": float,
-                                    "longitude": float,
-                                    "temporalDescription": Date,
-                                    "spatialDescription": Resource,
-                                },
-                    "Agent" : {
-    "id": str,
-    "identifiers": IdentifierList,
-    "names": List[TextValue],
-    "homepage": URI,
-    "openid": URI,
-    "accounts": List[OnlineAccount],
-    "emails": List[URI],
-    "phones": List[URI],
-    "addresses": List[Address],
-    "person": object | Resource,  # intended to be Person | Resource
-    # "xnotes": List[Note],  # commented out in your __init__
-    "attribution": object,  # for GEDCOM5/7 compatibility
-    "uri": URI | Resource,
-},
-'Event' : {
-    "id": str,
-    "lang": str,
-    "sources": List[SourceReference],
-    "analysis": Resource,
-    "notes": List[Note],
-    "confidence": ConfidenceLevel,
-    "attribution": Attribution,
-    "extracted": bool,
-    "evidence": List[EvidenceReference],
-    "media": List[SourceReference],
-    "identifiers": List[Identifier],
-    "type": EventType,
-    "date": Date,
-    "place": PlaceReference,
-    "roles": List[EventRole],
-}
-
-}
-        
-        
-        return fields[cls_name] if cls_name in fields else {}
+    @lru_cache(maxsize=None)
+    def _unwrap(T: Any) -> Any:
+        origin = get_origin(T)
+        if origin is None:
+            return T
+        if str(origin).endswith("Annotated"):
+            args = get_args(T)
+            return Serialization._unwrap(args[0]) if args else Any
+        if origin in (Union, types.UnionType):
+            args = tuple(a for a in get_args(T) if a is not type(None))
+            return Serialization._unwrap(args[0]) if len(args) == 1 else tuple(Serialization._unwrap(a) for a in args)
+        return T
 
     @staticmethod
-    def deserialize(data: dict[str, Any], class_type) -> Any:
-        """
-        Deserialize `data` according to `fields` (field -> type).
-        - Primitives are assigned directly.
-        - Objects use `type._from_json_(dict)` when present.
-        - Lists/Sets/Tuples/Dicts are recursively processed.
-        Returns (result, unknown_keys).
-        """
-        log.debug(f"Deserializing '{data}' into '{class_type.__name__}'")
-        class_fields = Serialization.get_class_fields(str(class_type.__name__))
-        if class_fields == {}:
-            log.warning(f"No class fields found for '{class_type.__name__}'")
-        log.debug(f"class fields: {class_fields}")
-        result: dict[str, Any] = {}
-        known = set(class_fields.keys())
-        log.debug(f"keys found in JSON: {data.keys()}")
-        #log.debug(f"known fields: {known}")
-        for name, typ in class_fields.items():
-            if name in data:
-                log.debug(f"Field '{name}' of {class_type.__name__} found in data")
-                result[name] = Serialization._coerce_value(data[name], typ)
-                #if type(result[name]) != class_fields[name]:# TODO Write better type checking 
-                #    log.error(f"Field '{name}' of {class_type.__name__} was expected to be of type '{class_fields[name]}', but got '{type(result[name])}' with value '{result[name]}'")
-                #    raise TypeError(f"Field '{name}' expected type '{class_fields[name]}', got '{type(result[name])}'")
-                log.debug(f"Field '{name}' of '{class_type.__name__}' resulted in a '{type(result[name]).__name__}' with value '{result[name]}'")
-            else:
-                log.debug(f"Field '{name}' of '{class_type.__name__}' not found in JSON data")
-
-        unknown_keys = [k for k in data.keys() if k not in known]
-        log.info(f"Creating instance of {class_type.__name__} with fields: {result.keys()}")
-        new_cls = class_type(**result)
-        log.debug(f"Deserialized {class_type.__name__} with unknown keys: {unknown_keys}")
-        return new_cls  # type: ignore, unknown_keys
+    @lru_cache(maxsize=None)
+    def _resolve_forward(T: Any) -> Any:
+        if isinstance(T, ForwardRef):
+            return globals().get(T.__forward_arg__, T)
+        if isinstance(T, str):
+            return globals().get(T, T)
+        return T
+
+    @staticmethod
+    @lru_cache(maxsize=None)
+    def _is_enum_type(T: Any) -> bool:
+        U = Serialization._resolve_forward(Serialization._unwrap(T))
+        try:
+            return isinstance(U, type) and issubclass(U, enum.Enum)
+        except TypeError:
+            return False
+
+    @staticmethod
+    def _is_list_like(T: Any) -> bool:
+        origin = get_origin(T) or T
+        return origin in (list, List)
+
+    @staticmethod
+    def _is_set_like(T: Any) -> bool:
+        origin = get_origin(T) or T
+        return origin in (set, Set)
+
+    @staticmethod
+    def _is_tuple_like(T: Any) -> bool:
+        origin = get_origin(T) or T
+        return origin in (tuple, Tuple)
+
+    @staticmethod
+    def _is_dict_like(T: Any) -> bool:
+        origin = get_origin(T) or T
+        return origin in (dict, Dict)