Structural model¶

besser.BUML.metamodel.structural.structural._next_timestamp() → datetime[source]¶

Current time, bumped so each call is strictly later than the previous one.

The clock often returns the same value for objects created back to back, and generators order members by timestamp, so ties made declaration order unstable.

class besser.BUML.metamodel.structural.structural.Element(timestamp: datetime = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: ABC

Element is the Superclass of all structural model elements.

Parameters:¶

timestamp (datetime) – Object creation datetime (default is current time).
is_derived (bool) – Indicates whether the element is derived (False as default).
uncertainty (float) – Indicates the uncertainty level of the element as a probability between 0 and 1 (0.0 as default).

Attributes:¶

timestamp (datetime) – Object creation datetime (default is current time).
is_derived (bool) – Indicates whether the element is derived (False as default).
uncertainty (float) – Indicates the uncertainty level of the element as a probability between 0 and 1 (0.0 as default).

property timestamp : datetime¶

Get the timestamp of the element.

Type:¶: datetime

property is_derived : bool¶

Get whether the element is derived.

Type:¶: bool

property uncertainty : float¶

Get the uncertainty level of the element as a probability between 0 and 1.

Type:¶: float

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.Metadata(description: str = None, uri: str = None, synonyms: list[str] = None, icon: str = None, timestamp: datetime = None)[source]¶

Bases: Element

The Metadata class stores additional information about named elements.

Parameters:¶

description (str) – Description of the element (None as default).
uri (str) – Uniform resource identifier for the element (None as default).
synonyms (List[str]) – List of synonyms of the element (None as default).
icon (str) – Icon representing the element (None as default).
timestamp (datetime) – Object creation datetime (default is current time).

Attributes:¶

description (str) – Description of the element (None as default).
uri (str) – Uniform resource identifier for the element (None as default).
synonyms (List[str]) – List of synonyms of the element (None as default).
icon (str) – Icon representing the element (None as default).
timestamp (datetime) – Object creation datetime (default is current time).

property description : str¶

Get the description of the metadata.

Type:¶: str

property uri : str¶

Get the URI of the metadata.

Type:¶: str

property synonyms : list[str]¶

Get the list of synonyms of the metadata.

Type:¶: List[str]

property icon : str¶

Get the icon representing the metadata.

Type:¶: str

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.NamedElement(name: str, timestamp: datetime = None, metadata: Metadata = None, visibility: str = 'public', is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: Element

NamedElement represent a structural element with a name.

Parameters:¶

name (str) – The name of the named element
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the named element (None as default).
visibility (str) – Determines the kind of visibility of the named element (public as default).
is_derived (bool) – Indicates whether the element is derived (False as default).

Attributes:¶

name (str) – The name of the named element
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the named element (None as default).
visibility – Determines the kind of visibility of the named element (public as default).
is_derived (bool) – Indicates whether the element is derived (False as default).

property name : str¶

Get the name of the named element.

Type:¶: str

property visibility : str¶

Get the visibility of the named element.

Type:¶: str

property metadata : Metadata¶

Get the metadata of the named element.

Type:¶: Metadata

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.Type(name: str, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

Type is the Superclass of classes and data types in the model.

Parameters:¶

name (str) – The name of the Type.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the type (None as default).
is_derived (bool) – Indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the Type.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the type (None as default).
is_derived (bool) – Indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.DataType(name: str, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: Type

Represents a data type.

This class inherits from NamedElement and is used to model data types.

Parameters:¶

name (str) – The name of the data type.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the data type (None as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the data type.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the data type (None as default).

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.PrimitiveDataType(name: str, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: DataType

Class representing a primitive data type.

This class is a subclass of DataType and is used to represent primitive data types with a specified name.

Parameters:¶

name (str) – The name of the primitive data type.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the primitive data type (None as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the primitive data type.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the primitive data type (None as default).

property name : str¶

Get the name of the named element.

Type:¶: str

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.MethodImplementationType(*values)[source]¶

Bases: Enum

Enumeration representing the type of implementation for a method.

Attributes:¶

NONE – No implementation (abstract method or signature only).
CODE – Implementation provided as Python code string.
BAL – Implementation provided as BESSER Action Language code string.
STATE_MACHINE – Implementation defined by a state machine.
QUANTUM_CIRCUIT – Implementation defined by a quantum circuit.
NEURAL_NETWORK – Implementation defined by a neural network.

NONE = 'none'¶

CODE = 'code'¶

BAL = 'besser_action_language'¶

STATE_MACHINE = 'state_machine'¶

QUANTUM_CIRCUIT = 'quantum_circuit'¶

NEURAL_NETWORK = 'neural_network'¶

class besser.BUML.metamodel.structural.structural.EnumerationLiteral(name: str, owner: DataType = None, timestamp: datetime = None, metadata: Metadata = None, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

Class representing an enumeration literal.

This class is a subclass of NamedElement and is used to represent individual literals within an enumeration.

Parameters:¶

name (str) – The name of the enumeration literal.
owner (DataType) – The owner data type of the enumeration literal (None as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the literal (None as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the enumeration literal.
owner (DataType) – Represents the owner data type of the enumeration literal (None as default).
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the literal (None as default).

property owner : DataType¶

Get the owner.

Type:¶: Datatype

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.Enumeration(name: str, literals: set[EnumerationLiteral] = None, timestamp: datetime = None, metadata: Metadata = None, uncertainty: float = 0.0)[source]¶

Bases: DataType

Class representing an enumeration.

This class is a subclass of DataType and is used to represent enumerations with a specified name and a set of enumeration literals.

Parameters:¶

name (str) – The name of the enumeration data type.
literals (set[EnumerationLiteral]) – Set of enumeration literals associated with the enumeration (None as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the enumeration (None as default).

Attributes:¶

name (str) – Inherited from DataType, represents the name of the enumeration.
literals (set[EnumerationLiteral]) – Represents a set of enumeration literals associated with the enumeration (None as default).
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the enumeration (None as default).

property literals : set[EnumerationLiteral]¶

Get the set of literals.

Type:¶: set[EnumerationLiteral]

add_literal(literal: EnumerationLiteral)[source]¶

Add an enumeration literal to the set.

Raises:¶: ValueError – if the enumeration literal name already exist.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.TypedElement(name: str, type: Type | str, timestamp: datetime = None, metadata: Metadata = None, visibility: str = 'public', is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

TypedElement is a subclass of NamedElement and is used to represent elements that have a specific type.

Parameters:¶

name (str) – The name of the typed element.
type (Type, str) – The data type of the typed element.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the typed element (None as default).
visibility (str) – Determines the kind of visibility of the typed element (public as default).
is_derived (bool) – Indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the typed element.
type (Type) – The data type of the typed element.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the typed element (None as default).
visibility (str) – Inherited from NamedElement, represents the visibility of the typed element (public as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

type_mapping = {'bool': PrimitiveDataType(bool, 2026-10-08 12:10:55.863910, None), 'date': PrimitiveDataType(date, 2026-10-08 12:10:55.863917, None), 'datetime': PrimitiveDataType(datetime, 2026-10-08 12:10:55.863920, None), 'float': PrimitiveDataType(float, 2026-10-08 12:10:55.863906, None), 'int': PrimitiveDataType(int, 2026-10-08 12:10:55.863900, None), 'str': PrimitiveDataType(str, 2026-10-08 12:10:55.863876, None), 'string': PrimitiveDataType(str, 2026-10-08 12:10:55.863876, None), 'time': PrimitiveDataType(time, 2026-10-08 12:10:55.863914, None), 'timedelta': PrimitiveDataType(timedelta, 2026-10-08 12:10:55.863922, None)}¶

property type : Type¶

Get the type of the typed element.

Type:¶: Type

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.Multiplicity(min_multiplicity: int, max_multiplicity: int | '*', is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: Element

Represents the multiplicity of a Property.

It consists of a minimum and maximum value, indicating the allowed range.

Parameters:¶

min_multiplicity (int) – The minimum multiplicity.
max_multiplicity (int | Literal[””]*) – The maximum multiplicity. Use “*” for unlimited.
is_derived (bool) – Indicates whether the element is derived (False as default).

Attributes:¶

min (int) – The minimum multiplicity.
max (int) – The maximum multiplicity.
is_derived (bool) – Indicates whether the element is derived (False as default).

property min : int¶

Get the minimum multiplicity.

Type:¶: int

property max : int¶

Get the maximum multiplicity.

Type:¶: int

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.Property(name: str, type: Type, owner: Type = None, multiplicity: Multiplicity = Multiplicity(1, 1, is_derived=False), visibility: str = 'public', is_composite: bool = False, is_navigable: bool = True, is_id: bool = False, is_read_only: bool = False, is_optional: bool = False, is_external_id: bool = False, default_value: Any = None, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: TypedElement

A property can represents an attribute of a class or an end of an association.

Properties are owned by a class or an association.

Parameters:¶

name (str) – The name of the property.
type (Type) – The type of the property.
owner (Type) – The type that owns the property (None as default).
multiplicity (Multiplicity) – The multiplicity of the property (1..1 as default).
visibility (str) – The visibility of the property (public as default).
is_composite (bool) – Indicates whether the property is a composite (False as default).
is_navigable (bool) – Indicates whether the property is navigable in a relationship (True as default).
is_id (bool) – Indicates whether the property is an id (False as default).
is_read_only (bool) – Indicates whether the property is read only (False as default).
is_optional (bool) – Indicates whether the property is optional/nullable (False as default).
default_value (Any) – The default value of the property (None as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the property (None as default). is_derived (bool): Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from TypedElement, represents the name of the property.
type (Type) – Inherited from TypedElement, represents the type of the property.
owner (Type) – The type that owns the property (public as default).
multiplicity (Multiplicity) – The multiplicity of the property (1..1 as default).
visibility (str) – Inherited from TypedElement, represents the visibility of the property (public as default).
is_composite (bool) – Indicates whether the property is a composite (False as default).
is_navigable (bool) – Indicates whether the property is navigable in a relationship (True as default).
is_id (bool) – Indicates whether the property is an id (False as default).
is_read_only (bool) – Indicates whether the property is read only (False as default).
is_optional (bool) – Indicates whether the property is optional/nullable (False as default).
default_value (Any) – The default value of the property (None as default).
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the property (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

property owner : Type¶

Get the owner type of the property.

Type:¶: Type

property multiplicity : Multiplicity¶

Get the multiplicity of the property.

Type:¶: Multiplicity

property is_composite : bool¶

Get whether the property is composite.

Type:¶: bool

property is_navigable : bool¶

Get whether the property is navigable.

Type:¶: bool

property is_id : bool¶

Get whether the property is an id.

Type:¶: bool

property is_read_only : bool¶

Get whether the property is read only.

Type:¶: bool

property is_optional : bool¶

Get whether the property is optional.

Type:¶: bool

property is_external_id : bool¶

Get whether the property is an external identifier.

External identifiers are user-facing keys (e.g. name, email, sku) that people outside the system use to locate an object, distinct from the internal/surrogate primary key (is_id). A class may have multiple external-id properties forming a composite key, and a property can be both is_id and is_external_id when a natural key also serves as the PK.

Type:¶: bool

property default_value : Any¶

Get the default value of the property.

Type:¶: Any

opposite_end() → Property[source]¶: Property: Get the opposite end of the property if it is an association end.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.Parameter(name: str, type: Type, default_value: Any = None, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: TypedElement

Parameter is used to represent a parameter of a method with a specific type.

Parameters:¶

name (str) – The name of the parameter.
type (Type) – The data type of the parameter.
default_value (Any) – The default value of the parameter (None as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the parameter (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the parameter.
type (Type) – Inherited from TypedElement, represents the type of the parameter.
default_value (Any) – The default value of the parameter (None as default).
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the parameter (None as default).

property default_value : Any¶

Get the default value of the parameter.

Type:¶: Type

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.Method(name: str, visibility: str = 'public', is_abstract: bool = False, parameters: list[Parameter] = None, type: Type = None, owner: Type = None, code: str = '', implementation_type: MethodImplementationType = None, state_machine: StateMachine = None, quantum_circuit: QuantumCircuit = None, neural_network: NN = None, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0, pre: list[Constraint] = None, post: list[Constraint] = None)[source]¶

Bases: TypedElement

Method is used to represent a method of a class.

A method can have different types of implementations: - NONE: Abstract method or signature only (UML description) - CODE: Python code implementation - BAL: BESSER Action Language implementation - STATE_MACHINE: Behavior defined by a state machine - QUANTUM_CIRCUIT: Behavior defined by a quantum circuit - NEURAL_NETWORK: Behavior defined by a neural network (calling the method runs the NN)

Parameters:¶

name (str) – The name of the method.
visibility (str) – Determines the kind of visibility of the method (public as default).
is_abstract (bool) – Indicates if the method is abstract (False as default).
parameters (list[Parameter]) – The list of parameters for the method (list() as default).
type (Type) – The type of the method (None as default).
owner (Type) – The type that owns the method (None as default).
code (str) – code of the method (”” as default).
implementation_type (MethodImplementationType) – The type of implementation (auto-detected as default).
state_machine (StateMachine) – Reference to a state machine that defines the method behavior (None as default).
quantum_circuit (QuantumCircuit) – Reference to a quantum circuit that defines the method behavior (None as default).
neural_network (NN) – Reference to a neural network that defines the method behavior (None as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the method (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).
pre (list[Constraint]) – Preconditions of the method (list() as default).
post (list[Constraint]) – Postconditions of the method (list() as default).

Attributes:¶

name (str) – Inherited from TypedElement, represents the name of the method.
visibility (str) – Inherited from TypedElement, represents the visibility of the method (public as default).
is_abstract (bool) – Indicates if the method is abstract. (False as default)
parameters (list[Parameter]) – The list of parameters for the method (list() as default).
type (Type) – Inherited from TypedElement, represents the type of the method (None as default).
owner (Type) – The type that owns the property (None as default).
code (str) – code of the method (”” as default).
implementation_type (MethodImplementationType) – The type of implementation.
state_machine (StateMachine) – Reference to a state machine that defines the method behavior (None as default).
quantum_circuit (QuantumCircuit) – Reference to a quantum circuit that defines the method behavior (None as default).
neural_network (NN) – Reference to a neural network that defines the method behavior (None as default).
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the method (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).
pre (list[Constraint]) – Preconditions of the method (list() as default).
post (list[Constraint]) – Postconditions of the method (list() as default).

property is_abstract : bool¶

Get whether the method is abstract.

Type:¶: bool

property parameters : list[Parameter]¶

Get the set of parameters of the method.

Type:¶: list[Parameter]

add_parameter(parameter: Parameter)[source]¶

Parameter: Add a parameter to the set of class parameters.

Raises:¶: ValueError – if the parameter name already exist.

property pre : list[Constraint]¶

Get the preconditions of the method.

Type:¶: list[Constraint]

property post : list[Constraint]¶

Get the postconditions of the method.

Type:¶: list[Constraint]

add_pre(constraint: Constraint)[source]¶

Constraint: Add a precondition to the method.

Raises:¶: ValueError – if the precondition name already exists on this method.

add_post(constraint: Constraint)[source]¶

Constraint: Add a postcondition to the method.

Raises:¶: ValueError – if the postcondition name already exists on this method.

property owner : Type¶

Get the owner type of the method.

Type:¶: Type

property code : str¶

Get the code of the method.

Type:¶: str

property implementation_type : MethodImplementationType¶

Get the implementation type of the method.

Type:¶: MethodImplementationType

property state_machine : StateMachine¶

Get the state machine that defines the method behavior.

Type:¶: StateMachine

property quantum_circuit : QuantumCircuit¶

Get the quantum circuit that defines the method behavior.

Type:¶: QuantumCircuit

property neural_network : NN¶

Get the neural network that defines the method behavior.

Type:¶: NN

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.BehaviorImplementation(name: str, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

A behaviorImplementation represents the body of a behavior associated with a class.

Parameters:¶: name (str) – The name of the behavior implementation.
Attributes:¶: name (str) – The name of the behavior implementation.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.structural.structural.BehaviorDeclaration(name: str, implementations: set[BehaviorImplementation], uncertainty: float = 0.0)[source]¶

Bases: NamedElement

A BehaviorDeclaration represents the signature of a behavior associated with a class.

Parameters:¶

name (str) – The name of the behavior.
implementations (set[BehaviorImplementation]) – The implementations associated with the behavior.

Attributes:¶

name (str) – The name of the behavior.
implementations (set[BehaviorImplementation]) – The implementations associated with the behavior.

property implementations : set[BehaviorImplementation]¶

Get the implementations of the behavior.

Type:¶: set[BehaviorImplementation]

_abc_impl = <_abc._abc_data object>¶

besser.BUML.metamodel.structural.structural._stem_candidates(role_name: str) → list[tuple[str, str]][source]¶

All plausible (stem, suffix_tag) readings of role_name, best guess first.

suffix_tag is "ies", "es" or "s" for a plural reading and "" for the name taken as-is (always the last candidate), so that houses can still match House and status can match Status.

besser.BUML.metamodel.structural.structural._stem_role_name(role_name: str) → tuple[str, str][source]¶

Strip a common English plural suffix from role_name.

Returns the best-guess (stem, suffix_tag) from _stem_candidates(). Only conservative English pluralisation rules are applied so that intentional role names like "borrower" are not mistaken for plurals.

besser.BUML.metamodel.structural.structural._pluralize(word: str) → str[source]¶: Regular English plural of word (box -> boxes, city -> cities).

besser.BUML.metamodel.structural.structural._pluralize_for_role(base: str, suffix_tag: str) → str[source]¶: Plural of base when suffix_tag marks a plural role, else base unchanged.

besser.BUML.metamodel.structural.structural._match_role_case(template: str, candidate: str) → str[source]¶

Adapt candidate to mirror the casing convention of template.

Heuristic:

If template is all lowercase -> return candidate.lower().
If template is all uppercase -> return candidate.upper().
If template starts with a lowercase letter (camelCase-ish role like borrowedBooks) -> first char lowercase, rest as-is from candidate.
Otherwise return candidate unchanged (preserves PascalCase).

besser.BUML.metamodel.structural.structural._role_name_matches_class(role_name: str, class_name: str) → tuple[bool, str][source]¶

Return (matches, suffix_tag) if role_name is the (possibly pluralised) lowercase form of class_name.

The match is exact after stripping a recognised plural suffix and case-folding – intentionally non-fuzzy so that role names like "borrower" (pointing to a Member class) are left alone.

class besser.BUML.metamodel.structural.structural.Class(name: str, attributes: set[Property] = None, methods: set[Method] = None, is_abstract: bool = False, is_read_only: bool = False, behaviors: set[BehaviorDeclaration] = None, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: Type

Represents a class in a modeling context.

A Class is a type that defines a blueprint for objects. It can have attributes, associations, and generalizations with other classes.

Parameters:¶

name (str) – The name of the class.
attributes (set[Property]) – The set of attributes associated with the class (None as default).
methods (set[Method]) – The set of methods of the class (None as default).
is_abstract (bool) – Indicates whether the class is abstract (False as default).
is_read_only (bool) – Indicates whether the class is read only (False as default).
behaviors (set[BehaviorDeclaration]) – The set of behaviors associated with the class (None as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the class (None as default).
is_derived (bool) – Indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from Type, represents the name of the class.
attributes (set[Property]) – The set of attributes associated with the class (set() as default).
methods (set[Method]) – The set of methods of the class (set() as default).
is_abstract (bool) – Indicates whether the class is abstract (False as default).
is_read_only (bool) – Indicates whether the class is read only (False as default).
behaviors (set[BehaviorDeclaration]) – The set of behaviors associated with the class (None as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the class (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

property name : str¶

Get the name of the named element.

Type:¶: str

property attributes : set[Property]¶

Get the attributes of the class.

Type:¶: set[Property]

property methods : set[Method]¶

Get the methods of the class.

Type:¶: set[Method]

add_method(method: Method)[source]¶

Method: Add a method to the set of class methods.

Raises:¶: ValueError – if the method name already exist.

all_attributes() → set[Property][source]¶: set[Property]: Get all attributes, including inherited ones.

add_attribute(attribute: Property)[source]¶

Property: Add an attribute to the set of class attributes.

Raises:¶: ValueError – if the attribute name already exist.

property behaviors : set[BehaviorDeclaration]¶

Get the behaviors associated with the class.

Type:¶: set[BehaviorDeclaration]

property is_abstract : bool¶

Get whether the class is abstract.

Type:¶: bool

property is_read_only : bool¶

Get whether the class is read only.

Type:¶: bool

property associations : set¶

Get the set of associations involving the class.

Type:¶: set[Association]

_add_association(association)[source]¶: Association: Add an association to the set of class associations.

_validate_unique_end_names(ends)[source]¶: Ensure that no association end has a duplicate name in this class or its specializations.

_delete_association(association)[source]¶: Association: Remove an association to the set of class associations.

property generalizations : set¶

Get the set of generalizations involving the class.

Type:¶: set[Generalization]

_add_generalization(generalization)[source]¶: Generalization: Add a generalization to the set of class generalizations.

_delete_generalization(generalization)[source]¶: Generalization: Remove a generalization to the set of class generalizations.

_abc_impl = <_abc._abc_data object>¶

inherited_attributes() → set[Property][source]¶: set[Property]: Get the set of inherited attributes.

association_ends() → set[source]¶: set[Property]: Get the set of association ends of the class.

all_association_ends() → set[Property][source]¶: set[Property]: Get the set of direct and indirect association ends of the class.

parents() → set[source]¶: set[Class]: Get the set of direct parents of the class.

all_parents() → set[source]¶: set[Class]: Get the set of direct and indirect parents of the class.

specializations() → set[source]¶: set[Class]: Get the set of direct specializations (children) of the class.

all_specializations() → set[source]¶: set[Class]: Get the set of direct and indirect specializations (children) of the class.

id_attribute() → Property[source]¶: Property: Get the id attribute of the class.

class besser.BUML.metamodel.structural.structural.Association(name: str, ends: set[Property], timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

Represents an association between classes.

An Association defines a relationship between classes and is composed of two or more ends, each associated with a class. An association must have more than one end.

Parameters:¶

name (str) – The name of the association.
ends (set[Property]) – The set of ends related to the association.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the association (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the association.
ends (set[Property]) – The set of ends related to the association.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the association (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

property ends : set[Property]¶

Get the ends of the association.

Type:¶: set[Property]

class besser.BUML.metamodel.structural.structural.BinaryAssociation(name: str, ends: set[Property], timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: Association

Represents a binary association between two classes.

A BinaryAssociation is a specialized form of Association that specifically involves two ends, each associated with a class. It enforces constraints on the association, such as having exactly two ends. Exactly two ends are required

Parameters:¶

name (str) – The name of the binary association.
ends (set[Property]) – The set of ends related to the binary association.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the binary association (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from Association, represents the name of the binary association.
ends (set[Property]) – Inherited from NamedElement, represents the set of ends related to the binary association.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the binary association (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

property ends : set[Property]¶

Get the ends of the association.

Type:¶: set[Property]

_navigability_errors(ends: set[Property] = None) → list[str][source]¶

Return the navigability rule violations of a binary association.

A binary association needs at least one navigable end, and the non-composite (part) end of a composition must be navigable. Used by the ends setter (construction time) and by DomainModel.validate() (to report ends made non-navigable after construction).

Parameters:¶: ends (set[Property]) – The ends to check (defaults to the current ends).
Returns:¶: One message per violated rule; empty when the ends are valid. The ends setter raises the first one.
Return type:¶: list[str]

class besser.BUML.metamodel.structural.structural.AssociationClass(name: str, attributes: set[Property], association: Association, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: Class

An AssociationClass is a class that that has an association nature. It inherits from Class and is associated with an underlying Association.

Parameters:¶

name (str) – The name of the association class.
attributes (set[Property]) – The set of attributes associated with the association class.
association (Association) – The underlying association linked to the association class.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the association class (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from Class, represents the name of the association class.
attributes (set[Property]) – Inherited from Class, represents the set of attributes associated with the association class.
association (Association) – The underlying association linked to the association class.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the association class (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

property association : Association¶

Get the underlying association of the association class.

Type:¶: Association

class besser.BUML.metamodel.structural.structural.Generalization(general: Class, specific: Class, timestamp: datetime = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: Element

Represents a generalization relationship between two classes.

A Generalization is a relationship between two classes, where one class (specific) inherits attributes and behaviors from another class (general).

Parameters:¶

general (Class) – The general (parent) class in the generalization relationship.
specific (Class) – The specific (child) class in the generalization relationship.
timestamp (datetime) – Object creation datetime (default is current time).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

general (Class) – The general (parent) class in the generalization relationship.
specific (Class) – The specific (child) class in the generalization relationship.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

property general : Class¶

Get the general (parent) class.

Type:¶: Class

property specific : Class¶

Get the specific (child) class.

Type:¶: Class

class besser.BUML.metamodel.structural.structural.GeneralizationSet(name: str, generalizations: set[Generalization], is_disjoint: bool, is_complete: bool, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

Represents a set of generalization relationships.

Parameters:¶

name (str) – The name of the generalization set.
generalizations (set[Generalization]) – The set of generalization relationships in the set.
is_disjoint (bool) – Indicates whether the set is disjoint (instances cannot belong to more than one class in the set).
is_complete (bool) – Indicates whether the set is complete (every instance of the superclass must belong to a subclass).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the generalization set (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the generalization set.
generalizations (set[Generalization]) – The set of generalization relationships in the set.
is_disjoint (bool) – Indicates whether the set is disjoint (instances cannot belong to more than one class in the set).
is_complete (bool) – Indicates whether the set is complete (every instance of the superclass must belong to a subclass).
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the generalization set (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

property generalizations : set[Generalization]¶

Get the generalization relationships.

Type:¶: set[Generalization]

property is_disjoint : bool¶

Get whether the set is disjoint.

Type:¶: bool

property is_complete : bool¶

Get whether the set is complete.

Type:¶: bool

class besser.BUML.metamodel.structural.structural.Package(name: str, elements: set[NamedElement], timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

A Package is a grouping mechanism that allows organizing and managing a set of NamedElements.

Parameters:¶

name (str) – The name of the package.
elements (set[NamedElement]) – The set of elements contained in the package.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the package (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the package.
elements (set[NamedElement]) – The set of elements contained in the package.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the package (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

property elements : set[NamedElement]¶

Get the named elements contained in the package.

Type:¶: set[NamedElement]

get_classes() → set[Class][source]¶: set[Class]: Get all classes within the package.

get_associations() → set[Association][source]¶: set[Association]: Get all associations within the package.

get_generalizations() → set[Generalization][source]¶: set[Generalization]: Get all generalizations within the package.

get_enumerations() → set[Enumeration][source]¶: set[Enumeration]: Get all enumerations within the package.

class besser.BUML.metamodel.structural.structural.Constraint(name: str, context: Class, expression: str, language: str, description: str = None, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

A Constraint is a statement that restricts or defines conditions on the behavior, structure, or other aspects of the modeled system.

Parameters:¶

name (str) – The name of the constraint.
context (Class) – The class to which the constraint is associated.
expression (str) – The expression or condition defined by the constraint.
language (str) – The language in which the constraint expression is written.
description (str) – Optional natural-language explanation shown to end-users when the constraint is violated. Intended for non-technical audiences (e.g. graphical editor users) who may not understand the raw constraint expression.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the constraint (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the constraint.
context (Class) – The class to which the constraint is associated.
expression (str) – The expression or condition defined by the constraint.
language (str) – The language in which the constraint expression is written.
description (str) – Optional natural-language explanation surfaced on validation failure.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the constraint (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).

_abc_impl = <_abc._abc_data object>¶

property context : Class¶

Get the class to which the constraint is associated.

Type:¶: Class

property expression : str¶

Get the source text of the constraint expression.

Type:¶: str

property language : str¶

Get the language in which the constraint expression is written.

Type:¶: str

property description : str¶

Get the natural-language explanation shown when the constraint is violated.

Type:¶: str

class besser.BUML.metamodel.structural.structural.Model(name: str, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, elements: set[Element] = None, uncertainty: float = 0.0)[source]¶

Bases: NamedElement

A model is the root element. There are different types of models that inherit from this class. For example, DomainModel, ObjectModel, or GUIModel.

Parameters:¶

name (str) – The name of the model.
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the model (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).
elements (set[Element]) – Set of model Elements in the Model.

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the model.
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the model (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).
elements (set[Element]) – Set of model Elements in the Model.

_abc_impl = <_abc._abc_data object>¶

property elements : set[Element]¶

Get the set of model elements in the model.

Type:¶: set[Element]

class besser.BUML.metamodel.structural.structural.DomainModel(name: str, types: set[Type] = None, associations: set[Association] = None, generalizations: set[Generalization] = None, packages: set[Package] = None, constraints: set[Constraint] = None, timestamp: datetime = None, metadata: Metadata = None, is_derived: bool = False, elements: set[Element] = None, uncertainty: float = 0.0)[source]¶

Bases: Model

A domain model comprises a number of types, associations, generalizations, packages, constraints, and others.

Parameters:¶

name (str) – The name of the domain model.
types (set[Type]) – The set of types (classes and datatypes) in the domain model (set() as default).
associations (set[Association]) – The set of associations in the domain model (set() as default).
generalizations (set[Generalization]) – The set of generalizations in the domain model (set() as default).
packages (set[Package]) – The set of packages in the domain model (set() as default).
constraints (set[Constraint]) – The set of constraints in the domain model (set() as default).
timestamp (datetime) – Object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the domain model (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).
elements (set[Element]) – Set of model Elements in the Model. This property is derived (auto-calculated).

Attributes:¶

name (str) – Inherited from NamedElement, represents the name of the domain model.
types (set[Type]) – The set of types (classes and datatypes) in the domain model (set() as default).
associations (set[Association]) – The set of associations in the domain model (set() as default).
generalizations (set[Generalization]) – The set of generalizations in the domain model (set() as default).
packages (set[Package]) – The set of packages in the domain model (set() as default).
constraints (set[Constraint]) – The set of constraints in the domain model (set() as default).
timestamp (datetime) – Inherited from NamedElement; object creation datetime (default is current time).
metadata (Metadata) – Metadata information for the domain model (None as default).
is_derived (bool) – Inherited from NamedElement, indicates whether the element is derived (False as default).
elements (set[Element]) – Set of model Elements in the Model. This property is derived (auto-calculated).

_abc_impl = <_abc._abc_data object>¶

_update_elements()[source]¶: Recalculates the elements property by combining all relevant sets.

property types : set[Type]¶

Get the set of types in the domain model.

Type:¶: set[Type]

get_type_by_name(type_name: str) → Type[source]¶: Type: Gets an Type by name.

add_type(type_: Type)[source]¶: Type: Add a type (Class or DataType) to the set of types of the model.

remove_type(type_: Type)[source]¶

Remove a type from the model.

Parameters:¶: type_ (Type) – The type to remove.
Raises:¶: ValueError – if the type is not in the model.

property associations : set[Association]¶

Get the set of associations in the domain model.

Type:¶: set[Association]

add_association(association: Association)[source]¶: Association: Add an association to the set of associations of the model.

remove_association(association: Association)[source]¶

Remove an association from the model and clean up references in involved classes.

Parameters:¶: association (Association) – The association to remove.
Raises:¶: ValueError – if the association is not in the model.

property generalizations : set[Generalization]¶

Get the set of generalizations in the domain model.

Type:¶: set[Generalization]

add_generalization(generalization: Generalization)[source]¶: Generalization: Add a generalization to the set of generalizations of the model.

remove_generalization(generalization: Generalization)[source]¶

Remove a generalization from the model and clean up references in involved classes.

Parameters:¶: generalization (Generalization) – The generalization to remove.
Raises:¶: ValueError – if the generalization is not in the model.

get_enumerations() → set[Enumeration][source]¶: set[Enumeration]: Get the set of enumerations in the domain model.

property packages : set[Package]¶

Get the set of packages in the domain model.

Type:¶: set[Package]

property constraints : set[Constraint]¶

Get the set of constraints in the domain model.

Type:¶: set[Constraint]

add_constraint(constraint: Constraint)[source]¶: Constraint: Add a constraint to the set of constraints of the model.

remove_constraint(constraint: Constraint)[source]¶

Remove a constraint from the model.

Parameters:¶: constraint (Constraint) – The constraint to remove.
Raises:¶: ValueError – if the constraint is not in the model.

get_classes() → set[Class][source]¶: set[Class]: Get all classes within the domain model.

get_class_by_name(class_name: str) → Class[source]¶: Class: Gets a class by name.

classes_sorted_by_inheritance() → list[Class][source]¶

list[Class]: Get the list of classes ordered by inheritance (parents first), ties by name.

Sorted by name, not timestamp: timestamps tie at clock resolution, so ties fell back to set order and the result changed between runs.

validate(raise_exception: bool = True) → dict[source]¶

Validate the domain model according to structural model constraints.

Parameters:¶: raise_exception (bool) – If True, raise ValueError when validation fails.
Returns:¶: Validation result with success flag, errors, and warnings.
Return type:¶: dict

_validate_generalizations(errors: list[str])[source]¶: Validate that generalizations reference types in the model.

_validate_associations(errors: list[str])[source]¶: Validate that association ends reference types in the model and that binary associations respect the navigability rules (at least one navigable end; the part end of a composition is navigable).

_validate_multiplicities(errors: list[str])[source]¶: Validate that multiplicities on association ends and attributes are well-formed.

_mandatory_dependencies() → dict[str, set[str]][source]¶

{class: classes it needs to exist before it can be created}.

An end with min >= 1 says every instance of the classes at the OTHER ends must already be linked to at least one instance of this end’s type — so those classes depend on this one.

_validate_mandatory_cycles(warnings: list[str])[source]¶

Flag a set of classes that can never be instantiated.

Example: Booking requires at least one ReservedRoom (1..*) while ReservedRoom requires exactly one Booking (1..1), through two DIFFERENT associations — so no per-association check sees it, and the generated API cannot create either class. A self-association with a mandatory end is the same defect with a cycle of length one.

A WARNING, not an error: an association with 1..1 on both ends is legal UML and BESSER’s own user_reference_domain_model ships three of them (Input/Output/Interaction_Modality, Knowledge/Topic), so the general metamodel validator must not reject it. It is fatal only when the model is about to be turned into a CRUD API, which is where the Spec-Driven Agent promotes this to a blocker.

_validate_duplicate_associations(warnings: list[str])[source]¶

Warn when one class pair is connected by more than one association.

Legal UML — homeAddress / workAddress are genuinely different relationships — so this is a warning, not an error. More often the pair is one concept drawn twice, which produces a redundant foreign key plus a _1-suffixed role name (the collision marker) in the generated schema.

_validate_constraints(errors: list[str])[source]¶

Validate that constraint contexts reference classes in the model.

Walks both class-level invariants (self.__constraints) and every class’s methods’ pre/post lists so a precondition with a stale or external context class is flagged the same way an invariant would be.

_validate_circular_inheritance(errors: list[str])[source]¶: Detect circular inheritance in the class hierarchy.

_validate_attribute_shadowing(errors: list[str])[source]¶: Validate that subclass attributes do not shadow inherited attributes.

_validate_member_name_collisions(errors: list[str])[source]¶

Validate that a method does not share its name with a feature of the class.

Generated code reaches both through the same name, so one of them wins and the other becomes unreachable: a body reading self.check_out - self.check_in subtracts two methods instead of two dates.

_validate_unique_end_names(errors: list[str])[source]¶

Validate that no class reaches two association ends with the same name.

Construction checks this, but renaming an end (or a class, which propagates to role names) afterwards does not.