gedcom-x 0.5.8__py3-none-any.whl → 0.5.10__py3-none-any.whl

gedcomx/source_citation.py

@@ -1,4 +1,13 @@
 from typing import Optional
+from .logging_hub import hub, logging
+"""
+======================================================================
+Logging
+======================================================================
+"""
+log = logging.getLogger("gedcomx")
+serial_log = "gedcomx.serialization"
+#=====================================================================
 
 class SourceCitation:
     identifier = 'http://gedcomx.org/v1/SourceCitation'
@@ -11,13 +20,16 @@ class SourceCitation:
     # ...existing code...
 
     @classmethod
-    def _from_json_(cls, data: dict):
+    def _from_json_(cls, data: dict, context = None):
         """
         Create a SourceCitation instance from a JSON-dict (already parsed).
         """
-        lang = data.get('lang', 'en')
-        value = data.get('value')
-        return cls(lang=lang, value=value)
+        object_data = {}
+        if (lang := data.get('lang')) is not None:
+            object_data['lang'] = lang
+        if (value := data.get('value')) is not None:
+            object_data['value'] = value
+        return cls(**object_data)
     
     @property
     def _as_dict_(self):

gedcomx/source_description.py

@@ -5,6 +5,7 @@ from typing import Any, Dict, List, Optional, TYPE_CHECKING
 if TYPE_CHECKING:
     from .document import Document
 
+
 """
 ======================================================================
  Project: Gedcom-X
@@ -31,12 +32,21 @@ from .attribution import Attribution
 from .coverage import Coverage
 from .date import Date
 from .identifier import Identifier, IdentifierList, make_uid
+from .logging_hub import hub, logging
 from .note import Note
 from .resource import Resource
 from .source_citation import SourceCitation
 from .source_reference import SourceReference
 from .textvalue import TextValue
 from .uri import URI
+"""
+======================================================================
+Logging
+======================================================================
+"""
+log = logging.getLogger("gedcomx")
+serial_log = "gedcomx.serialization"
+deserial_log = "gedcomx.deserialization"
 #=====================================================================
 
 
@@ -157,6 +167,8 @@ class SourceDescription:
         self.max_note_count = max_note_count
 
         self.uri = URI(fragment=id) if id else None #TODO Should i take care of this in the collections?
+
+        self._place_holder = False
     
     @property
     def publisher(self) -> Resource | Agent | None:
@@ -195,7 +207,7 @@ class SourceDescription:
                     return False
             self.notes.append(note_to_add)
     
-    def add_source(self, source_to_add: SourceReference):
+    def add_source_reference(self, source_to_add: SourceReference):
         if source_to_add and isinstance(object,SourceReference):
             for current_source in self.sources:
                 if current_source == source_to_add:
@@ -213,102 +225,177 @@ class SourceDescription:
             raise ValueError(f"Cannot add title of type {type(title_to_add)}")
             
     @property
-    def _as_dict_(self) -> Dict[str, Any]:
+    def _as_dict_(self) -> Dict[str, Any] | None:
         from .serialization import Serialization
-        type_as_dict = {}
-
-        if self.id:
-            type_as_dict['id'] = self.id
-        if self.about:
-            type_as_dict['about'] = self.about._as_dict_
-        if self.resourceType:
-            type_as_dict['resourceType'] = getattr(self.resourceType, 'value', self.resourceType)
-        if self.citations:
-            type_as_dict['citations'] = [c._as_dict_ for c in self.citations if c]
-        if self.mediaType:
-            type_as_dict['mediaType'] = self.mediaType
-        if self.mediator:
-            type_as_dict['mediator'] = self.mediator._as_dict_
-        if self.publisher:
-            type_as_dict['publisher'] = self.publisher._as_dict_ #TODO Resource this
-        if self.authors:
-            type_as_dict['authors'] = [a._as_dict_ for a in self.authors if a]
-        if self.sources:
-            type_as_dict['sources'] = [s._as_dict_ for s in self.sources if s]
-        if self.analysis:
-            type_as_dict['analysis'] = self.analysis._as_dict_
-        if self.componentOf:
-            type_as_dict['componentOf'] = self.componentOf._as_dict_ 
-        if self.titles:
-            type_as_dict['titles'] = [t._as_dict_ for t in self.titles if t]
-        if self.notes:
-            type_as_dict['notes'] = [n._as_dict_ for n in self.notes if n]
-        if self.attribution:
-            type_as_dict['attribution'] = self.attribution._as_dict_
-        if self.rights:
-            type_as_dict['rights'] = [r._as_dict_ for r in self.rights if r]
-        if self.coverage:
-            type_as_dict['coverage'] = [c._as_dict_ for c in self.coverage if c]
-        if self.descriptions:
-            type_as_dict['descriptions'] = [d for d in self.descriptions if d]
-        if self.identifiers:
-            type_as_dict['identifiers'] = self.identifiers._as_dict_
-        if self.created is not None:
-            type_as_dict['created'] = self.created
-        if self.modified is not None:
-            type_as_dict['modified'] = self.modified
-        if self.published is not None:
-            type_as_dict['published'] = self.published
-        if self.repository:
-            type_as_dict['repository'] = self.repository._as_dict_ #TODO Resource this
-        if self.uri and self.uri.value:
-            type_as_dict['uri'] = self.uri.value
+        return Serialization.serialize(self)
+        with hub.use(serial_log):
+            log.debug(f"Serializing 'SourceDescription' with id: {self.id}")
+            type_as_dict = {}
 
-        
-        return Serialization.serialize_dict(type_as_dict)
-         
+            if self.id:
+                type_as_dict['id'] = self.id
+            if self.about:
+                type_as_dict['about'] = self.about._as_dict_
+            if self.resourceType:
+                if isinstance(self.resourceType,str):
+                    log.warning(f"'SourceDescription.resourceType' should not be a string {self.resourceType}")
+                    type_as_dict['resourceType'] = self.resourceType
+                else:
+                    type_as_dict['resourceType'] = self.resourceType.value 
+            if self.citations:
+                type_as_dict['citations'] = [c._as_dict_ for c in self.citations if c]
+            if self.mediaType:
+                type_as_dict['mediaType'] = self.mediaType
             
-    @classmethod
-    def _from_json_(cls, data: Dict[str, Any]) -> 'SourceDescription':
-        # TODO Hande Resource/URI
-        
-        # Basic fields
-        id_ = data.get('id')
-        rt = ResourceType(data['resourceType']) if data.get('resourceType') else None
-
-        # Sub-objects
-        citations    = [SourceCitation._from_json_(c) for c in data.get('citations', [])]
-        about        = URI._from_json_(data['about']) if data.get('about') else None
-        mediator     = Resource._from_json_(data['mediator']) if data.get('mediator') else None
-        publisher    = Resource._from_json_(data['publisher']) if data.get('publisher') else None
-        authors      = [Resource._from_json_(a) for a in data.get('authors', [])] if data.get('authors') else None
-        sources      = [SourceReference._from_json_(s) for s in data.get('sources', [])]
-        analysis     = Resource._from_json_(data['analysis']) if data.get('analysis') else None
-        component_of = SourceReference._from_json_(data['componentOf']) if data.get('componentOf') else None
-        titles       = [TextValue._from_json_(t) for t in data.get('titles', [])]
-        notes        = [Note._from_json_(n) for n in data.get('notes', [])]
-        attribution  = Attribution._from_json_(data['attribution']) if data.get('attribution') else None
-        rights       = [URI._from_json_(r) for r in data.get('rights', [])]
-        coverage     = [Coverage._from_json_(cvg) for cvg in data.get('coverage',[])] 
-        descriptions = [TextValue._from_json_(d) for d in data.get('descriptions', [])]
-        identifiers  = IdentifierList._from_json_(data.get('identifiers', []))
+            if self.mediator:
+                type_as_dict['mediator'] = self.mediator._as_dict_
+            if self.publisher:
+                type_as_dict['publisher'] = self.publisher._as_dict_ #TODO Resource this
+            if self.authors:
+                type_as_dict['authors'] = [a._as_dict_ for a in self.authors if a]
+            if self.sources:
+                type_as_dict['sources'] = [s._as_dict_ for s in self.sources if s]
+            
+            
+            if self.analysis:
+                type_as_dict['analysis'] = self.analysis._as_dict_
+            if self.componentOf:
+                type_as_dict['componentOf'] = self.componentOf._as_dict_ 
+            if self.titles:
+                type_as_dict['titles'] = [t._as_dict_ for t in self.titles if t]
+            if self.notes:
+                type_as_dict['notes'] = [n._as_dict_ for n in self.notes if n]
+            if self.attribution:
+                type_as_dict['attribution'] = self.attribution._as_dict_
+            if self.rights:
+                type_as_dict['rights'] = [r._as_dict_ for r in self.rights if r]
+            
+            if self.coverage:
+                type_as_dict['coverage'] = [c._as_dict_ for c in self.coverage if c]
+            
+            if self.descriptions:
+                if not (isinstance(self.descriptions, list) and all(isinstance(x, TextValue) for x in self.descriptions)):
+                    assert False
+                type_as_dict['descriptions'] = [d._as_dict_ for d in self.descriptions if d]
+                
+            if self.identifiers:
+                type_as_dict['identifiers'] = self.identifiers._as_dict_
+            
+            if self.created is not None:
+                type_as_dict['created'] = self.created
+            if self.modified is not None:
+                type_as_dict['modified'] = self.modified
+            if self.published is not None:
+                type_as_dict['published'] = self.published
+            
+            if self.repository:
+                type_as_dict['repository'] = self.repository._as_dict_ #TODO Resource this       
+
+            log.debug(f"'SourceDescription' serialized with fields: '{type_as_dict.keys()}'") 
+            if type_as_dict == {}: log.warning("serializing and empty 'SourceDescription'")
+        return type_as_dict if type_as_dict != {} else None
         
-        created      = Date._from_json_(data['created']) if data.get('created') else None
-        modified     = data.get('modified',None)
-        published    = Date._from_json_(data['published']) if data.get('published') else None
-        repository   = Agent._from_json_(data['repository']) if data.get('repository') else None
-
-        return cls(
-            id=id_, resourceType=rt, citations=citations,
-            mediaType=data.get('mediaType'), about=about,
-            mediator=mediator, publisher=publisher,
-            authors=authors, sources=sources,
-            analysis=analysis, componentOf=component_of,
-            titles=titles, notes=notes, attribution=attribution,
-            rights=rights, coverage=coverage,
-            descriptions=descriptions, identifiers=identifiers,
-            created=created, modified=modified,
-            published=published, repository=repository
-        )
+              
+    @classmethod
+    def _from_json_(cls, data: Dict[str, Any], context: Any = None) -> "SourceDescription":
+        if not isinstance(data, dict):
+            raise TypeError(f"{cls.__name__}._from_json_ expected dict, got {type(data)}")
+
+        source_description_data: Dict[str, Any] = {}
+
+        # ── Scalars ──────────────────────────────────────────────────────────────
+        if (id_ := data.get("id")) is not None:
+            source_description_data["id"] = id_
+        if (media_type := data.get("mediaType")) is not None:
+            source_description_data["mediaType"] = media_type
+        if (mnc := data.get("max_note_count")) is not None:
+            source_description_data["max_note_count"] = int(mnc)
+
+        # resourceType (enum or similar)
+        if (rt := data.get("resourceType")) is not None:
+            source_description_data["resourceType"] = ResourceType(rt)
+
+        # about: URI (accept string or dict)
+        if (about := data.get("about")) is not None:
+            source_description_data["about"] = URI.from_url(about) if isinstance(about, str) else URI._from_json_(about, context)
+
+        # mediator / publisher can be Agent or Resource
+        if (mediator := data.get("mediator")) is not None:
+            if isinstance(mediator, dict) and any(k in mediator for k in ("names", "emails", "accounts", "addresses", "person")):
+                source_description_data["mediator"] = Agent._from_json_(mediator, context)
+            else:
+                source_description_data["mediator"] = Resource._from_json_(mediator, context)
+
+        if (publisher := data.get("publisher")) is not None:
+            if isinstance(publisher, dict) and any(k in publisher for k in ("names", "emails", "accounts", "addresses", "person")):
+                source_description_data["publisher"] = Agent._from_json_(publisher, context)
+            else:
+                source_description_data["publisher"] = Resource._from_json_(publisher, context)
+
+        # repository (Agent)
+        if (repo := data.get("repository")) is not None:
+            source_description_data["repository"] = Agent._from_json_(repo, context)
+
+        # analysis: Document | Resource   (prefer Document when possible)
+        if (analysis := data.get("analysis")) is not None:
+            try:
+                source_description_data["analysis"] = Document._from_json_(analysis, context)
+            except Exception:
+                source_description_data["analysis"] = Resource._from_json_(analysis, context)
+
+        # componentOf: SourceReference
+        if (component := data.get("componentOf")) is not None:
+            source_description_data["componentOf"] = SourceReference._from_json_(component, context)
+
+        # identifiers
+        if (identifiers := data.get("identifiers")) is not None:
+            source_description_data["identifiers"] = IdentifierList._from_json_(identifiers, context)
+
+        # timestamps
+        if (created := data.get("created")) is not None:
+            source_description_data["created"] = created 
+        if (modified := data.get("modified")) is not None:
+            source_description_data["modified"] = modified
+        if (published := data.get("published")) is not None:
+            source_description_data["published"] = published
+
+        # ── Lists ───────────────────────────────────────────────────────────────
+        if (citations := data.get("citations")) is not None:
+            source_description_data["citations"] = [SourceCitation._from_json_(c, context) for c in citations]
+
+        if (authors := data.get("authors")) is not None:
+            source_description_data["authors"] = [Resource._from_json_(a, context) for a in authors]
+
+        if (sources := data.get("sources")) is not None:
+            source_description_data["sources"] = [SourceReference._from_json_(s, context) for s in sources]
+
+        if (titles := data.get("titles")) is not None:
+            source_description_data["titles"] = [
+                (TextValue._from_json_(t, context) if isinstance(t, dict) else TextValue(t))
+                for t in titles
+            ]
+
+        if (notes := data.get("notes")) is not None:
+            source_description_data["notes"] = [Note._from_json_(n, context) for n in notes]
+
+        if (rights := data.get("rights")) is not None:
+            source_description_data["rights"] = [Resource._from_json_(r, context) for r in rights]
+
+        if (coverage := data.get("coverage")) is not None:
+            source_description_data["coverage"] = [Coverage._from_json_(c, context) for c in coverage]
+
+        if (descriptions := data.get("descriptions")) is not None:
+            for d in descriptions:
+                if not isinstance(d, dict): assert False
+            source_description_data["descriptions"] = [
+                (TextValue._from_json_(d, context) if isinstance(d, dict) else TextValue(value="somethings fucked up"))
+                for d in descriptions
+            ]
+
+        # attribution
+        if (attr := data.get("attribution")) is not None:
+            source_description_data["attribution"] = Attribution._from_json_(attr, context) if isinstance(attr, dict) else attr
+
+        return cls(**source_description_data)
 
     

gedcomx/source_reference.py

@@ -10,6 +10,15 @@ from .qualifier import Qualifier
 from .resource import Resource
 
 from .uri import URI
+from .logging_hub import hub, logging
+"""
+======================================================================
+Logging
+======================================================================
+"""
+log = logging.getLogger("gedcomx")
+serial_log = "gedcomx.serialization"
+#=====================================================================
 
 from collections.abc import Sized
 
@@ -52,7 +61,7 @@ class SourceReference:
     version = 'http://gedcomx.org/conceptual-model/v1'
     
     def __init__(self,
-                 description: URI | SourceDescription | None = None,
+                 description: SourceDescription | URI | None = None,
                  descriptionId: Optional[str] = None,
                  attribution: Optional[Attribution] = None,
                  qualifiers: Optional[List[Qualifier]] = None
@@ -85,23 +94,49 @@ class SourceReference:
     
     @property    
     def _as_dict_(self):
-        from .serialization import Serialization
-        type_as_dict = {
-            'description':self.description._as_dict_ if self.description else None,
-            'descriptionId': self.descriptionId.replace("\n"," ").replace("\r"," ") if self.descriptionId else None,
-            'attribution': self.attribution._as_dict_ if self.attribution else None,
-            'qualifiers':[qualifier.__as_dict__ for qualifier in self.qualifiers] if (self.qualifiers and len(self.qualifiers) > 0) else None
-            }
-        return Serialization.serialize_dict(type_as_dict)
+        with hub.use(serial_log):
+            log.debug(f"Serializing 'SourceReference' with 'descriptionId': '{self.descriptionId}'")
+            type_as_dict = {}
+            if self.description is not None:
+                type_as_dict['description']= URI(target=self.description)._as_dict_ if self.description is not None else None
+            if self.descriptionId is not None:
+                type_as_dict['descriptionId']= self.descriptionId.replace("\n"," ").replace("\r"," ") if self.descriptionId else None
+            if self.attribution is not None:
+                type_as_dict['attribution'] = self.attribution._as_dict_ if self.attribution else None
+            if self.qualifiers is not None and self.qualifiers != []:
+                type_as_dict['qualifiers'] = [qualifier.__as_dict__ for qualifier in self.qualifiers] if (self.qualifiers and len(self.qualifiers) > 0) else None
+            log.debug(f"'SourceReference' serialized with fields: {type_as_dict.keys()}") 
+            if type_as_dict == {}: log.warning("serializing and empty 'SourceReference'")  
+        return type_as_dict if type_as_dict != {} else None
       
     @classmethod
-    def _from_json_(cls, data: dict):         
-        """
-        Rehydrate a SourceReference from the dict passed down from JSON deserialization.
-        NOTE: This does not resolve references to SourceDescription objects.
-        """
-        from .serialization import Serialization
-        return Serialization.deserialize(data, SourceReference)
+    def _from_json_(cls, data: dict, context=None) -> "SourceReference":
+        ref = {}
+
+        # Scalars
+        if (descriptionId := data.get("descriptionId")) is not None:
+            ref["descriptionId"] = descriptionId
+
+        # Objects (description could be URI or SourceDescription)
+        if (description := data.get("description")) is not None:
+            # if description is just a string, assume URI
+            if isinstance(description, str):
+                ref["description"] = URI(description)
+            elif isinstance(description, dict):
+                print(">>",description)
+                ref["description"] = Resource._from_json_(description, context)
+                assert False
+        else:
+            pass #TODO
+            #print(ref["descriptionId"])
+
+        if (attribution := data.get("attribution")) is not None:
+            ref["attribution"] = Attribution._from_json_(attribution, context)
+
+        if (qualifiers := data.get("qualifiers")) is not None:
+            ref["qualifiers"] = [Qualifier._from_json_(q, context) for q in qualifiers]
+
+        return cls(**ref)
     
         
 

gedcomx/subject.py

@@ -9,7 +9,7 @@ from typing import List, Optional
 
  Created: 2025-08-25
  Updated:
-   - 2025-08-31: 
+   - 2025-09-03: _from_json_ refactor 
    
 ======================================================================
 """
@@ -22,11 +22,21 @@ GEDCOM Module Types
 from .attribution import Attribution
 from .conclusion import ConfidenceLevel, Conclusion
 from .evidence_reference import EvidenceReference
-from .Extensions.rs10.rsLink import _rsLinkList
+from .Extensions.rs10.rsLink import _rsLinks
 from .identifier import Identifier, IdentifierList
+from .logging_hub import hub, logging
 from .note import Note
 from .resource import Resource
 from .source_reference import SourceReference
+from. uri import URI
+"""
+======================================================================
+Logging
+======================================================================
+"""
+log = logging.getLogger("gedcomx")
+serial_log = "gedcomx.serialization"
+#=====================================================================
 
 
 class Subject(Conclusion):
@@ -46,7 +56,7 @@ class Subject(Conclusion):
                  media: Optional[List[SourceReference]] = [],
                  identifiers: Optional[IdentifierList] = None,
                  uri: Optional[Resource] = None,
-                 links: Optional[_rsLinkList] = None) -> None:
+                 links: Optional[_rsLinks] = None) -> None:
         super().__init__(id, lang, sources, analysis, notes, confidence, attribution,links=links)
         self.extracted = extracted
         self.evidence = evidence
@@ -63,15 +73,50 @@ class Subject(Conclusion):
    
     @property
     def _as_dict_(self):
-        from .serialization import Serialization
-
-        type_as_dict = super()._as_dict_  # Start with base class fields
-        # Only add Relationship-specific fields
-        type_as_dict.update({
-            "extracted": self.extracted,
-            "evidence": [evidence_ref for evidence_ref in self.evidence] if self.evidence else None,
-            "media": [media for media in self.media] if self.media else None,
-            "identifiers": self.identifiers._as_dict_ if self.identifiers else None
+        with hub.use(serial_log):
+            log.debug(f"Serializing 'Subject' with id: '{self.id}'")
+            type_as_dict = super()._as_dict_  # Start with base class fields
+            if type_as_dict is None: type_as_dict = {}
+            if self.extracted:
+                type_as_dict["extracted"] = self.extracted
+            if self.evidence:
+                type_as_dict["evidence"] = [evidence_ref for evidence_ref in self.evidence] if self.evidence else None
+            if self.media:
+                type_as_dict["media"] = [media for media in self.media] if self.media else None
+            if self.identifiers:
+                type_as_dict["identifiers"] = self.identifiers._as_dict_ if self.identifiers else None
+            log.debug(f"'Subject' serialized with fields: '{type_as_dict.keys()}'") 
+            if type_as_dict == {} or len(type_as_dict.keys()) == 0: log.warning("serializing and empty 'Subject' Object")
                            
-        })
-        return Serialization.serialize_dict(type_as_dict)
+        return type_as_dict if type_as_dict != {} else None
+        
+    
+    @classmethod
+    def _dict_from_json_(cls, data: dict, context = None) -> dict:
+        subject_data = Conclusion._dict_from_json_(data,context)
+        
+        # Bool
+        if (extracted := data.get("extracted")) is not None:
+            # cast to bool in case JSON gives "true"/"false" as string
+            if isinstance(extracted, str):
+                subject_data["extracted"] = extracted.lower() == "true"
+            else:
+                subject_data["extracted"] = bool(extracted)
+
+        # Lists
+        if (evidence := data.get("evidence")) is not None:
+            subject_data["evidence"] = [EvidenceReference._from_json_(e, context) for e in evidence]
+
+        if (media := data.get("media")) is not None:
+            subject_data["media"] = [SourceReference._from_json_(m, context) for m in media]
+
+        # Identifiers
+        if (identifiers := data.get("identifiers")) is not None:
+            subject_data["identifiers"] = IdentifierList._from_json_(identifiers, context)
+
+        # URI
+        if (uri := data.get("uri")) is not None:
+            subject_data["uri"] = URI(uri)
+
+        #return cls(**conclusion)
+        return subject_data

gedcomx/textvalue.py

@@ -1,35 +1,89 @@
-from typing import Optional
+from typing import Any, Optional, Dict
+
+"""
+======================================================================
+ Project: Gedcom-X
+ File:    textvalue.py
+ Author:  David J. Cartwright
+ Purpose: 
+
+ Created: 2025-08-25
+ Updated:
+   - 2025-09-03 _from_json_ refactor
+   - 2025-09-04 added _str_ and _repr_ dunders
+   
+======================================================================
+"""
+
+"""
+======================================================================
+GEDCOM Module Types
+======================================================================
+"""
+from .logging_hub import hub, logging
+"""
+======================================================================
+Logging
+======================================================================
+"""
+log = logging.getLogger("gedcomx")
+serial_log = "gedcomx.serialization"
+#=====================================================================
 
 class TextValue:
     identifier = 'http://gedcomx.org/v1/TextValue'
     version = 'http://gedcomx.org/conceptual-model/v1'
 
-    def __init__(self, value: Optional[str] = None, lang: Optional[str] = 'en') -> None:
+    def __init__(self, value: Optional[str] = None, lang: Optional[str] = None) -> None:
         self.lang = lang
         self.value = value
     
     def _append_to_value(self, value_to_append):
         if not isinstance(value_to_append, str):
             raise ValueError(f"Cannot append object of type {type(value_to_append)}.")
-        self.value += ' ' + value_to_append
+        if self.value is None: self.value = value_to_append
+        else: self.value += ' ' + value_to_append
     
     @property
     def _as_dict_(self):
-        return {
-            "lang":self.lang if self.lang else None,
-            "value":self.value if self.value else None
-        }
+        from .serialization import Serialization
+        return Serialization.serialize(self)
+        type_as_dict = {}
+        if self.lang is not None: type_as_dict['lang'] = self.lang
+        if self.value is not None: type_as_dict['value'] = self.value
+        return type_as_dict if type_as_dict != {} else None
     
     def __str__(self):
         return f"{self.value} ({self.lang})"
     
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other,TextValue):
+            if self.value.strip() == other.value.strip():
+                return True
+        return False
+    
     # ...existing code...
 
     @classmethod
-    def _from_json_(cls, data: dict):
+    def _from_json_(cls, data: Any, context: Any = None) -> "TextValue":
         """
-        Create a TextValue instance from a JSON-dict (already parsed).
+        Create a TextValue from JSON.
+        - Accepts a dict like {"value": "...", "lang": "en"} or a plain string shorthand.
+        - Defaults lang to "en" if not provided.
         """
-        value = data.get('value')
-        lang = data.get('lang', 'en')
-        return cls(value=value, lang=lang)
+        if not isinstance(data, dict):
+            raise TypeError(f"{cls.__name__}._from_json_ expected dict or str, got {type(data)}")
+
+        text_value_data: Dict[str, Any] = {}       
+            
+        if (v := data.get("value")) is None:
+            text_value_data["value"] = v
+        if (l := data.get("lang")) is None:
+            text_value_data["lang"] = l
+
+        return cls(**text_value_data)
+    
+    def __repr__(self) -> str:
+        # Debug-friendly: unambiguous constructor-style representation
+        cls = self.__class__.__name__
+        return f"{cls}(value={self.value!r}, lang={self.lang!r})"