cognite-neat 0.123.26__py3-none-any.whl → 1.0.22__py3-none-any.whl

cognite/neat/_data_model/models/dms/_view_property.py

@@ -0,0 +1,235 @@
+from abc import ABC
+from typing import Annotated, Any, Literal
+
+from pydantic import Field, Json, TypeAdapter, field_serializer
+from pydantic_core.core_schema import FieldSerializationInfo
+
+from cognite.neat._utils.useful_types import BaseModelObject
+
+from ._base import Resource, WriteableResource
+from ._constants import CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN
+from ._data_types import DataType
+from ._references import ContainerDirectReference, ContainerReference, NodeReference, ViewDirectReference, ViewReference
+
+
+class ViewPropertyDefinition(Resource, ABC):
+    connection_type: str
+
+
+class ViewCoreProperty(ViewPropertyDefinition, ABC):
+    # Core properties do not have connection type in the API, but we add it here such that
+    # we can use it as a discriminator in unions. The exclude=True ensures that it is not
+    # sent to the API.
+    connection_type: Literal["primary_property"] = Field(default="primary_property", exclude=True)
+    name: str | None = Field(
+        default=None,
+        description="Readable property name.",
+        max_length=255,
+    )
+    description: str | None = Field(
+        default=None,
+        description="Description of the content and suggested use for this property..",
+        max_length=1024,
+    )
+    container: ContainerReference = Field(
+        description="Reference to the container where this property is defined.",
+    )
+    container_property_identifier: str = Field(
+        description="Identifier of the property in the container.",
+        min_length=1,
+        max_length=255,
+        pattern=CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN,
+    )
+
+    @field_serializer("container", mode="plain")
+    @classmethod
+    def serialize_container(cls, container: ContainerReference, info: FieldSerializationInfo) -> dict[str, Any]:
+        output = container.model_dump(**vars(info))
+        output["type"] = "container"
+        return output
+
+
+class ViewCorePropertyRequest(ViewCoreProperty):
+    source: ViewReference | None = Field(
+        default=None,
+        description="Indicates on what type a referenced direct relation is expected to be. "
+        "Only applicable for direct relation properties.",
+    )
+
+    @field_serializer("source", mode="plain")
+    @classmethod
+    def serialize_source(cls, source: ViewReference | None, info: FieldSerializationInfo) -> dict[str, Any] | None:
+        if source is None:
+            return None
+        output = source.model_dump(**vars(info))
+        output["type"] = "view"
+        return output
+
+
+class ConstraintOrIndexState(BaseModelObject):
+    nullability: Literal["current", "pending", "failed"] | None = Field(
+        None,
+        description="""For properties that have isNullable set to false, this field describes the validity of the
+not-null constraint. It is not specified for nullable properties.
+
+Possible values are:
+
+"failed": The property contains null values, violating the constraint. This can occur if a property with
+          existing nulls was made non-nullable. New null values will still be rejected.
+"current": The constraint is satisfied; all values in the property are not null.
+"pending": The constraint validity has not yet been computed.
+        """,
+    )
+
+
+class ViewCorePropertyResponse(ViewCoreProperty, WriteableResource[ViewCorePropertyRequest]):
+    immutable: bool | None = Field(
+        default=None,
+        description="Should updates to this property be rejected after the initial population?",
+    )
+    nullable: bool | None = Field(
+        default=None,
+        description="Does this property need to be set to a value, or not?",
+    )
+    auto_increment: bool | None = Field(
+        default=None,
+        description="Increment the property based on its highest current value (max value).",
+    )
+    default_value: str | int | bool | dict[str, Json] | None = Field(
+        default=None,
+        description="Default value to use when you do not specify a value for the property.",
+    )
+    constraint_state: ConstraintOrIndexState = Field(
+        description="Describes the validity of constraints defined on this property"
+    )
+    type: DataType = Field(description="The type of data you can store in this property.")
+
+    def as_request(self) -> ViewCorePropertyRequest:
+        return ViewCorePropertyRequest.model_validate(self.model_dump(by_alias=True))
+
+
+class ConnectionPropertyDefinition(ViewPropertyDefinition, ABC):
+    name: str | None = Field(
+        default=None,
+        description="Readable property name.",
+        max_length=255,
+    )
+    description: str | None = Field(
+        default=None,
+        description="Description of the content and suggested use for this property..",
+        max_length=1024,
+    )
+
+
+class EdgeProperty(ConnectionPropertyDefinition, ABC):
+    source: ViewReference = Field(
+        description="The target node(s) of this connection can be read through the view specified in 'source'."
+    )
+    type: NodeReference = Field(
+        description="Reference to the node pointed to by the direct relation. The reference consists of a "
+        "space and an external-id."
+    )
+    edge_source: ViewReference | None = Field(
+        None, description="The edge(s) of this connection can be read through the view specified in 'edgeSource'."
+    )
+    direction: Literal["outwards", "inwards"] = Field(
+        "outwards", description="The direction of the edge(s) of this connection."
+    )
+
+    @field_serializer("source", "edge_source", mode="plain")
+    @classmethod
+    def serialize_source(cls, source: ViewReference | None, info: FieldSerializationInfo) -> dict[str, Any] | None:
+        if source is None:
+            return None
+        output = source.model_dump(**vars(info))
+        output["type"] = "view"
+        return output
+
+
+class SingleEdgeProperty(EdgeProperty):
+    connection_type: Literal["single_edge_connection"] = "single_edge_connection"
+
+
+class MultiEdgeProperty(EdgeProperty):
+    connection_type: Literal["multi_edge_connection"] = "multi_edge_connection"
+
+
+class ReverseDirectRelationProperty(ConnectionPropertyDefinition, ABC):
+    source: ViewReference = Field(
+        description="The node(s) containing the direct relation property can be read "
+        "through the view specified in 'source'."
+    )
+    through: ContainerDirectReference | ViewDirectReference = Field(
+        description="The view of the node containing the direct relation property."
+    )
+
+    @field_serializer("source", mode="plain")
+    @classmethod
+    def serialize_source(cls, source: ViewReference, info: FieldSerializationInfo) -> dict[str, Any] | None:
+        output = source.model_dump(**vars(info))
+        output["type"] = "view"
+        return output
+
+    @field_serializer("through", mode="plain")
+    @classmethod
+    def serialize_through(
+        cls, through: ContainerDirectReference | ViewDirectReference, info: FieldSerializationInfo
+    ) -> dict[str, Any]:
+        output = through.model_dump(**vars(info))
+        if isinstance(through, ContainerDirectReference):
+            output["source"]["type"] = "container"
+        else:
+            output["source"]["type"] = "view"
+        return output
+
+
+class SingleReverseDirectRelationPropertyRequest(ReverseDirectRelationProperty):
+    connection_type: Literal["single_reverse_direct_relation"] = "single_reverse_direct_relation"
+
+
+class MultiReverseDirectRelationPropertyRequest(ReverseDirectRelationProperty):
+    connection_type: Literal["multi_reverse_direct_relation"] = "multi_reverse_direct_relation"
+
+
+class SingleReverseDirectRelationPropertyResponse(
+    ReverseDirectRelationProperty, WriteableResource[SingleReverseDirectRelationPropertyRequest]
+):
+    connection_type: Literal["single_reverse_direct_relation"] = "single_reverse_direct_relation"
+    targets_list: bool = Field(
+        description="Whether or not this reverse direct relation targets a list of direct relations.",
+    )
+
+    def as_request(self) -> SingleReverseDirectRelationPropertyRequest:
+        return SingleReverseDirectRelationPropertyRequest.model_validate(self.model_dump(by_alias=True))
+
+
+class MultiReverseDirectRelationPropertyResponse(
+    ReverseDirectRelationProperty, WriteableResource[MultiReverseDirectRelationPropertyRequest]
+):
+    connection_type: Literal["multi_reverse_direct_relation"] = "multi_reverse_direct_relation"
+    targets_list: bool = Field(
+        description="Whether or not this reverse direct relation targets a list of direct relations.",
+    )
+
+    def as_request(self) -> MultiReverseDirectRelationPropertyRequest:
+        return MultiReverseDirectRelationPropertyRequest.model_validate(self.model_dump(by_alias=True))
+
+
+ViewRequestProperty = Annotated[
+    SingleEdgeProperty
+    | MultiEdgeProperty
+    | SingleReverseDirectRelationPropertyRequest
+    | MultiReverseDirectRelationPropertyRequest
+    | ViewCorePropertyRequest,
+    Field(discriminator="connection_type"),
+]
+ViewResponseProperty = Annotated[
+    SingleEdgeProperty
+    | MultiEdgeProperty
+    | SingleReverseDirectRelationPropertyResponse
+    | MultiReverseDirectRelationPropertyResponse
+    | ViewCorePropertyResponse,
+    Field(discriminator="connection_type"),
+]
+
+ViewRequestPropertyAdapter: TypeAdapter[ViewRequestProperty] = TypeAdapter(ViewRequestProperty)

cognite/neat/_data_model/models/dms/_views.py

@@ -0,0 +1,216 @@
+import re
+from abc import ABC
+from typing import Any, Literal, TypeVar
+
+from pydantic import Field, field_serializer, field_validator, model_validator
+from pydantic_core.core_schema import FieldSerializationInfo
+
+from cognite.neat._utils.text import humanize_collection
+
+from . import DirectNodeRelation
+from ._base import APIResource, Resource, WriteableResource
+from ._constants import (
+    CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN,
+    DM_EXTERNAL_ID_PATTERN,
+    DM_VERSION_PATTERN,
+    FORBIDDEN_CONTAINER_AND_VIEW_EXTERNAL_IDS,
+    FORBIDDEN_CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER,
+    SPACE_FORMAT_PATTERN,
+)
+from ._references import ContainerReference, NodeReference, ViewReference
+from ._view_filter import Filter
+from ._view_property import (
+    EdgeProperty,
+    ViewCorePropertyRequest,
+    ViewCorePropertyResponse,
+    ViewRequestProperty,
+    ViewResponseProperty,
+)
+
+KEY_PATTERN = re.compile(CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN)
+
+
+class View(Resource, APIResource[ViewReference], ABC):
+    space: str = Field(
+        description="Id of the space that the view belongs to.",
+        min_length=1,
+        max_length=43,
+        pattern=SPACE_FORMAT_PATTERN,
+    )
+    external_id: str = Field(
+        description="External-id of the view.",
+        min_length=1,
+        max_length=255,
+        pattern=DM_EXTERNAL_ID_PATTERN,
+    )
+    version: str = Field(
+        description="Version of the view.",
+        max_length=43,
+        pattern=DM_VERSION_PATTERN,
+    )
+    name: str | None = Field(
+        default=None,
+        description="name for the view.",
+        max_length=255,
+    )
+    description: str | None = Field(
+        default=None,
+        description="Description of the view.",
+        max_length=1024,
+    )
+    filter: Filter | None = Field(
+        default=None,
+        description="A filter Domain Specific Language (DSL) used to select which instances the view should include.",
+    )
+    implements: list[ViewReference] | None = Field(
+        default=None,
+        description="References to the views from where this view will inherit properties.",
+    )
+
+    def as_reference(self) -> ViewReference:
+        return ViewReference(space=self.space, external_id=self.external_id, version=self.version)
+
+    @model_validator(mode="before")
+    def set_connection_type_on_primary_properties(cls, data: dict) -> dict:
+        if "properties" not in data:
+            return data
+        properties = data["properties"]
+        if not isinstance(properties, dict):
+            return data
+        # We assume all properties without connectionType are core properties.
+        # The reason we set connectionType it easy for pydantic to discriminate the union.
+        # This also leads to better error messages, as if there is a union and pydantic do not know which
+        # type to pick it will give errors from all type in the union.
+        new_properties: dict[str, Any] = {}
+        for prop_id, prop in properties.items():
+            if isinstance(prop, dict) and "connectionType" not in prop:
+                prop_copy = prop.copy()
+                prop_copy["connectionType"] = "primary_property"
+                new_properties[prop_id] = prop_copy
+            else:
+                new_properties[prop_id] = prop
+        if new_properties:
+            new_data = data.copy()
+            new_data["properties"] = new_properties
+            return new_data
+
+        return data
+
+    @field_validator("external_id", mode="after")
+    def check_forbidden_external_id_value(cls, val: str) -> str:
+        """Check the external_id not present in forbidden set"""
+        if val in FORBIDDEN_CONTAINER_AND_VIEW_EXTERNAL_IDS:
+            raise ValueError(
+                f"'{val}' is a reserved view External ID. Reserved External IDs are: "
+                f"{humanize_collection(FORBIDDEN_CONTAINER_AND_VIEW_EXTERNAL_IDS)}"
+            )
+        return val
+
+    @field_serializer("implements", mode="plain")
+    @classmethod
+    def serialize_implements(
+        cls, implements: list[ViewReference] | None, info: FieldSerializationInfo
+    ) -> list[dict[str, Any]] | None:
+        if implements is None:
+            return None
+        output: list[dict[str, Any]] = []
+        for view in implements:
+            dumped = view.model_dump(**vars(info))
+            dumped["type"] = "view"
+            output.append(dumped)
+        return output
+
+
+class ViewRequest(View):
+    properties: dict[str, ViewRequestProperty] = Field(
+        description="View with included properties and expected edges, indexed by a unique space-local identifier."
+    )
+
+    @field_validator("properties", mode="after")
+    def validate_properties_identifier(cls, val: dict[str, ViewRequestProperty]) -> dict[str, ViewRequestProperty]:
+        """Validate properties Identifier"""
+        return _validate_properties_keys(val)
+
+    @property
+    def used_containers(self) -> set[ContainerReference]:
+        """Get all containers referenced by this view."""
+        return {prop.container for prop in self.properties.values() if isinstance(prop, ViewCorePropertyRequest)}
+
+
+class ViewResponse(View, WriteableResource[ViewRequest]):
+    properties: dict[str, ViewResponseProperty] = Field(
+        description="List of properties and connections included in this view."
+    )
+
+    created_time: int = Field(
+        description="When the view was created. The number of milliseconds since 00:00:00 Thursday, 1 January 1970, "
+        "Coordinated Universal Time (UTC), minus leap seconds."
+    )
+    last_updated_time: int = Field(
+        description="When the view was last updated. The number of milliseconds since 00:00:00 Thursday, "
+        "1 January 1970, Coordinated Universal Time (UTC), minus leap seconds."
+    )
+    writable: bool = Field(
+        description="oes the view support write operations, i.e. is it writable? "
+        "You can write to a view if the view maps all non-nullable properties."
+    )
+    queryable: bool = Field(
+        description="Does the view support queries, i.e. is it queryable? You can query a view if "
+        "it either has a filter or at least one property mapped to a container."
+    )
+    used_for: Literal["node", "edge", "all"] = Field(description="Should this operation apply to nodes, edges or both.")
+    is_global: bool = Field(description="Is this a global view.")
+    mapped_containers: list[ContainerReference] = Field(
+        description="List of containers with properties mapped by this view."
+    )
+
+    @field_validator("properties", mode="after")
+    def validate_properties_identifier(cls, val: dict[str, ViewResponseProperty]) -> dict[str, ViewResponseProperty]:
+        """Validate properties Identifier"""
+        return _validate_properties_keys(val)
+
+    @property
+    def node_types(self) -> list[NodeReference]:
+        """Get all node types referenced by this view."""
+        nodes_refs: set[NodeReference] = set()
+        for prop in self.properties.values():
+            if isinstance(prop, EdgeProperty):
+                nodes_refs.add(prop.type)
+        return list(nodes_refs)
+
+    def as_request(self) -> ViewRequest:
+        dumped = self.model_dump(by_alias=True, exclude={"properties"})
+        properties: dict[str, Any] = {}
+        for key, value in self.properties.items():
+            if isinstance(value, ViewCorePropertyResponse) and isinstance(value.type, DirectNodeRelation):
+                # Special case. In the request the source of DirectNodeRelation is set on the Property object,
+                # while in the response it is set on the DirectNodeRelation object.
+                request_object = value.as_request().model_dump(by_alias=True)
+                request_object["source"] = value.type.source.model_dump(by_alias=True) if value.type.source else None
+                properties[key] = request_object
+            elif isinstance(value, WriteableResource):
+                properties[key] = value.as_request().model_dump(by_alias=True)
+            else:
+                properties[key] = value.model_dump(by_alias=True)
+
+        dumped["properties"] = properties
+        return ViewRequest.model_validate(dumped)
+
+
+T_Property = TypeVar("T_Property")
+
+
+def _validate_properties_keys(properties: dict[str, T_Property]) -> dict[str, T_Property]:
+    """Validate keys of a properties dictionary."""
+    errors: list[str] = []
+    for key in properties:
+        if not KEY_PATTERN.match(key):
+            errors.append(f"Property '{key}' does not match the required pattern: {KEY_PATTERN.pattern}")
+        if key in FORBIDDEN_CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER:
+            errors.append(
+                f"'{key}' is a reserved property identifier. Reserved identifiers are: "
+                f"{humanize_collection(FORBIDDEN_CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER)}"
+            )
+    if errors:
+        raise ValueError("; ".join(errors))
+    return properties

cognite/neat/_data_model/models/entities/__init__.py

@@ -0,0 +1,50 @@
+from ._base import ConceptEntity, UnknownEntity
+from ._constants import Undefined, Unknown
+from ._data_types import (
+    AnyURI,
+    Boolean,
+    DataType,
+    Date,
+    DateTime,
+    DateTimeStamp,
+    Double,
+    Enum,
+    File,
+    Float,
+    Integer,
+    Json,
+    Long,
+    Sequence,
+    String,
+    Timeseries,
+)
+from ._identifiers import URI, NameSpace
+from ._parser import ParsedEntity, parse_entities, parse_entity
+
+__all__ = [
+    "URI",
+    "AnyURI",
+    "Boolean",
+    "ConceptEntity",
+    "DataType",
+    "Date",
+    "DateTime",
+    "DateTimeStamp",
+    "Double",
+    "Enum",
+    "File",
+    "Float",
+    "Integer",
+    "Json",
+    "Long",
+    "NameSpace",
+    "ParsedEntity",
+    "Sequence",
+    "String",
+    "Timeseries",
+    "Undefined",
+    "Unknown",
+    "UnknownEntity",
+    "parse_entities",
+    "parse_entity",
+]

cognite/neat/_data_model/models/entities/_base.py

@@ -0,0 +1,101 @@
+from functools import total_ordering
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator, model_serializer
+
+from ._constants import (
+    PREFIX_PATTERN,
+    SUFFIX_PATTERN,
+    VERSION_PATTERN,
+    Undefined,
+    Unknown,
+    _UndefinedType,
+    _UnknownType,
+)
+
+
+@total_ordering
+class Entity(BaseModel, extra="ignore", populate_by_name=True):
+    """Entity is a concept, class, property, datatype in semantics sense."""
+
+    prefix: str | _UndefinedType = Field(default=Undefined, pattern=PREFIX_PATTERN, min_length=1, max_length=43)
+    suffix: str = Field(min_length=1, max_length=255, pattern=SUFFIX_PATTERN)
+
+    @model_serializer(when_used="unless-none", return_type=str)
+    def as_str(self) -> str:
+        return str(self)
+
+    @field_validator("*", mode="before")
+    def strip_string(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.strip()
+        elif isinstance(value, list):
+            return [entry.strip() if isinstance(entry, str) else entry for entry in value]
+        return value
+
+    def as_tuple(self) -> tuple[str, ...]:
+        # We haver overwritten the serialization to str, so we need to do it manually
+        extra: tuple[str, ...] = tuple(
+            [
+                str(v or "")
+                for field_name in self.model_fields.keys()
+                if (v := getattr(self, field_name)) and field_name not in {"prefix", "suffix"}
+            ]
+        )
+        if isinstance(self.prefix, _UndefinedType):
+            return str(self.suffix), *extra
+        else:
+            return self.prefix, str(self.suffix), *extra
+
+    def __lt__(self, other: object) -> bool:
+        if type(other) is not type(self):
+            return NotImplemented
+        return self.as_tuple() < other.as_tuple()  # type: ignore[attr-defined]
+
+    def __eq__(self, other: object) -> bool:
+        # We need to be explicit that we are not allowing comparison between different types
+        if type(other) is not type(self):
+            # requires explicit raising as NotImplemented would lead to running comparison
+            raise TypeError(f"'==' not supported between instances of {type(self).__name__} and {type(other).__name__}")
+        return self.as_tuple() == other.as_tuple()  # type: ignore[attr-defined]
+
+    def __hash__(self) -> int:
+        return hash(f"{type(self).__name__}({self})")
+
+    def __str__(self) -> str:
+        # there are three cases for string representation:
+        # 1. only suffix is present -> return str(suffix)
+        # 2. prefix and suffix are present -> return "prefix:suffix"
+        # 3. prefix, suffix and other fields are present -> return "prefix:suffix(field1=value1,field2=value2)"
+
+        model_dump = {k: v for k in self.model_fields if (v := getattr(self, k)) is not None}
+
+        base_str = f"{self.prefix}:{self.suffix}" if not isinstance(self.prefix, _UndefinedType) else str(self.suffix)
+
+        extra_fields = {
+            (self.model_fields[k].alias or k): v for k, v in model_dump.items() if k not in {"prefix", "suffix"}
+        }
+        if extra_fields:
+            extra_str = ",".join([f"{k}={v}" for k, v in extra_fields.items()])
+            return f"{base_str}({extra_str})"
+        else:
+            return base_str
+
+    def __repr__(self) -> str:
+        # We have overwritten the serialization to str, so we need to do it manually
+        model_dump = {k: v for k in self.model_fields if (v := getattr(self, k)) is not None}
+        args = ",".join([f"{k}={v!r}" for k, v in model_dump.items()])
+        return f"{type(self).__name__}({args})"
+
+
+class ConceptEntity(Entity):
+    version: str | None = Field(default=None, pattern=VERSION_PATTERN, max_length=43)
+
+
+class UnknownEntity(ConceptEntity):
+    prefix: _UndefinedType = Undefined
+    suffix: _UnknownType = Unknown  # type: ignore[assignment]
+
+    @property
+    def id(self) -> str:
+        return str(Unknown)

cognite/neat/_data_model/models/entities/_constants.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+
+
+class _UndefinedType(BaseModel): ...
+
+
+class _UnknownType(BaseModel):
+    def __str__(self) -> str:
+        return "#N/A"
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+
+# This is a trick to make Undefined and Unknown singletons
+Undefined = _UndefinedType()
+Unknown = _UnknownType()
+
+
+PREFIX_PATTERN = r"^[a-zA-Z][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$"
+SUFFIX_PATTERN = r"^[a-zA-Z0-9._~?@!$&'*+,;=%-]+$"
+VERSION_PATTERN = r"^[a-zA-Z0-9]([.a-zA-Z0-9_-]{0,41}[a-zA-Z0-9])?$"