followthemoney.property

  1from banal import is_mapping, as_bool
  2from typing import TYPE_CHECKING, cast, Any, List, Optional, TypedDict
  3
  4from followthemoney.exc import InvalidModel
  5from followthemoney.types import registry
  6from followthemoney.rdf import NS, URIRef
  7from followthemoney.util import gettext, get_entity_id
  8
  9if TYPE_CHECKING:
 10    from followthemoney.schema import Schema
 11    from followthemoney.model import Model
 12
 13
 14class ReverseSpec(TypedDict, total=False):
 15    name: str
 16    label: Optional[str]
 17    hidden: Optional[bool]
 18
 19
 20class PropertyDict(TypedDict, total=False):
 21    label: Optional[str]
 22    description: Optional[str]
 23    type: Optional[str]
 24    hidden: Optional[bool]
 25    matchable: Optional[bool]
 26    deprecated: Optional[bool]
 27    maxLength: Optional[int]
 28    # stub: Optional[bool]
 29    rdf: Optional[str]
 30    range: Optional[str]
 31    format: Optional[str]
 32
 33
 34class PropertySpec(PropertyDict):
 35    reverse: ReverseSpec
 36
 37
 38class PropertyToDict(PropertyDict, total=False):
 39    name: str
 40    qname: str
 41    reverse: Optional[str]
 42    stub: Optional[bool]
 43
 44
 45class Property:
 46    """A definition of a value-holding field on a schema. Properties define
 47    the field type and other possible constraints. They also serve as entity
 48    to entity references."""
 49
 50    __slots__ = (
 51        "model",
 52        "schema",
 53        "name",
 54        "qname",
 55        "_label",
 56        "_hash",
 57        "_description",
 58        "hidden",
 59        "type",
 60        "matchable",
 61        "deprecated",
 62        "max_length",
 63        "_range",
 64        "format",
 65        "range",
 66        "stub",
 67        "_reverse",
 68        "reverse",
 69        "uri",
 70    )
 71
 72    #: Invalid property names.
 73    RESERVED = ["id", "caption", "schema", "schemata"]
 74
 75    def __init__(self, schema: "Schema", name: str, data: PropertySpec) -> None:
 76        #: The schema which the property is defined for. This is always the
 77        #: most abstract schema that has this property, not the possible
 78        #: child schemata that inherit it.
 79        self.schema = schema
 80
 81        #: Machine-readable name for this property.
 82        self.name = name
 83
 84        #: Qualified property name, which also includes the schema name.
 85        self.qname = "%s:%s" % (schema.name, self.name)
 86        if self.name in self.RESERVED:
 87            raise InvalidModel("Reserved name: %s" % self.name)
 88
 89        self._hash = hash("<Property(%r)>" % self.qname)
 90
 91        self._label = data.get("label", name)
 92        self._description = data.get("description")
 93
 94        #: This property is deprecated and should not be used.
 95        self.deprecated = as_bool(data.get("deprecated", False))
 96
 97        #: This property should not be shown or mentioned in the user interface.
 98        self.hidden = as_bool(data.get("hidden"))
 99
100        type_ = data.get("type", "string")
101        if type_ is None or type_ not in registry.named:
102            raise InvalidModel("Invalid type: %s" % type_)
103
104        #: The data type for this property.
105        self.type = registry[type_]
106
107        #: Whether this property should be used for matching and cross-referencing.
108        _matchable = data.get("matchable")
109        if _matchable is not None:
110            self.matchable = as_bool(data.get("matchable"))
111        else:
112            self.matchable = self.type.matchable
113
114        #: The maximum length of the property value.
115        self.max_length = int(data.get("maxLength") or self.type.max_length)
116
117        #: If the property is of type ``entity``, the set of valid schema to be added
118        #: in this property can be constrained. For example, an asset can be owned,
119        #: but a person cannot be owned.
120        self._range = data.get("range")
121        self.range: Optional["Schema"] = None
122
123        #: If the property is of type ``identifier``, a more narrow definition of the
124        #: identifier format can be provided. For example, LEI, INN or IBAN codes
125        #: can be automatically validated.
126        self.format: Optional[str] = data.get("format")
127
128        #: When a property points to another schema, a reverse property is added for
129        #: various administrative reasons. These properties are, however, not real
130        #: and cannot be written to. That's why they are marked as stubs and adding
131        #: values to them will raise an exception.
132        self.stub: Optional[bool] = False
133
134        #: When a property points to another schema, a stub reverse property is
135        #: added as a place to store metadata to help display the link in inverted
136        #: views.
137        self._reverse = data.get("reverse")
138        self.reverse: Optional["Property"] = None
139
140        #: RDF term for this property (i.e. the predicate URI).
141        self.uri = URIRef(cast(str, data.get("rdf", NS[self.qname])))
142
143    def generate(self, model: "Model") -> None:
144        """Setup method used when loading the model in order to build out the reverse
145        links of the property."""
146        model.properties.add(self)
147
148        if self.type == registry.entity:
149            if self.range is None and self._range is not None:
150                self.range = model.get(self._range)
151
152            if self.reverse is None and self.range and self._reverse:
153                if not is_mapping(self._reverse):
154                    raise InvalidModel("Invalid reverse: %s" % self)
155                self.reverse = self.range._add_reverse(model, self._reverse, self)
156
157    @property
158    def label(self) -> str:
159        """User-facing title for this property."""
160        return gettext(self._label)
161
162    @property
163    def description(self) -> str:
164        """A longer description of the semantics of this property."""
165        return gettext(self._description)
166
167    def specificity(self, value: str) -> float:
168        """Return a measure of how precise the given value is."""
169        if not self.matchable:
170            return 0.0
171        return self.type.specificity(value)
172
173    def validate(self, data: List[Any]) -> Optional[str]:
174        """Validate that the data should be stored.
175
176        Since the types system doesn't really have validation, this currently
177        tries to normalize the value to see if it passes strict parsing.
178        """
179        values = []
180        for val in data:
181            if self.stub:
182                return gettext("Property cannot be written")
183            val = get_entity_id(val)
184            if val is None:
185                continue
186            if not self.type.validate(val):
187                return gettext("Invalid value")
188            if val is not None:
189                values.append(val)
190        return None
191
192    def __eq__(self, other: Any) -> bool:
193        return self._hash == hash(other)
194
195    def __hash__(self) -> int:
196        return self._hash
197
198    def to_dict(self) -> PropertyToDict:
199        """Return property metadata in a serializable form."""
200        data: PropertyToDict = {
201            "name": self.name,
202            "qname": self.qname,
203            "label": self.label,
204            "type": self.type.name,
205            "maxLength": self.max_length,
206        }
207        if self.description:
208            data["description"] = self.description
209        if self.stub:
210            data["stub"] = True
211        if self.matchable:
212            data["matchable"] = True
213        if self.hidden:
214            data["hidden"] = True
215        if self.deprecated:
216            data["deprecated"] = True
217        if self.range is not None:
218            data["range"] = self.range.name
219        if self.reverse is not None:
220            data["reverse"] = self.reverse.name
221        if self.format is not None:
222            data["format"] = self.format
223        return data
224
225    def __repr__(self) -> str:
226        return "<Property(%r)>" % self.qname
227
228    def __str__(self) -> str:
229        return self.qname