Semantic entities

The cvcdocdb.drm_entities module contains the domain-specific node types built on top of cvcdocdb.base. These classes add validation, default labels, and automatic materialisation of properties into graph structures.

See also cvcdocdb.base for the underlying primitives and cvcdocdb.exemples for ready-made dataset loaders built with these entities.

Semantic entity definitions for the DRM graph model.

rThis module defines domain-specific node types such as Individu, Lloc and DocumentCultural. These classes build on cvcdocdb.base to provide validation, default labels, and automatic relationship materialisation.

Conceptually, the module is organised around two families of entities:

• root entities, which inherit from Node

• hierarchical child entities, which inherit from WeakNode

The concrete classes model people, places, cultural documents, layouts and other semantic concepts used throughout the tutorials and examples.

cvcdocdb.drm_entities.assert_on_properties(args, properties, entity, accepted_types=(<class 'str'>, <class 'int'>, <class 'dict'>, <class 'bool'>))

Precondition on node insertion: asserts if a specified property isn’t an instance.

Parameters:

• args (Dict) – dict of arguments for a certain entity.

• properties (Iterable) – iterable with properties to be asserted.

• entity (object) – entity we are checking out.

• accepted_types (tuple) – tuple of accepted types as property of object type Node or Relation. Non-hashable types are rejected.

Returns:

bool, message: str). On success, message is “OKAY”. On failure, message describes the missing property.

Return type:

A tuple (success

class cvcdocdb.drm_entities.Individu(ignore_assertion=False, **kwargs)

Bases: Node

A person entity with a primary key.

Base class for all person entities. Automatically appends “Individu” to alternative labels. Subclasses can define be_value_properties to automatically materialise string attributes as Atribut nodes.

Parameters:

• pk – Primary key.

• alternative_labels – Additional labels (appends “Individu”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties: Tuple[str, ...] = ('pk',)

be_value_properties: Tuple[str, ...] = ()

__init__(ignore_assertion=False, **kwargs)

Initialize an Individu node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to Node.__init__ (pk, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.IndividuPadro(ignore_assertion=False, **kwargs)

Bases: Individu

A person entity with a name attribute.

Extends Individu with mandatory nom property. The nom and cognom attributes are automatically materialised as Valor nodes connected by typed edges.

Parameters:

• pk – Primary key.

• nom – Person’s first name (creates a Valor node).

• cognom1 – First surname (creates a Valor node).

• cognom2 – Second surname (creates a Valor node).

• alternative_labels – Additional labels (appends “Individu”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties: Tuple[str, ...] = ('pk', 'nom')

be_value_properties: Tuple[str, ...] = ('nom', 'cognom1', 'cognom2')

class cvcdocdb.drm_entities.IndividuFoto(ignore_assertion=False, **kwargs)

Bases: Individu

A person entity linked to a photograph.

Extends Individu with no additional value properties.

Parameters:

• pk – Primary key.

• alternative_labels – Additional labels (appends “Individu”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties: Tuple[str, ...] = ('pk',)

be_value_properties: Tuple[str, ...] = ()

class cvcdocdb.drm_entities.Lloc(main_label='', ignore_assertion=False, **kwargs)

Bases: Node

A place entity with a primary key.

Base class for all place entities. Automatically appends “Lloc” to alternative labels.

Parameters:

• main_label (str) – Primary Cypher label (default depends on subclass).

• pk – Primary key.

• alternative_labels – Additional labels (appends “Lloc”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties: Tuple[str, ...] = ('pk',)

__init__(main_label='', ignore_assertion=False, **kwargs)

Initialize a Lloc node.

Parameters:

• main_label (str) – Primary Cypher label.

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to Node.__init__ (pk, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.LlocPadro(main_label='', ignore_assertion=False, **kwargs)

Bases: Lloc

A location entity with a custom label.

Extends Lloc with default label “LlocPadro”.

Parameters:

• main_label (str) – Primary Cypher label (default “LlocPadro”).

• pk – Primary key.

• alternative_labels – Additional labels (appends “Lloc”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties: Tuple[str, ...] = ('pk',)

class cvcdocdb.drm_entities.LlocFoto(main_label='', ignore_assertion=False, **kwargs)

Bases: Lloc

A location entity linked to a photograph.

Extends Lloc with default label “LlocFoto”.

Parameters:

• main_label (str) – Primary Cypher label (default “LlocFoto”).

• pk – Primary key.

• alternative_labels – Additional labels (appends “Lloc”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties: Tuple[str, ...] = ('pk',)

class cvcdocdb.drm_entities.DocumentCultural(**kwargs)

Bases: Node

An abstract base class for cultural documents.

This class should not be instantiated directly. Subclasses override document_class to set the appropriate label. Automatically appends “DocumentCultural” to alternative labels.

Parameters:

kwargs (Any)

document_class

The Cypher label for this document type. Defaults to “abstract_class”.

__init__(**kwargs)

Initialize a DocumentCultural node.

Parameters:

**kwargs (Any) – Passed to Node.__init__ (alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.Fons(ignore_assertion=False, **kwargs)

Bases: DocumentCultural

A document collection (fonds) entity.

Extends DocumentCultural with label “Fons”. This is the root entity under which all other documents are hierarchically organised.

Parameters:

• pk – Primary key.

• alternative_labels – Additional labels (appends “DocumentCultural”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties = ('pk',)

__init__(ignore_assertion=False, **kwargs)

Initialize a Fons node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to Node.__init__ (pk, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.ActaTemporal(ignore_assertion=False, **kwargs)

Bases: DocumentCultural

A temporary act/document entity.

Extends DocumentCultural with label “ActaTemporal”.

Parameters:

• pk – Primary key.

• alternative_labels – Additional labels (appends “DocumentCultural”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties = ('pk',)

__init__(ignore_assertion=False, **kwargs)

Initialize an ActaTemporal node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to Node.__init__ (pk, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.EntitatAmbNom(ignore_assertion=False, **kwargs)

Bases: Node

A named entity with a nom property.

Extends Node with mandatory pk and nom properties.

Parameters:

• pk – Primary key.

• nom – Entity name.

• alternative_labels – Additional labels.

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties = ('pk', 'nom')

__init__(ignore_assertion=False, **kwargs)

Initialize an EntitatAmbNom node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to Node.__init__ (pk, nom, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.IndividuAgregat(pk='', main_label='PersonaAgregat', ignore_assertion=False, **kwargs)

Bases: Node

An aggregated person entity with configurable mandatory properties.

Extends Node with a configurable set of mandatory properties derived from a tuple or list of property names.

Parameters:

• pk (str) – Primary key (defaults to empty string).

• main_label (str) – Primary Cypher label (defaults to “PersonaAgregat”).

• alternative_labels – Additional labels (appends “Individu”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties: Tuple[str, ...] = ('pk',)

__init__(pk='', main_label='PersonaAgregat', ignore_assertion=False, **kwargs)

Initialize an IndividuAgregat node.

Parameters:

• pk (str) – Primary key.

• main_label (str) – Primary Cypher label.

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to Node.__init__ (alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.Atribut(value, **kwargs)

Bases: Node

A value node wrapping a string attribute.

Extends Node to represent a string value as a graph node with label “Valor” and a name primary key derived from the value.

Parameters:

• value (str) – The string value to wrap.

• **kwargs (Any) – Additional node attributes passed to Node.__init__.

__init__(value, **kwargs)

Initialize an Atribut value node.

Parameters:

• value (str) – The string value. Stored as {"name": value.lower()} pk.

• **kwargs (Any) – Passed to Node.__init__ (alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.Esdeventiment(ignore_assertion=False, **kwargs)

Bases: Node

An event entity.

Extends Node with mandatory pk property and label “Esdeveniment”.

Parameters:

• pk – Primary key.

• alternative_labels – Additional labels (appends “Semantic”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes.

mandatory_properties = ('pk',)

__init__(ignore_assertion=False, **kwargs)

Initialize an Esdeventiment node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to Node.__init__ (pk, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.Layout(**kwargs)

Bases: WeakNode

An abstract base class for layout entities.

This class should not be instantiated directly. Subclasses override main_label to set the appropriate Cypher label. Automatically appends “layout” to alternative labels.

Parameters:

• parent – The parent Node.

• main_label – Primary Cypher label.

• pk – Primary key.

• alternative_labels – Additional labels (appends “layout”).

• **kwargs (Any) – Additional node attributes passed to WeakNode.__init__.

main_label: str = 'Layout'

__init__(**kwargs)

Initialize a Layout weak node.

Parameters:

**kwargs (Any) – Passed to WeakNode.__init__ (main_label, pk, parent, parent_relation, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.RegioFisica(**kwargs)

Bases: Layout

A physical region entity with contours.

Extends Layout with mandatory pk and contours properties.

Parameters:

• parent – The parent Node.

• main_label – Primary Cypher label.

• pk – Primary key.

• contours – Region contour data.

• alternative_labels – Additional labels (appends “layout”).

• **kwargs (Any) – Additional node attributes passed to WeakNode.__init__.

mandatory_properties = ('pk', 'contours')

main_label: str = 'RegioFisica'

__init__(**kwargs)

Initialize a RegioFisica weak node.

Parameters:

**kwargs (Any) – Passed to WeakNode.__init__ (main_label, pk, contours, parent, parent_relation, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.OCRTranscript(**kwargs)

Bases: Layout

An OCR transcript entity.

Extends Layout with a main_label and optional pk. Automatically appends “semantic” to alternative labels.

Parameters:

• parent – The parent Node.

• main_label – Primary Cypher label.

• pk – Primary key.

• alternative_labels – Additional labels (appends “semantic”).

• **kwargs (Any) – Additional node attributes passed to WeakNode.__init__.

main_label: str = 'OCRTranscript'

__init__(**kwargs)

Initialize an OCRTranscript weak node.

Parameters:

**kwargs (Any) – Passed to WeakNode.__init__ (main_label, pk, parent, parent_relation, alternative_labels, etc.).

Return type:

None

class cvcdocdb.drm_entities.Padro(ignore_assertion=False, **kwargs)

Bases: _DocumentCulturalBase

A padro document entity with a path property.

Extends _DocumentCulturalBase with mandatory pk and ruta properties.

Parameters:

• parent – The parent Node.

• pk – Primary key.

• ruta – Path property.

• alternative_labels – Additional labels (appends “document”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes passed to WeakNode.__init__.

mandatory_properties = ('pk', 'ruta')

__init__(ignore_assertion=False, **kwargs)

Initialize a Padro weak node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to WeakNode.__init__ (pk, ruta, alternative_labels, parent, parent_relation, etc.).

Return type:

None

class cvcdocdb.drm_entities.Fotografia(ignore_assertion=False, **kwargs)

Bases: _DocumentCulturalBase

A photograph entity.

Extends _DocumentCulturalBase with mandatory pk property.

Parameters:

• parent – The parent Node.

• pk – Primary key.

• alternative_labels – Additional labels (appends “document”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes passed to WeakNode.__init__.

mandatory_properties = ('pk',)

__init__(ignore_assertion=False, **kwargs)

Initialize a Fotografia weak node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to WeakNode.__init__ (pk, alternative_labels, parent, parent_relation, etc.).

Return type:

None

class cvcdocdb.drm_entities.BOE(ignore_assertion=False, **kwargs)

Bases: _DocumentCulturalBase

A Boletín Oficial del Estado (Spanish government gazette) entity.

Extends _DocumentCulturalBase with mandatory pk and ruta properties.

Parameters:

• parent – The parent Node.

• pk – Primary key.

• ruta – Path to the document.

• alternative_labels – Additional labels (appends “document”).

• ignore_assertion (bool) – If True, skip mandatory property checks.

• **kwargs (Any) – Additional node attributes passed to WeakNode.__init__.

mandatory_properties = ('pk', 'ruta')

__init__(ignore_assertion=False, **kwargs)

Initialize a BOE weak node.

Parameters:

• ignore_assertion (bool) – Skip mandatory property checks.

• **kwargs (Any) – Passed to WeakNode.__init__ (pk, ruta, alternative_labels, parent, parent_relation, etc.).

Return type:

None