# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2026-2026 Electronic Design Automation Abstraction (EDA²) #
# #
# Licensed under the Apache License, Version 2.0 (the "License"); #
# you may not use this file except in compliance with the License. #
# You may obtain a copy of the License at #
# #
# http://www.apache.org/licenses/LICENSE-2.0 #
# #
# Unless required by applicable law or agreed to in writing, software #
# distributed under the License is distributed on an "AS IS" BASIS, #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
# See the License for the specific language governing permissions and #
# limitations under the License. #
# #
# SPDX-License-Identifier: Apache-2.0 #
# ==================================================================================================================== #
#
"""
Abstract data model of requirements management.
A :class:`RequirementSpecification` is the root: it registers the persons, personas, labels, documents and layers its
items refer to, and every requirement and specification item by its ID.
A :class:`Requirement` has a title, a description, a creation time, a state, a kind and an obligation. It names its
authors and owners (:class:`~pyEDAA.Reports.Person`), the personas it is about (:class:`Persona`), its labels
(:class:`Label`), the documents attached to it (:class:`Document`), and the layer it belongs to (:class:`Layer`) - all
registered in the same specification. A requirement contains child requirements, which refine it.
A :class:`SpecificationItem` mirrors a requirement: it states how the system meets requirements. Specification items and
requirements are in an N:M relation.
An item's :class:`Link` states a relationship to another item, e.g. to its counterpart in another layer. An item's
history lists the events of its life cycle (:class:`HistoryEvent`), e.g. a split into other requirements.
"""
from __future__ import annotations
from datetime import datetime
from enum import Enum, Flag
from typing import Any, Callable, ClassVar, Generator, Hashable, Iterable, Mapping, \
Optional as Nullable, Self
from pyTooling.Common import getFullyQualifiedName, getTypeName
from pyTooling.DataModel import KeyValuePairsMixin
from pyTooling.Decorators import export, readonly
from pyTooling.Exceptions import AlreadyInHierarchyError, DuplicateElementError, NotInSameHierarchyError
from pyTooling.MetaClasses import ExtendedType
from pyTooling.Versioning import SemanticVersion
from pyEDAA.Reports import Person, ReportException
[docs]
@export
class RequirementsError(ReportException):
"""Base-exception of the requirements model."""
[docs]
@export
class NotInSameSpecificationError(RequirementsError, NotInSameHierarchyError):
"""
The exception is raised when an element is used together with an element or a person of another specification.
The element or person itself is valid, only its ownership is wrong: add it to the specification first. E.g. a link
from a requirement to a requirement of another specification.
"""
[docs]
@export
class AlreadyInSpecificationError(RequirementsError, AlreadyInHierarchyError):
"""The exception is raised when an element is added to a specification or an item, but it already has a parent."""
[docs]
@export
class DuplicatePersonaError(RequirementsError, DuplicateElementError):
"""The exception is raised when a specification or an item already contains a persona of the same ID."""
[docs]
@export
class DuplicateLabelError(RequirementsError, DuplicateElementError):
"""The exception is raised when a specification or an item already contains a label of the same ID."""
[docs]
@export
class DuplicateDocumentError(RequirementsError, DuplicateElementError):
"""The exception is raised when a specification or an item already contains a document of the same ID."""
[docs]
@export
class DuplicateLayerError(RequirementsError, DuplicateElementError):
"""The exception is raised when a specification already contains a layer of the same ID."""
[docs]
@export
class DuplicatePersonError(RequirementsError, DuplicateElementError):
"""The exception is raised when a specification or an item already contains a person of the same user ID."""
[docs]
@export
class DuplicateRequirementError(RequirementsError, DuplicateElementError):
"""The exception is raised when a specification or an item already contains a requirement of the same ID."""
[docs]
@export
class DuplicateSpecificationItemError(RequirementsError, DuplicateElementError):
"""The exception is raised when a specification or an item already contains a specification item of the same ID."""
[docs]
@export
class DuplicateLinkError(RequirementsError, DuplicateElementError):
"""The exception is raised when an item already has a link of the same kind to the same destination."""
[docs]
@export
class ItemState(Enum):
"""
The state of an item in its life cycle.
An item is open from :attr:`Placeholder` over :attr:`Draft`, :attr:`InReview`, :attr:`Final` and :attr:`Implemented`
to :attr:`Verified`. It ends :attr:`Closed` after its verification, or :attr:`Rejected` or :attr:`Obsolete` at any
time.
"""
Placeholder = 1 #: Reserved, e.g. an ID and a title, but not yet written.
Draft = 2 #: Written, but not yet reviewed.
InReview = 3 #: Under review by its stakeholders.
Final = 4 #: Reviewed and agreed by its stakeholders; it binds the design.
Implemented = 5 #: Implemented, but not yet verified.
Verified = 6 #: Implemented and verified; open for a regression.
Closed = 7 #: Verified and released, e.g. in a baseline; it changes no more.
Rejected = 8 #: Not accepted by its stakeholders.
Obsolete = 9 #: No longer valid, e.g. replaced by another one, split or merged.
[docs]
@export
class RequirementKind(Enum):
"""
The kind of a requirement: what it constrains.
The kinds follow the requirement types of ISO/IEC/IEEE 29148, with safety and security as kinds of their own, as
functional safety and security standards treat them separately.
"""
Functional = 1 #: A function the system performs, e.g. a register map or a protocol's behavior.
Performance = 2 #: How well a function is performed, e.g. a clock frequency, latency or throughput.
Quality = 3 #: A quality attribute, e.g. reliability, maintainability or usability.
Safety = 4 #: A measure against hazards, e.g. a safety mechanism of ISO 26262 or IEC 61508.
Security = 5 #: A measure against threats, e.g. encrypted bitstreams or secure boot.
Interface = 6 #: An interface to another system, e.g. a pin-out, a bus or a signal level.
Environmental = 7 #: An operating condition, e.g. a temperature range, vibration or EMC.
Constraint = 8 #: A design or implementation constraint, e.g. an FPGA family or a language.
Regulatory = 9 #: A standard, law or certification the system complies with.
Other = 10 #: Any other requirement.
[docs]
@export
class Obligation(Enum):
"""
The obligation of a requirement: whether it must, should or may be met.
The levels are those of the keywords of ISO/IEC/IEEE 29148 (*shall*, *should*, *may*) and of RFC 2119 (*MUST*,
*SHOULD*, *MAY*). A negated requirement (*shall not*) has the obligation of its positive keyword; the negation is part
of its text.
"""
Mandatory = 1 #: Binding: the requirement must be met (*shall*, *must*).
Recommended = 2 #: A goal: the requirement should be met, deviations are justified (*should*).
Optional = 3 #: A permission: the requirement may be met (*may*).
# A class with a property named like a class - ``Obligation`` - can't name that class in the annotation of a field: the
# class body's namespace, where annotations are evaluated, binds the name to the property.
_Obligation = Obligation
[docs]
@export
class VerificationMethod(Flag):
"""
The methods verifying a requirement, as flags.
The methods follow the verification methods of ISO/IEC/IEEE 29148 - inspection, analysis, demonstration and test -,
with simulation and formal verification as methods of their own, as hardware designs are verified by them.
"""
Unknown = 0 #: Not decided yet.
Inspection = 1 #: Examining the item, e.g. reviewing a schematic or source code.
Analysis = 2 #: Calculating or modeling, e.g. a timing analysis or a power budget.
Demonstration = 4 #: Operating the system without measurements, e.g. showing a feature works.
Test = 8 #: Operating the system with measurements under defined conditions, e.g. on a test bench.
Simulation = 16 #: Simulating a model of the design, e.g. a VHDL testbench.
Formal = 32 #: Proving properties of the design, e.g. by formal property checking.
[docs]
@export
class Base(KeyValuePairsMixin, metaclass=ExtendedType, slots=True):
"""
Base-class of every element of the requirements model: key-value pairs, a reference to the element containing it, and
a reference to the specification it is part of.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] #: The types a parent may have; set by each class with a parent.
_parent: Nullable[Base] #: The element containing this one, or ``None``.
_root: Nullable[RequirementSpecification] #: The specification, or ``None`` while the element isn't in one.
[docs]
def __init__(self, *, keyValuePairs: Nullable[Mapping[Hashable, Any]] = None, parent: Nullable[Base] = None) -> None:
"""
Initializes an element with its key-value pairs, its parent, and the parent's specification.
The parent doesn't list the element yet: the class setting the field the parent stores it by - an ID - adds it with
``parent._AddElement(self)``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:param parent: Optional, the element containing this one. Default: ``None``.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises TypeError: If parameter ``parent`` isn't of a type this class declares in :attr:`_PARENT_TYPE`.
"""
super().__init__(keyValuePairs)
if parent is None:
self._parent = None
self._root = None
elif not isinstance(parent, self._PARENT_TYPE):
typeNames = " or ".join(f"'{parentType.__name__}'" for parentType in self._PARENT_TYPE)
ex = TypeError(f"Parameter 'parent' is not of type {typeNames}.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
else:
self._parent = parent
self._root = parent._root
@property
def Parent(self) -> Nullable[Base]:
"""
Property to access the element containing this one (:attr:`_parent`).
Assigning a parent to an element without one adds the element to it, and sets the parent's specification as the
specification of this element and of every element below it.
:returns: The parent, or ``None``.
:raises ValueError: If ``None`` is assigned.
:raises TypeError: If the assigned parent isn't of a type this class declares in
:attr:`_PARENT_TYPE`.
:raises TypeError: If a parent is assigned to a :class:`RequirementSpecification`, which has
no
parent.
:raises AlreadyInSpecificationError: If the element already has a parent.
:raises DuplicatePersonaError: If the element is a persona, and the specification already contains a
persona of its ID.
:raises DuplicateLabelError: If the element is a label, and the specification already contains a label
of its ID.
:raises DuplicateDocumentError: If the element is a document, and the specification already contains a
document of its ID.
:raises DuplicateLayerError: If the element is a layer, and the specification already contains a layer
of its ID.
:raises DuplicateRequirementError: If the specification already contains a requirement of an ID of this
requirement or of a requirement below it.
:raises DuplicateSpecificationItemError: If the specification already contains a specification item of an ID of this
item or of an item below it.
"""
return self._parent
@Parent.setter
def Parent(self, parent: Base) -> None:
if parent is None:
raise ValueError("Parameter 'parent' is None.")
elif not isinstance(parent, self._PARENT_TYPE):
typeNames = " or ".join(f"'{parentType.__name__}'" for parentType in self._PARENT_TYPE)
ex = TypeError(f"Parameter 'parent' is not of type {typeNames}.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
if self._parent is not None:
raise AlreadyInSpecificationError(f"{getTypeName(self)} already has a parent.")
parent._AddElement(self)
self._parent = parent
self._root = parent._root
@readonly
def Root(self) -> Nullable[RequirementSpecification]:
"""
Read-only property to access the specification this element is part of (:attr:`_root`).
The specification is maintained by :attr:`Parent`: assigning a parent sets it for this element and every element
below it.
:returns: The specification, or ``None`` while the element isn't part of one.
"""
return self._root
[docs]
@export
class BaseWithID(Base):
"""
Base-class of the elements of the requirements model, which have an ID and a description.
The ID is unique among the elements of the same class in a specification.
"""
_DUPLICATE_ERROR: ClassVar[type[RequirementsError]] #: The error a second element of an ID raises; set by each class.
_id: str #: The element's ID.
_description: str #: The element's description, or ``""``.
[docs]
def __init__(
self,
identifier: str,
*,
description: str = "",
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
parent: Nullable[Base] = None
) -> None:
"""
Initializes an element with its ID, its description, its key-value pairs and its parent.
:param identifier: The element's ID.
:param description: Optional, the element's description. Default: ``""``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:param parent: Optional, the element containing this one. Default: ``None``.
:raises ValueError: If parameter ``identifier`` is ``None``.
:raises TypeError: If parameter ``identifier`` isn't of type :class:`str`.
:raises ValueError: If parameter ``identifier`` is empty.
:raises ValueError: If parameter ``description`` is ``None``.
:raises TypeError: If parameter ``description`` isn't of type :class:`str`.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises TypeError: If parameter ``parent`` isn't of a type this class declares in :attr:`_PARENT_TYPE`.
"""
super().__init__(keyValuePairs=keyValuePairs, parent=parent)
if identifier is None:
raise ValueError("Parameter 'identifier' is None.")
elif not isinstance(identifier, str):
ex = TypeError("Parameter 'identifier' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(identifier)}'.")
raise ex
elif identifier == "":
raise ValueError("Parameter 'identifier' is empty.")
if description is None:
raise ValueError("Parameter 'description' is None.")
elif not isinstance(description, str):
ex = TypeError("Parameter 'description' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(description)}'.")
raise ex
self._id = identifier
self._description = description
@readonly
def ID(self) -> str:
"""
Read-only property to access the element's ID (:attr:`_id`).
:returns: The ID.
"""
return self._id
@readonly
def Description(self) -> str:
"""
Read-only property to access the element's description (:attr:`_description`).
:returns: The description, or ``""``.
"""
return self._description
[docs]
@export
class RequirementSpecification(Base):
"""
The root of the requirements model: the requirements and specification items of a system, and the personas, labels,
documents and layers they refer to.
It registers every requirement and every specification item by its ID - also a child item -, and is its own
specification.
Persons have no parent: the specification registers the persons its items refer to by their user IDs, and a person may
be registered in several specifications.
"""
_name: Nullable[str] #: The specification's name, or ``None``.
_version: SemanticVersion #: The version of the specification.
_persons: dict[str, Person] #: The persons, by user ID.
_personas: dict[str, Persona] #: The personas, by ID.
_labels: dict[str, Label] #: The labels, by ID.
_documents: dict[str, Document] #: The documents, by ID.
_layers: dict[str, Layer] #: The layers, by ID.
_requirements: dict[str, Requirement] #: Every requirement, by ID, in the order they were added.
_specificationItems: dict[str, SpecificationItem] #: Every specification item, by ID, in the order they were added.
[docs]
def __init__(
self,
version: SemanticVersion,
name: Nullable[str] = None,
*,
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
) -> None:
"""
Initializes an empty requirement specification.
:param version: The version of the specification.
:param name: Optional, the specification's name. Default: ``None``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:raises ValueError: If parameter ``version`` is ``None``.
:raises TypeError: If parameter ``version`` isn't of type :class:`~pyTooling.Versioning.SemanticVersion`.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``name`` is empty.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
"""
super().__init__(keyValuePairs=keyValuePairs)
if version is None:
raise ValueError("Parameter 'version' is None.")
elif not isinstance(version, SemanticVersion):
ex = TypeError("Parameter 'version' is not of type 'SemanticVersion'.")
ex.add_note(f"Got type '{getFullyQualifiedName(version)}'.")
raise ex
if name is not None:
if not isinstance(name, str):
ex = TypeError("Parameter 'name' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(name)}'.")
raise ex
elif name == "":
raise ValueError("Parameter 'name' is empty.")
self._root = self
self._name = name
self._version = version
self._persons = {}
self._personas = {}
self._labels = {}
self._documents = {}
self._layers = {}
self._requirements = {}
self._specificationItems = {}
@Base.Parent.setter
def Parent(self, parent: None) -> None:
ex = TypeError(f"A '{getFullyQualifiedName(self)}' has no parent.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
[docs]
def _AddElement(self, element: BaseWithID) -> None:
"""
Register a persona, label, document, layer, top-level requirement or top-level specification item, which names the
specification as its parent.
:param element: The element.
:raises DuplicatePersonaError: If the specification already contains a persona of the element's ID.
:raises DuplicateLabelError: If the specification already contains a label of the element's ID.
:raises DuplicateDocumentError: If the specification already contains a document of the element's ID.
:raises DuplicateLayerError: If the specification already contains a layer of the element's ID.
:raises DuplicateRequirementError: If the specification already contains a requirement of the ID of the
requirement or of a requirement below it.
:raises DuplicateSpecificationItemError: If the specification already contains a specification item of the ID of the
item or of an item below it.
"""
if isinstance(element, BaseItem):
self._AddItems(element)
return
if isinstance(element, Persona):
elements = self._personas
elif isinstance(element, Label):
elements = self._labels
elif isinstance(element, Document):
elements = self._documents
else:
elements = self._layers
if element._id in elements:
raise element._DUPLICATE_ERROR(
f"{getTypeName(element)} '{element._id}' already exists in the specification."
)
elements[element._id] = element
[docs]
def _AddItems(self, item: BaseItem) -> None:
"""
Register an item and every item below it by their IDs, and set the specification as their specification and the
specification of their history events.
Either all of them are registered, or none.
:param item: The item joining the specification.
:raises DuplicateRequirementError: If the item is a requirement, and an ID of these requirements is registered
already, or used twice by them.
:raises DuplicateSpecificationItemError: If the item is a specification item, and an ID of these items is registered
already, or used twice by them.
"""
items = self._requirements if isinstance(item, Requirement) else self._specificationItems
ids = set()
subtree = (item, *item.IterateDescendants())
for element in subtree:
if element._id in items or element._id in ids:
raise element._DUPLICATE_ERROR(
f"{getTypeName(element)} '{element._id}' already exists in the specification."
)
ids.add(element._id)
for element in subtree:
element._root = self
items[element._id] = element
for event in element._history:
event._root = self
@readonly
def Name(self) -> Nullable[str]:
"""
Read-only property to access the specification's name (:attr:`_name`).
:returns: The name, or ``None``.
"""
return self._name
@readonly
def Version(self) -> SemanticVersion:
"""
Read-only property to access the version of the specification (:attr:`_version`).
:returns: The version.
"""
return self._version
@readonly
def Persons(self) -> dict[str, Person]:
"""
Read-only property to access the persons (:attr:`_persons`).
:returns: The persons, by user ID.
"""
return self._persons
[docs]
def IteratePersons(self, predicate: Nullable[Callable[[Person], bool]] = None) -> Generator[Person, None, None]:
"""
Iterate all or selected persons.
If parameter ``predicate`` is not None, the given filter function is used to skip persons in the generator.
:param predicate: Optional, filter function accepting a person and returning a boolean. Default: ``None``.
:returns: A generator of the persons, in the order they were added.
"""
if predicate is None:
yield from self._persons.values()
else:
for person in self._persons.values():
if predicate(person):
yield person
[docs]
def AddPerson(self, person: Person) -> None:
"""
Register a person, whom the specification's items can refer to.
E.g. an author or an owner of requirements. A person has no parent: the same person may be registered in several
specifications.
:param person: The person.
:raises ValueError: If parameter ``person`` is ``None``.
:raises TypeError: If parameter ``person`` isn't of type :class:`~pyEDAA.Reports.Person`.
:raises DuplicatePersonError: If the specification already contains a person of this user ID.
"""
if person is None:
raise ValueError("Parameter 'person' is None.")
elif not isinstance(person, Person):
ex = TypeError("Parameter 'person' is not of type 'Person'.")
ex.add_note(f"Got type '{getFullyQualifiedName(person)}'.")
raise ex
elif person._userID in self._persons:
raise DuplicatePersonError(f"Person '{person._userID}' already exists in the specification.")
self._persons[person._userID] = person
@readonly
def Personas(self) -> dict[str, Persona]:
"""
Read-only property to access the personas (:attr:`_personas`).
:returns: The personas, by ID.
"""
return self._personas
[docs]
def IteratePersonas(self, predicate: Nullable[Callable[[Persona], bool]] = None) -> Generator[Persona, None, None]:
"""
Iterate all or selected personas.
If parameter ``predicate`` is not None, the given filter function is used to skip personas in the generator.
:param predicate: Optional, filter function accepting a persona and returning a boolean. Default: ``None``.
:returns: A generator of the personas, in the order they were added.
"""
if predicate is None:
yield from self._personas.values()
else:
for persona in self._personas.values():
if predicate(persona):
yield persona
@readonly
def Labels(self) -> dict[str, Label]:
"""
Read-only property to access the labels (:attr:`_labels`).
:returns: The labels, by ID.
"""
return self._labels
[docs]
def IterateLabels(self, predicate: Nullable[Callable[[Label], bool]] = None) -> Generator[Label, None, None]:
"""
Iterate all or selected labels.
If parameter ``predicate`` is not None, the given filter function is used to skip labels in the generator.
:param predicate: Optional, filter function accepting a label and returning a boolean. Default: ``None``.
:returns: A generator of the labels, in the order they were added.
"""
if predicate is None:
yield from self._labels.values()
else:
for label in self._labels.values():
if predicate(label):
yield label
@readonly
def Documents(self) -> dict[str, Document]:
"""
Read-only property to access the documents (:attr:`_documents`).
:returns: The documents, by ID.
"""
return self._documents
[docs]
def IterateDocuments(self, predicate: Nullable[Callable[[Document], bool]] = None) -> Generator[Document, None, None]:
"""
Iterate all or selected documents.
If parameter ``predicate`` is not None, the given filter function is used to skip documents in the generator.
:param predicate: Optional, filter function accepting a document and returning a boolean. Default: ``None``.
:returns: A generator of the documents, in the order they were added.
"""
if predicate is None:
yield from self._documents.values()
else:
for document in self._documents.values():
if predicate(document):
yield document
@readonly
def Layers(self) -> dict[str, Layer]:
"""
Read-only property to access the layers (:attr:`_layers`).
:returns: The layers, by ID.
"""
return self._layers
[docs]
def IterateLayers(self, predicate: Nullable[Callable[[Layer], bool]] = None) -> Generator[Layer, None, None]:
"""
Iterate all or selected layers.
If parameter ``predicate`` is not None, the given filter function is used to skip layers in the generator.
:param predicate: Optional, filter function accepting a layer and returning a boolean. Default: ``None``.
:returns: A generator of the layers, in the order they were added.
"""
if predicate is None:
yield from self._layers.values()
else:
for layer in self._layers.values():
if predicate(layer):
yield layer
@readonly
def Requirements(self) -> dict[str, Requirement]:
"""
Read-only property to access every requirement (:attr:`_requirements`), also the child requirements.
:returns: The requirements, by ID, in the order they were added.
"""
return self._requirements
@readonly
def SpecificationItems(self) -> dict[str, SpecificationItem]:
"""
Read-only property to access every specification item (:attr:`_specificationItems`), also the child items.
:returns: The specification items, by ID, in the order they were added.
"""
return self._specificationItems
[docs]
def IterateRequirements(
self,
predicate: Nullable[Callable[[Requirement], bool]] = None
) -> Generator[Requirement, None, None]:
"""
Iterate all or selected requirements, also the child requirements, in the order they were added.
If parameter ``predicate`` is not None, the given filter function is used to skip requirements in the generator.
:param predicate: Optional, filter function accepting a requirement and returning a boolean. Default: ``None``.
:returns: A generator of the requirements.
"""
if predicate is None:
yield from self._requirements.values()
else:
for requirement in self._requirements.values():
if predicate(requirement):
yield requirement
[docs]
def IterateSpecificationItems(
self,
predicate: Nullable[Callable[[SpecificationItem], bool]] = None
) -> Generator[SpecificationItem, None, None]:
"""
Iterate all or selected specification items, also the child items, in the order they were added.
If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator.
:param predicate: Optional, filter function accepting a specification item and returning a boolean. Default:
``None``.
:returns: A generator of the specification items.
"""
if predicate is None:
yield from self._specificationItems.values()
else:
for specification in self._specificationItems.values():
if predicate(specification):
yield specification
[docs]
@export
class BaseWithName(BaseWithID):
"""
Base-class of the elements a specification registers for its requirements to refer to: an ID, a name and a
description.
Its parent is the :class:`RequirementSpecification`.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] = (RequirementSpecification, ) #: The element is in a specification.
_name: str #: The element's name.
[docs]
def __init__(
self,
identifier: str,
name: str,
*,
description: str = "",
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
parent: Nullable[RequirementSpecification] = None
) -> None:
"""
Initializes an element with its ID, name and description, and registers it in its specification.
:param identifier: The element's ID.
:param name: The element's name.
:param description: Optional, the element's description. Default: ``""``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:param parent: Optional, the specification. Default: ``None``.
:raises ValueError: If parameter ``identifier`` is ``None``.
:raises TypeError: If parameter ``identifier`` isn't of type :class:`str`.
:raises ValueError: If parameter ``identifier`` is empty.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``name`` is empty.
:raises ValueError: If parameter ``description`` is ``None``.
:raises TypeError: If parameter ``description`` isn't of type :class:`str`.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises TypeError: If parameter ``parent`` isn't of type :class:`RequirementSpecification`.
:raises DuplicatePersonaError: If the element is a persona, and the specification already contains a persona of
this ID.
:raises DuplicateLabelError: If the element is a label, and the specification already contains a label of this
ID.
:raises DuplicateDocumentError: If the element is a document, and the specification already contains a document of
this ID.
:raises DuplicateLayerError: If the element is a layer, and the specification already contains a layer of this
ID.
"""
super().__init__(identifier, description=description, keyValuePairs=keyValuePairs, parent=parent)
if name is None:
raise ValueError("Parameter 'name' is None.")
elif not isinstance(name, str):
ex = TypeError("Parameter 'name' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(name)}'.")
raise ex
elif name == "":
raise ValueError("Parameter 'name' is empty.")
self._name = name
if parent is not None:
parent._AddElement(self)
@readonly
def Name(self) -> str:
"""
Read-only property to access the element's name (:attr:`_name`).
:returns: The name.
"""
return self._name
[docs]
@export
class Persona(BaseWithName):
"""
A persona: a role a user of the system acts in, like the role of a use case or a user story.
E.g. an administrator, a reviewer or a quality inspector. A real person, e.g. an author, is a
:class:`~pyEDAA.Reports.Person`.
"""
_DUPLICATE_ERROR = DuplicatePersonaError #: The error a second persona of an ID raises.
[docs]
@export
class Label(BaseWithName):
"""
A label to classify items across layers and kinds.
E.g. a product variant, a release or a customer.
"""
_DUPLICATE_ERROR = DuplicateLabelError #: The error a second label of an ID raises.
[docs]
@export
class Document(BaseWithName):
"""
A document attached to items.
E.g. a datasheet, a schematic or a standard.
"""
_DUPLICATE_ERROR = DuplicateDocumentError #: The error a second document of an ID raises.
[docs]
@export
class Layer(BaseWithName):
"""
A layer of the system: the items of one engineering discipline.
E.g. electrical, mechanical, FPGA firmware and software requirements are four layers. Each item belongs to at most one
layer. A requirement of one layer has its counterparts in other layers, e.g. an electrical requirement in the FPGA
firmware, and this one in the software; links of kind :attr:`LinkKind.CounterpartOf` or :attr:`LinkKind.DerivesFrom`
state it.
"""
_DUPLICATE_ERROR = DuplicateLayerError #: The error a second layer of an ID raises.
[docs]
def IterateRequirements(
self,
predicate: Nullable[Callable[[Requirement], bool]] = None
) -> Generator[Requirement, None, None]:
"""
Iterate all or selected requirements of this layer, in the order the specification registered them.
If parameter ``predicate`` is not None, the given filter function is used to skip requirements in the generator.
:param predicate: Optional, filter function accepting a requirement and returning a boolean. Default: ``None``.
:returns: A generator of the layer's requirements; an empty one, while the layer isn't part of a
specification.
"""
if self._root is None:
return
if predicate is None:
for requirement in self._root._requirements.values():
if requirement._layer is self:
yield requirement
else:
for requirement in self._root._requirements.values():
if requirement._layer is self and predicate(requirement):
yield requirement
[docs]
def IterateSpecificationItems(
self,
predicate: Nullable[Callable[[SpecificationItem], bool]] = None
) -> Generator[SpecificationItem, None, None]:
"""
Iterate all or selected specification items of this layer, in the order the specification registered them.
If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator.
:param predicate: Optional, filter function accepting a specification item and returning a boolean. Default:
``None``.
:returns: A generator of the layer's specification items; an empty one, while the layer isn't part of a
specification.
"""
if self._root is None:
return
if predicate is None:
for specification in self._root._specificationItems.values():
if specification._layer is self:
yield specification
else:
for specification in self._root._specificationItems.values():
if specification._layer is self and predicate(specification):
yield specification
# A class with a property named like a class - ``Layer`` - can't name that class in the annotation of a field: the class
# body's namespace, where annotations are evaluated, binds the name to the property.
_Layer = Layer
[docs]
@export
class BaseItem(BaseWithID):
"""
Base-class of the items of a specification - requirements and specification items -: a title, a creation time, a
state, the layer, the persons, personas, labels and documents it refers to, its child items, its links and its
history.
An item refers only to persons, personas, labels, documents and layers of its own specification, so it must be part of
one to refer to any. A child item has the class of its parent; its ID is unique in the specification, too.
"""
_title: str #: The item's title.
_rationale: str #: Why the item exists or is as it is, or ``""``.
_created: datetime #: The time the item was created.
_state: ItemState #: The item's state in its life cycle.
_layer: Nullable[_Layer] #: The layer the item belongs to, or ``None``.
_authors: dict[str, Person] #: The authors of the item, by user ID.
_owners: dict[str, Person] #: The owners of the item, by user ID.
_personas: dict[str, Persona] #: The personas the item is about, by ID.
_labels: dict[str, Label] #: The labels of the item, by ID.
_attachments: dict[str, Document] #: The documents attached to the item, by ID.
_children: dict[str, Self] #: The child items, by ID.
_outboundLinks: list[Link] #: The links from this item, in the order they were added.
_inboundLinks: list[Link] #: The links to this item, in the order they were added.
_history: list[HistoryEvent] #: The events in the item's life cycle, in chronological order.
[docs]
def __init__(
self,
identifier: str,
title: str,
description: str = "",
created: Nullable[datetime] = None,
*,
rationale: str = "",
state: ItemState = ItemState.Draft,
layer: Nullable[Layer] = None,
authors: Nullable[Iterable[Person]] = None,
owners: Nullable[Iterable[Person]] = None,
personas: Nullable[Iterable[Persona]] = None,
labels: Nullable[Iterable[Label]] = None,
attachments: Nullable[Iterable[Document]] = None,
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
parent: Nullable[BaseItem | RequirementSpecification] = None
) -> None:
"""
Initializes an item with its title, creation time, state, layer, and the persons, personas, labels and documents it
refers to.
:param identifier: The item's ID.
:param title: The item's title.
:param description: Optional, the item's description. Default: ``""``.
:param created: Optional, the time the item was created; without a time zone, it is a local
time.
Default: ``None``, the current time.
:param rationale: Optional, why the item exists or is as it is. Default: ``""``.
:param state: Optional, the item's state. Default: :attr:`ItemState.Draft`.
:param layer: Optional, the layer the item belongs to. Default: ``None``.
:param authors: Optional, the authors of the item. Default: ``None``.
:param owners: Optional, the owners of the item. Default: ``None``.
:param personas: Optional, the personas the item is about. Default: ``None``.
:param labels: Optional, the labels of the item. Default: ``None``.
:param attachments: Optional, the documents attached to the item. Default: ``None``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:param parent: Optional, the parent item or the specification. Default: ``None``.
:raises ValueError: If parameter ``identifier`` is ``None``.
:raises TypeError: If parameter ``identifier`` isn't of type :class:`str`.
:raises ValueError: If parameter ``identifier`` is empty.
:raises ValueError: If parameter ``title`` is ``None``.
:raises TypeError: If parameter ``title`` isn't of type :class:`str`.
:raises ValueError: If parameter ``title`` is empty.
:raises ValueError: If parameter ``description`` is ``None``.
:raises TypeError: If parameter ``description`` isn't of type :class:`str`.
:raises TypeError: If parameter ``created`` isn't of type :class:`~datetime.datetime`.
:raises ValueError: If parameter ``rationale`` is ``None``.
:raises TypeError: If parameter ``rationale`` isn't of type :class:`str`.
:raises ValueError: If parameter ``state`` is ``None``.
:raises TypeError: If parameter ``state`` isn't of type :class:`ItemState`.
:raises TypeError: If parameter ``layer`` isn't of type :class:`Layer`.
:raises NotInSameSpecificationError: If parameter ``layer`` isn't part of the item's specification.
:raises TypeError: If parameter ``authors`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``authors`` contains an element not of type
:class:`~pyEDAA.Reports.Person`.
:raises NotInSameSpecificationError: If parameter ``authors`` contains an element, which isn't part of the item's
specification.
:raises DuplicatePersonError: If parameter ``authors`` contains a person twice.
:raises TypeError: If parameter ``owners`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``owners`` contains an element not of type
:class:`~pyEDAA.Reports.Person`.
:raises NotInSameSpecificationError: If parameter ``owners`` contains an element, which isn't part of the item's
specification.
:raises DuplicatePersonError: If parameter ``owners`` contains a person twice.
:raises TypeError: If parameter ``personas`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``personas`` contains an element not of type :class:`Persona`.
:raises NotInSameSpecificationError: If parameter ``personas`` contains an element, which isn't part of the item's
specification.
:raises DuplicatePersonaError: If parameter ``personas`` contains a persona twice.
:raises TypeError: If parameter ``labels`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``labels`` contains an element not of type :class:`Label`.
:raises NotInSameSpecificationError: If parameter ``labels`` contains an element, which isn't part of the item's
specification.
:raises DuplicateLabelError: If parameter ``labels`` contains a label twice.
:raises TypeError: If parameter ``attachments`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``attachments`` contains an element not of type :class:`Document`.
:raises NotInSameSpecificationError: If parameter ``attachments`` contains an element, which isn't part of the
item's specification.
:raises DuplicateDocumentError: If parameter ``attachments`` contains a document twice.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises TypeError: If parameter ``parent`` isn't of a type this class declares in
:attr:`_PARENT_TYPE`.
"""
super().__init__(identifier, description=description, keyValuePairs=keyValuePairs, parent=parent)
if title is None:
raise ValueError("Parameter 'title' is None.")
elif not isinstance(title, str):
ex = TypeError("Parameter 'title' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(title)}'.")
raise ex
elif title == "":
raise ValueError("Parameter 'title' is empty.")
if rationale is None:
raise ValueError("Parameter 'rationale' is None.")
elif not isinstance(rationale, str):
ex = TypeError("Parameter 'rationale' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(rationale)}'.")
raise ex
if created is None:
created = datetime.now()
elif not isinstance(created, datetime):
ex = TypeError("Parameter 'created' is not of type 'datetime'.")
ex.add_note(f"Got type '{getFullyQualifiedName(created)}'.")
raise ex
if state is None:
raise ValueError("Parameter 'state' is None.")
elif not isinstance(state, ItemState):
ex = TypeError("Parameter 'state' is not of type 'ItemState'.")
ex.add_note(f"Got type '{getFullyQualifiedName(state)}'.")
raise ex
if layer is not None:
if not isinstance(layer, Layer):
ex = TypeError("Parameter 'layer' is not of type 'Layer'.")
ex.add_note(f"Got type '{getFullyQualifiedName(layer)}'.")
raise ex
elif self._root is None or layer._root is not self._root:
ex = NotInSameSpecificationError("Parameter 'layer' isn't part of the item's specification.")
ex.add_note(f"Got layer '{layer._id}'.")
raise ex
self._title = title
self._rationale = rationale
self._created = created
self._state = state
self._layer = layer
self._authors = {}
self._owners = {}
self._personas = {}
self._labels = {}
self._attachments = {}
self._children = {}
self._outboundLinks = []
self._inboundLinks = []
self._history = []
for parameterName, references, referenceType, container, duplicateError in (
("authors", authors, Person, self._authors, DuplicatePersonError),
("owners", owners, Person, self._owners, DuplicatePersonError),
("personas", personas, Persona, self._personas, DuplicatePersonaError),
("labels", labels, Label, self._labels, DuplicateLabelError),
("attachments", attachments, Document, self._attachments, DuplicateDocumentError),
):
if references is None:
continue
elif not isinstance(references, Iterable):
ex = TypeError(f"Parameter '{parameterName}' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(references)}'.")
raise ex
elif isinstance(references, KeyValuePairsMixin):
ex = TypeError(f"Parameter '{parameterName}' is a single element, not an iterable of elements.")
ex.add_note(f"Got type '{getFullyQualifiedName(references)}'.")
raise ex
for reference in references:
if not isinstance(reference, referenceType):
ex = TypeError(f"Parameter '{parameterName}' contains an element not of type '{referenceType.__name__}'.")
ex.add_note(f"Got type '{getFullyQualifiedName(reference)}'.")
raise ex
if referenceType is Person:
key = reference._userID
registered = self._root is not None and self._root._persons.get(key) is reference
else:
key = reference._id
registered = self._root is not None and reference._root is self._root
if not registered:
ex = NotInSameSpecificationError(
f"Parameter '{parameterName}' contains an element not part of the item's specification."
)
ex.add_note(f"Got {referenceType.__name__.lower()} '{key}'.")
raise ex
elif key in container:
ex = duplicateError(f"Parameter '{parameterName}' contains an element twice.")
ex.add_note(f"Got {referenceType.__name__.lower()} '{key}'.")
raise ex
container[key] = reference
[docs]
def _AddElement(self, element: Self | HistoryEvent) -> None:
"""
Add a child item or a history event, which names this item as its parent.
A child item is registered with every item below it in the specification.
:param element: The child item or history event.
:raises DuplicateRequirementError: If the child is a requirement, and the specification already contains a
requirement of an ID of the child or a requirement below it.
:raises DuplicateSpecificationItemError: If the child is a specification item, and the specification already
contains a specification item of an ID of the child or an item below it.
:raises DuplicateRequirementError: If the child is a requirement, this item isn't part of a specification, and
it has a child of this ID already.
:raises DuplicateSpecificationItemError: If the child is a specification item, this item isn't part of a
specification, and it has a child of this ID already.
:raises RequirementsError: If the history event is earlier than the item's creation or its last event.
"""
if isinstance(element, HistoryEvent):
previous = self._history[-1]._timestamp if len(self._history) > 0 else self._created
if element._timestamp.astimezone() < previous.astimezone():
ex = RequirementsError("History event is earlier than the item's creation or its last event.")
ex.add_note(f"Got '{element._timestamp.isoformat()}' after '{previous.isoformat()}'.")
raise ex from ValueError(f"Parameter 'timestamp' is earlier than '{previous.isoformat()}'.")
self._history.append(element)
else:
if self._root is not None:
self._root._AddItems(element)
elif element._id in self._children:
raise element._DUPLICATE_ERROR(f"{getTypeName(self)} '{self._id}' already has a child '{element._id}'.")
self._children[element._id] = element
@readonly
def Title(self) -> str:
"""
Read-only property to access the item's title (:attr:`_title`).
:returns: The title.
"""
return self._title
@readonly
def Rationale(self) -> str:
"""
Read-only property to access why the item exists or is as it is (:attr:`_rationale`).
:returns: The rationale, or ``""``.
"""
return self._rationale
@readonly
def Created(self) -> datetime:
"""
Read-only property to access the time the item was created (:attr:`_created`).
:returns: The time; without a time zone, it is a local time.
"""
return self._created
@property
def State(self) -> ItemState:
"""
Property to access the item's state in its life cycle (:attr:`_state`).
:returns: The state.
:raises ValueError: If ``None`` is assigned.
:raises TypeError: If the assigned state isn't of type :class:`ItemState`.
"""
return self._state
@State.setter
def State(self, state: ItemState) -> None:
if state is None:
raise ValueError("Parameter 'state' is None.")
elif not isinstance(state, ItemState):
ex = TypeError("Parameter 'state' is not of type 'ItemState'.")
ex.add_note(f"Got type '{getFullyQualifiedName(state)}'.")
raise ex
self._state = state
@readonly
def Layer(self) -> Nullable[Layer]:
"""
Read-only property to access the layer the item belongs to (:attr:`_layer`).
:returns: The layer, or ``None``.
"""
return self._layer
@readonly
def Authors(self) -> dict[str, Person]:
"""
Read-only property to access the authors of the item (:attr:`_authors`).
:returns: The authors, by user ID.
"""
return self._authors
@readonly
def Owners(self) -> dict[str, Person]:
"""
Read-only property to access the owners of the item (:attr:`_owners`).
:returns: The owners, by user ID.
"""
return self._owners
@readonly
def Personas(self) -> dict[str, Persona]:
"""
Read-only property to access the personas the item is about (:attr:`_personas`).
E.g. the role of a user story: "As a reviewer, I want ...".
:returns: The personas, by ID.
"""
return self._personas
@readonly
def Labels(self) -> dict[str, Label]:
"""
Read-only property to access the labels of the item (:attr:`_labels`).
:returns: The labels, by ID.
"""
return self._labels
@readonly
def Attachments(self) -> dict[str, Document]:
"""
Read-only property to access the documents attached to the item (:attr:`_attachments`).
:returns: The documents, by ID.
"""
return self._attachments
@readonly
def Children(self) -> dict[str, Self]:
"""
Read-only property to access the child items (:attr:`_children`).
:returns: The child items, by ID.
"""
return self._children
@readonly
def OutboundLinks(self) -> list[Link]:
"""
Read-only property to access the links from this item (:attr:`_outboundLinks`).
:returns: The links, in the order they were added.
"""
return self._outboundLinks
@readonly
def InboundLinks(self) -> list[Link]:
"""
Read-only property to access the links to this item (:attr:`_inboundLinks`).
:returns: The links, in the order they were added.
"""
return self._inboundLinks
@readonly
def History(self) -> list[HistoryEvent]:
"""
Read-only property to access the events in the item's life cycle (:attr:`_history`).
:returns: The events, in chronological order.
"""
return self._history
[docs]
def IterateChildren(self, predicate: Nullable[Callable[[Self], bool]] = None) -> Generator[Self, None, None]:
"""
Iterate all or selected child items.
If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator.
:param predicate: Optional, filter function accepting an item and returning a boolean. Default: ``None``.
:returns: A generator of the child items.
"""
if predicate is None:
yield from self._children.values()
else:
for child in self._children.values():
if predicate(child):
yield child
[docs]
def IterateDescendants(self, predicate: Nullable[Callable[[Self], bool]] = None) -> Generator[Self, None, None]:
"""
Iterate all or selected items below this one - its children, grandchildren, ... -, depth-first: each child
followed by the items below it.
If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator. A skipped
item's children are still iterated.
:param predicate: Optional, filter function accepting an item and returning a boolean. Default: ``None``.
:returns: A generator of the items below this one.
"""
if predicate is None:
for child in self._children.values():
yield child
yield from child.IterateDescendants()
else:
for child in self._children.values():
if predicate(child):
yield child
yield from child.IterateDescendants(predicate)
[docs]
def LinkTo(
self,
destination: BaseItem,
kind: LinkKind,
*,
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
) -> Link:
"""
Create an outbound link from this item to the given item.
:param destination: The item the link points to.
:param kind: The relationship the link states.
:param keyValuePairs: Optional, the key-value pairs of the link. Default: ``None``.
:returns: The link from this item to the destination.
:raises ValueError: If parameter ``destination`` is ``None``.
:raises TypeError: If parameter ``destination`` isn't of type :class:`BaseItem`.
:raises ValueError: If parameter ``destination`` is this item.
:raises NotInSameSpecificationError: If parameter ``destination`` isn't part of this item's specification.
:raises ValueError: If parameter ``kind`` is ``None``.
:raises TypeError: If parameter ``kind`` isn't of type :class:`LinkKind`.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises NotInSameSpecificationError: If this item isn't part of a specification.
:raises DuplicateLinkError: If this item has a link of this kind to the destination already.
.. seealso::
:meth:`LinkFrom`
|rarr| Create an inbound link from the given item to this item.
"""
return Link(self, destination, kind, keyValuePairs=keyValuePairs)
[docs]
def LinkFrom(
self,
source: BaseItem,
kind: LinkKind,
*,
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
) -> Link:
"""
Create an inbound link from the given item to this item.
:param source: The item the link starts at.
:param kind: The relationship the link states.
:param keyValuePairs: Optional, the key-value pairs of the link. Default: ``None``.
:returns: The link from the source to this item.
:raises ValueError: If parameter ``source`` is ``None``.
:raises TypeError: If parameter ``source`` isn't of type :class:`BaseItem`.
:raises NotInSameSpecificationError: If parameter ``source`` isn't part of a specification.
:raises ValueError: If parameter ``source`` is this item.
:raises ValueError: If parameter ``kind`` is ``None``.
:raises TypeError: If parameter ``kind`` isn't of type :class:`LinkKind`.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises NotInSameSpecificationError: If this item isn't part of the source's specification.
:raises DuplicateLinkError: If the source has a link of this kind to this item already.
.. seealso::
:meth:`LinkTo`
|rarr| Create an outbound link from this item to the given item.
"""
return Link(source, self, kind, keyValuePairs=keyValuePairs)
[docs]
def IterateOutboundLinks(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[Link, None, None]:
"""
Iterate all or selected links from this item.
If parameter ``predicate`` is not None, the given filter function is used to skip links in the generator.
:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
:returns: A generator of the links from this item.
"""
if predicate is None:
yield from self._outboundLinks
else:
for link in self._outboundLinks:
if predicate(link):
yield link
[docs]
def IterateInboundLinks(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[Link, None, None]:
"""
Iterate all or selected links to this item.
If parameter ``predicate`` is not None, the given filter function is used to skip links in the generator.
:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
:returns: A generator of the links to this item.
"""
if predicate is None:
yield from self._inboundLinks
else:
for link in self._inboundLinks:
if predicate(link):
yield link
[docs]
def _IterateTrace(
self,
predicate: Nullable[Callable[[Link], bool]],
inbound: bool
) -> Generator[BaseItem, None, None]:
"""
Iterate the items reached by following links transitively, depth-first, each item once.
:param predicate: Filter function accepting a link and returning a boolean, or ``None`` to follow every link.
:param inbound: ``True`` to follow links to their sources, ``False`` to their destinations.
:returns: A generator of the items reached, without this item.
"""
visited = {self}
if predicate is None:
def follow(item: BaseItem) -> Generator[BaseItem, None, None]:
"""
Nested function for recursion, following every link.
:param item: The item, whose links are followed.
:returns: A generator of the items reached from the item, not visited before.
"""
for link in (item._inboundLinks if inbound else item._outboundLinks):
reached = link._source if inbound else link._destination
if reached not in visited:
visited.add(reached)
yield reached
yield from follow(reached)
else:
def follow(item: BaseItem) -> Generator[BaseItem, None, None]:
"""
Nested function for recursion, following the links the predicate accepts.
:param item: The item, whose links are followed.
:returns: A generator of the items reached from the item, not visited before.
"""
for link in (item._inboundLinks if inbound else item._outboundLinks):
reached = link._source if inbound else link._destination
if reached not in visited and predicate(link):
visited.add(reached)
yield reached
yield from follow(reached)
yield from follow(self)
[docs]
def IterateTrace(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[BaseItem, None, None]:
"""
Iterate the items this item traces to: the destinations of its links, and of their links, ..., depth-first, each
item once.
If parameter ``predicate`` is not None, only links accepted by the given filter function are followed.
:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
:returns: A generator of the items reached, without this item.
"""
yield from self._IterateTrace(predicate, False)
[docs]
def IterateInboundTrace(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[BaseItem, None, None]:
"""
Iterate the items tracing to this item: the sources of its inbound links, and of their inbound links, ...,
depth-first, each item once.
If parameter ``predicate`` is not None, only links accepted by the given filter function are followed.
:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
:returns: A generator of the items reached, without this item.
"""
yield from self._IterateTrace(predicate, True)
[docs]
@export
class Requirement(BaseItem):
"""
A requirement: a condition or capability the system must, should or may meet, its kind and its obligation.
Its parent is the :class:`RequirementSpecification` for a top-level requirement, or the :class:`Requirement` it
refines - a child requirement. The specification registers either by its ID.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] #: In a requirement or the specification; assigned below.
_kind: RequirementKind #: What the requirement constrains.
_obligation: _Obligation #: Whether the requirement must, should or may be met.
_verificationMethods: VerificationMethod #: The methods verifying the requirement.
_acceptanceCriteria: list[str] #: The criteria the verification accepts the requirement by.
_specificationItems: dict[str, SpecificationItem] #: The specification items specifying this requirement, by ID.
[docs]
def __init__(
self,
identifier: str,
title: str,
kind: RequirementKind,
description: str = "",
created: Nullable[datetime] = None,
*,
obligation: Obligation = Obligation.Mandatory,
verificationMethods: VerificationMethod = VerificationMethod.Unknown,
acceptanceCriteria: Nullable[Iterable[str]] = None,
rationale: str = "",
state: ItemState = ItemState.Draft,
layer: Nullable[Layer] = None,
authors: Nullable[Iterable[Person]] = None,
owners: Nullable[Iterable[Person]] = None,
personas: Nullable[Iterable[Persona]] = None,
labels: Nullable[Iterable[Label]] = None,
attachments: Nullable[Iterable[Document]] = None,
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
parent: Nullable[Requirement | RequirementSpecification] = None
) -> None:
"""
Initializes a requirement, adds it to its parent, and registers it in its specification.
:param identifier: The requirement's ID.
:param title: The requirement's title.
:param kind: What the requirement constrains.
:param description: Optional, the requirement's description. Default: ``""``.
:param created: Optional, the time the requirement was created; without a time zone, it is a
local time. Default: ``None``, the current time.
:param obligation: Optional, whether the requirement must, should or may be met. Default:
:attr:`Obligation.Mandatory`.
:param verificationMethods: Optional, the methods verifying the requirement. Default:
:attr:`VerificationMethod.Unknown`.
:param acceptanceCriteria: Optional, the criteria the verification accepts the requirement by. Default:
``None``.
:param rationale: Optional, why the requirement exists or is as it is. Default: ``""``.
:param state: Optional, the requirement's state. Default: :attr:`ItemState.Draft`.
:param layer: Optional, the layer the requirement belongs to. Default: ``None``.
:param authors: Optional, the authors of the requirement. Default: ``None``.
:param owners: Optional, the owners of the requirement. Default: ``None``.
:param personas: Optional, the personas the requirement is about. Default: ``None``.
:param labels: Optional, the labels of the requirement. Default: ``None``.
:param attachments: Optional, the documents attached to the requirement. Default: ``None``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:param parent: Optional, the requirement this one refines, or the specification. Default:
``None``.
:raises ValueError: If parameter ``identifier`` is ``None``.
:raises TypeError: If parameter ``identifier`` isn't of type :class:`str`.
:raises ValueError: If parameter ``identifier`` is empty.
:raises ValueError: If parameter ``title`` is ``None``.
:raises TypeError: If parameter ``title`` isn't of type :class:`str`.
:raises ValueError: If parameter ``title`` is empty.
:raises ValueError: If parameter ``kind`` is ``None``.
:raises TypeError: If parameter ``kind`` isn't of type :class:`RequirementKind`.
:raises ValueError: If parameter ``description`` is ``None``.
:raises TypeError: If parameter ``description`` isn't of type :class:`str`.
:raises TypeError: If parameter ``created`` isn't of type :class:`~datetime.datetime`.
:raises ValueError: If parameter ``obligation`` is ``None``.
:raises TypeError: If parameter ``obligation`` isn't of type :class:`Obligation`.
:raises ValueError: If parameter ``verificationMethods`` is ``None``.
:raises TypeError: If parameter ``verificationMethods`` isn't of type :class:`VerificationMethod`.
:raises TypeError: If parameter ``acceptanceCriteria`` isn't iterable, or is a single string.
:raises TypeError: If parameter ``acceptanceCriteria`` contains an element not of type
:class:`str`.
:raises ValueError: If parameter ``acceptanceCriteria`` contains an empty criterion.
:raises ValueError: If parameter ``rationale`` is ``None``.
:raises TypeError: If parameter ``rationale`` isn't of type :class:`str`.
:raises ValueError: If parameter ``state`` is ``None``.
:raises TypeError: If parameter ``state`` isn't of type :class:`ItemState`.
:raises TypeError: If parameter ``layer`` isn't of type :class:`Layer`.
:raises NotInSameSpecificationError: If parameter ``layer`` isn't part of the requirement's specification.
:raises TypeError: If parameter ``authors`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``authors`` contains an element not of type
:class:`~pyEDAA.Reports.Person`.
:raises NotInSameSpecificationError: If parameter ``authors`` contains an element, which isn't part of the
requirement's specification.
:raises DuplicatePersonError: If parameter ``authors`` contains a person twice.
:raises TypeError: If parameter ``owners`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``owners`` contains an element not of type
:class:`~pyEDAA.Reports.Person`.
:raises NotInSameSpecificationError: If parameter ``owners`` contains an element, which isn't part of the
requirement's specification.
:raises DuplicatePersonError: If parameter ``owners`` contains a person twice.
:raises TypeError: If parameter ``personas`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``personas`` contains an element not of type :class:`Persona`.
:raises NotInSameSpecificationError: If parameter ``personas`` contains an element, which isn't part of the
requirement's specification.
:raises DuplicatePersonaError: If parameter ``personas`` contains a persona twice.
:raises TypeError: If parameter ``labels`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``labels`` contains an element not of type :class:`Label`.
:raises NotInSameSpecificationError: If parameter ``labels`` contains an element, which isn't part of the
requirement's specification.
:raises DuplicateLabelError: If parameter ``labels`` contains a label twice.
:raises TypeError: If parameter ``attachments`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``attachments`` contains an element not of type :class:`Document`.
:raises NotInSameSpecificationError: If parameter ``attachments`` contains an element, which isn't part of the
requirement's specification.
:raises DuplicateDocumentError: If parameter ``attachments`` contains a document twice.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises TypeError: If parameter ``parent`` isn't of type :class:`Requirement` or
:class:`RequirementSpecification`.
:raises DuplicateRequirementError: If the specification already contains a requirement of this ID.
"""
super().__init__(
identifier,
title,
description,
created,
rationale=rationale,
state=state,
layer=layer,
authors=authors,
owners=owners,
personas=personas,
labels=labels,
attachments=attachments,
keyValuePairs=keyValuePairs,
parent=parent
)
if kind is None:
raise ValueError("Parameter 'kind' is None.")
elif not isinstance(kind, RequirementKind):
ex = TypeError("Parameter 'kind' is not of type 'RequirementKind'.")
ex.add_note(f"Got type '{getFullyQualifiedName(kind)}'.")
raise ex
if obligation is None:
raise ValueError("Parameter 'obligation' is None.")
elif not isinstance(obligation, Obligation):
ex = TypeError("Parameter 'obligation' is not of type 'Obligation'.")
ex.add_note(f"Got type '{getFullyQualifiedName(obligation)}'.")
raise ex
if verificationMethods is None:
raise ValueError("Parameter 'verificationMethods' is None.")
elif not isinstance(verificationMethods, VerificationMethod):
ex = TypeError("Parameter 'verificationMethods' is not of type 'VerificationMethod'.")
ex.add_note(f"Got type '{getFullyQualifiedName(verificationMethods)}'.")
raise ex
self._acceptanceCriteria = acceptanceCriterionList = []
if acceptanceCriteria is not None:
if not isinstance(acceptanceCriteria, Iterable):
ex = TypeError("Parameter 'acceptanceCriteria' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(acceptanceCriteria)}'.")
raise ex
elif isinstance(acceptanceCriteria, str):
ex = TypeError("Parameter 'acceptanceCriteria' is a single string, not an iterable of strings.")
ex.add_note(f"Got value '{acceptanceCriteria}'.")
raise ex
for criterion in acceptanceCriteria:
if not isinstance(criterion, str):
ex = TypeError("Parameter 'acceptanceCriteria' contains an element not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(criterion)}'.")
raise ex
elif criterion == "":
raise ValueError("Parameter 'acceptanceCriteria' contains an empty criterion.")
acceptanceCriterionList.append(criterion)
self._kind = kind
self._obligation = obligation
self._verificationMethods = verificationMethods
self._specificationItems = {}
if parent is not None:
parent._AddElement(self)
@readonly
def Kind(self) -> RequirementKind:
"""
Read-only property to access what the requirement constrains (:attr:`_kind`).
:returns: The requirement's kind.
"""
return self._kind
@readonly
def Obligation(self) -> Obligation:
"""
Read-only property to access whether the requirement must, should or may be met (:attr:`_obligation`).
:returns: The requirement's obligation.
"""
return self._obligation
@readonly
def VerificationMethods(self) -> VerificationMethod:
"""
Read-only property to access the methods verifying the requirement (:attr:`_verificationMethods`).
:returns: The verification methods.
"""
return self._verificationMethods
@readonly
def AcceptanceCriteria(self) -> list[str]:
"""
Read-only property to access the criteria the verification accepts the requirement by (:attr:`_acceptanceCriteria`).
:returns: The acceptance criteria, in the order given.
"""
return self._acceptanceCriteria
@readonly
def SpecificationItems(self) -> dict[str, SpecificationItem]:
"""
Read-only property to access the specification items specifying this requirement (:attr:`_specificationItems`).
The relation is maintained by :meth:`SpecificationItem.AddRequirement`.
:returns: The specification items, by ID.
"""
return self._specificationItems
Requirement._PARENT_TYPE = (Requirement, RequirementSpecification)
Requirement._DUPLICATE_ERROR = DuplicateRequirementError
[docs]
@export
class SpecificationItem(BaseItem):
"""
A specification item: how the system meets requirements.
E.g. a design decision, an architecture or an interface description. It mirrors a requirement - with an ID, a title, a
state, a layer, persons, personas, labels, documents, child items, links and a history -, and specifies any number of
requirements; a requirement is specified by any number of specification items.
Its parent is the :class:`RequirementSpecification` for a top-level item, or the :class:`SpecificationItem` it
details. The specification registers either by its ID.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] #: An item is in an item or the specification; assigned below the class.
_requirements: dict[str, Requirement] #: The requirements this item specifies, by ID.
[docs]
def __init__(
self,
identifier: str,
title: str,
description: str = "",
created: Nullable[datetime] = None,
*,
requirements: Nullable[Iterable[Requirement]] = None,
rationale: str = "",
state: ItemState = ItemState.Draft,
layer: Nullable[Layer] = None,
authors: Nullable[Iterable[Person]] = None,
owners: Nullable[Iterable[Person]] = None,
personas: Nullable[Iterable[Persona]] = None,
labels: Nullable[Iterable[Label]] = None,
attachments: Nullable[Iterable[Document]] = None,
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
parent: Nullable[SpecificationItem | RequirementSpecification] = None
) -> None:
"""
Initializes a specification item, adds it to its parent, registers it in its specification, and relates it to the
requirements it specifies.
:param identifier: The item's ID.
:param title: The item's title.
:param description: Optional, the item's description. Default: ``""``.
:param created: Optional, the time the item was created; without a time zone, it is a local
time. Default: ``None``, the current time.
:param requirements: Optional, the requirements the item specifies. Default: ``None``.
:param rationale: Optional, why the item exists or is as it is. Default: ``""``.
:param state: Optional, the item's state. Default: :attr:`ItemState.Draft`.
:param layer: Optional, the layer the item belongs to. Default: ``None``.
:param authors: Optional, the authors of the item. Default: ``None``.
:param owners: Optional, the owners of the item. Default: ``None``.
:param personas: Optional, the personas the item is about. Default: ``None``.
:param labels: Optional, the labels of the item. Default: ``None``.
:param attachments: Optional, the documents attached to the item. Default: ``None``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:param parent: Optional, the specification item this one details, or the specification.
Default: ``None``.
:raises ValueError: If parameter ``identifier`` is ``None``.
:raises TypeError: If parameter ``identifier`` isn't of type :class:`str`.
:raises ValueError: If parameter ``identifier`` is empty.
:raises ValueError: If parameter ``title`` is ``None``.
:raises TypeError: If parameter ``title`` isn't of type :class:`str`.
:raises ValueError: If parameter ``title`` is empty.
:raises ValueError: If parameter ``description`` is ``None``.
:raises TypeError: If parameter ``description`` isn't of type :class:`str`.
:raises TypeError: If parameter ``created`` isn't of type :class:`~datetime.datetime`.
:raises TypeError: If parameter ``requirements`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``requirements`` contains an element not of type
:class:`Requirement`.
:raises NotInSameSpecificationError: If parameter ``requirements`` contains a requirement, which isn't part of
the item's specification.
:raises DuplicateRequirementError: If parameter ``requirements`` contains a requirement twice.
:raises ValueError: If parameter ``rationale`` is ``None``.
:raises TypeError: If parameter ``rationale`` isn't of type :class:`str`.
:raises ValueError: If parameter ``state`` is ``None``.
:raises TypeError: If parameter ``state`` isn't of type :class:`ItemState`.
:raises TypeError: If parameter ``layer`` isn't of type :class:`Layer`.
:raises NotInSameSpecificationError: If parameter ``layer`` isn't part of the item's specification.
:raises TypeError: If parameter ``authors`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``authors`` contains an element not of type
:class:`~pyEDAA.Reports.Person`.
:raises NotInSameSpecificationError: If parameter ``authors`` contains an element, which isn't part of the
item's specification.
:raises DuplicatePersonError: If parameter ``authors`` contains a person twice.
:raises TypeError: If parameter ``owners`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``owners`` contains an element not of type
:class:`~pyEDAA.Reports.Person`.
:raises NotInSameSpecificationError: If parameter ``owners`` contains an element, which isn't part of the item's
specification.
:raises DuplicatePersonError: If parameter ``owners`` contains a person twice.
:raises TypeError: If parameter ``personas`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``personas`` contains an element not of type :class:`Persona`.
:raises NotInSameSpecificationError: If parameter ``personas`` contains an element, which isn't part of the
item's specification.
:raises DuplicatePersonaError: If parameter ``personas`` contains a persona twice.
:raises TypeError: If parameter ``labels`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``labels`` contains an element not of type :class:`Label`.
:raises NotInSameSpecificationError: If parameter ``labels`` contains an element, which isn't part of the item's
specification.
:raises DuplicateLabelError: If parameter ``labels`` contains a label twice.
:raises TypeError: If parameter ``attachments`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``attachments`` contains an element not of type
:class:`Document`.
:raises NotInSameSpecificationError: If parameter ``attachments`` contains an element, which isn't part of the
item's specification.
:raises DuplicateDocumentError: If parameter ``attachments`` contains a document twice.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises TypeError: If parameter ``parent`` isn't of type :class:`SpecificationItem` or
:class:`RequirementSpecification`.
:raises DuplicateSpecificationItemError: If the specification already contains a specification item of this ID.
"""
super().__init__(
identifier,
title,
description,
created,
rationale=rationale,
state=state,
layer=layer,
authors=authors,
owners=owners,
personas=personas,
labels=labels,
attachments=attachments,
keyValuePairs=keyValuePairs,
parent=parent
)
self._requirements = {}
if requirements is not None:
if not isinstance(requirements, Iterable):
ex = TypeError("Parameter 'requirements' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(requirements)}'.")
raise ex
elif isinstance(requirements, KeyValuePairsMixin):
ex = TypeError("Parameter 'requirements' is a single element, not an iterable of elements.")
ex.add_note(f"Got type '{getFullyQualifiedName(requirements)}'.")
raise ex
for requirement in requirements:
if not isinstance(requirement, Requirement):
ex = TypeError("Parameter 'requirements' contains an element not of type 'Requirement'.")
ex.add_note(f"Got type '{getFullyQualifiedName(requirement)}'.")
raise ex
elif self._root is None or requirement._root is not self._root:
ex = NotInSameSpecificationError(
"Parameter 'requirements' contains a requirement not part of the item's specification."
)
ex.add_note(f"Got requirement '{requirement._id}'.")
raise ex
elif requirement._id in self._requirements:
ex = DuplicateRequirementError("Parameter 'requirements' contains a requirement twice.")
ex.add_note(f"Got requirement '{requirement._id}'.")
raise ex
self._requirements[requirement._id] = requirement
if parent is not None:
parent._AddElement(self)
for requirement in self._requirements.values():
requirement._specificationItems[identifier] = self
@readonly
def Requirements(self) -> dict[str, Requirement]:
"""
Read-only property to access the requirements this item specifies (:attr:`_requirements`).
:returns: The requirements, by ID.
"""
return self._requirements
[docs]
def AddRequirement(self, requirement: Requirement) -> None:
"""
Relate this item to a requirement it specifies: the item lists the requirement, and the requirement lists the item.
:param requirement: The requirement.
:raises ValueError: If parameter ``requirement`` is ``None``.
:raises TypeError: If parameter ``requirement`` isn't of type :class:`Requirement`.
:raises NotInSameSpecificationError: If parameter ``requirement`` isn't part of the item's specification.
:raises DuplicateRequirementError: If the item specifies the requirement already.
"""
if requirement is None:
raise ValueError("Parameter 'requirement' is None.")
elif not isinstance(requirement, Requirement):
ex = TypeError("Parameter 'requirement' is not of type 'Requirement'.")
ex.add_note(f"Got type '{getFullyQualifiedName(requirement)}'.")
raise ex
elif self._root is None or requirement._root is not self._root:
ex = NotInSameSpecificationError("Parameter 'requirement' isn't part of the item's specification.")
ex.add_note(f"Got requirement '{requirement._id}'.")
raise ex
elif requirement._id in self._requirements:
raise DuplicateRequirementError(
f"Specification item '{self._id}' specifies requirement '{requirement._id}' already."
)
self._requirements[requirement._id] = requirement
requirement._specificationItems[self._id] = self
SpecificationItem._PARENT_TYPE = (SpecificationItem, RequirementSpecification)
SpecificationItem._DUPLICATE_ERROR = DuplicateSpecificationItemError
[docs]
@export
class LinkKind(Enum):
"""
The relationship a link states: the source item *<kind>* the destination item.
A link connects items of the same or of different layers, e.g. an FPGA firmware requirement derived from an electrical
one. Which specification item specifies which requirement, isn't a link, but the relation of
:attr:`SpecificationItem.Requirements` and :attr:`Requirement.SpecificationItems`.
"""
Refines = 1 #: The source states the destination in more detail, outside the item hierarchy.
DerivesFrom = 2 #: The source is derived from the destination, e.g. from a higher layer.
CounterpartOf = 3 #: The source is the destination's counterpart in another layer.
DependsOn = 4 #: The source can only be met, if the destination is met.
ConflictsWith = 5 #: The source and the destination can't both be met.
Duplicates = 6 #: The source states the same as the destination.
Replaces = 7 #: The source replaces the destination, which is obsolete.
RelatesTo = 8 #: Any other relationship.
[docs]
@export
class Link(KeyValuePairsMixin, metaclass=ExtendedType, slots=True):
"""
A link from an item - its source - to another item of the same specification - its destination -, and the
relationship it states.
A link connects two items of the item hierarchy; it is no element of the hierarchy and has no parent. The source
lists it in :attr:`~BaseItem.OutboundLinks`, the destination in :attr:`~BaseItem.InboundLinks`.
"""
_source: BaseItem #: The item the link starts at.
_destination: BaseItem #: The item the link points to.
_kind: LinkKind #: The relationship the link states.
[docs]
def __init__(
self,
source: BaseItem,
destination: BaseItem,
kind: LinkKind,
*,
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
) -> None:
"""
Initializes a link, and adds it to its source and its destination.
:param source: The item the link starts at.
:param destination: The item the link points to.
:param kind: The relationship the link states.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:raises ValueError: If parameter ``source`` is ``None``.
:raises TypeError: If parameter ``source`` isn't of type :class:`BaseItem`.
:raises NotInSameSpecificationError: If parameter ``source`` isn't part of a specification.
:raises ValueError: If parameter ``destination`` is ``None``.
:raises TypeError: If parameter ``destination`` isn't of type :class:`BaseItem`.
:raises ValueError: If parameter ``destination`` is the source.
:raises NotInSameSpecificationError: If parameter ``destination`` isn't part of the source's specification.
:raises ValueError: If parameter ``kind`` is ``None``.
:raises TypeError: If parameter ``kind`` isn't of type :class:`LinkKind`.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises DuplicateLinkError: If the source has a link of this kind to this destination already.
"""
super().__init__(keyValuePairs)
if source is None:
raise ValueError("Parameter 'source' is None.")
elif not isinstance(source, BaseItem):
ex = TypeError("Parameter 'source' is not of type 'BaseItem'.")
ex.add_note(f"Got type '{getFullyQualifiedName(source)}'.")
raise ex
elif source._root is None:
ex = NotInSameSpecificationError("Parameter 'source' isn't part of a specification.")
ex.add_note(f"Got item '{source._id}'.")
raise ex
if destination is None:
raise ValueError("Parameter 'destination' is None.")
elif not isinstance(destination, BaseItem):
ex = TypeError("Parameter 'destination' is not of type 'BaseItem'.")
ex.add_note(f"Got type '{getFullyQualifiedName(destination)}'.")
raise ex
elif destination is source:
ex = ValueError("Parameter 'destination' is the source.")
ex.add_note(f"Got item '{destination._id}'.")
raise ex
elif destination._root is not source._root:
ex = NotInSameSpecificationError("Parameter 'destination' isn't part of the source's specification.")
ex.add_note(f"Got item '{destination._id}'.")
raise ex
if kind is None:
raise ValueError("Parameter 'kind' is None.")
elif not isinstance(kind, LinkKind):
ex = TypeError("Parameter 'kind' is not of type 'LinkKind'.")
ex.add_note(f"Got type '{getFullyQualifiedName(kind)}'.")
raise ex
for link in source._outboundLinks:
if link._destination is destination and link._kind is kind:
ex = DuplicateLinkError(f"{getTypeName(source)} '{source._id}' has a '{kind.name}' link already.")
ex.add_note(f"Got destination '{destination._id}'.")
raise ex
self._source = source
self._destination = destination
self._kind = kind
source._outboundLinks.append(self)
destination._inboundLinks.append(self)
@readonly
def Source(self) -> BaseItem:
"""
Read-only property to access the item the link starts at (:attr:`_source`).
:returns: The source item.
"""
return self._source
@readonly
def Destination(self) -> BaseItem:
"""
Read-only property to access the item the link points to (:attr:`_destination`).
:returns: The destination item.
"""
return self._destination
@readonly
def Kind(self) -> LinkKind:
"""
Read-only property to access the relationship the link states (:attr:`_kind`).
:returns: The link's kind.
"""
return self._kind
[docs]
@export
class EventKind(Enum):
"""
The kind of an event in the life cycle of an item.
"""
Opened = 1 #: The item was opened, e.g. written as a draft.
Modified = 2 #: The item's text or fields were changed.
Reviewed = 3 #: The item was reviewed.
Approved = 4 #: The item was approved: it became final.
Rejected = 5 #: The item was rejected.
Split = 6 #: The item was split; the event names the other items involved.
Merged = 7 #: The item was merged; the event names the other items involved.
Closed = 8 #: The item was closed after its verification, e.g. released.
Reopened = 9 #: The closed item was opened again.
Obsoleted = 10 #: The item became obsolete, e.g. replaced by the items the event names.
# A class with a property named like a class - ``Person`` - can't name that class in the annotation of a field: the
# class body's namespace, where annotations are evaluated, binds the name to the property.
_Person = Person
[docs]
@export
class HistoryEvent(Base):
"""
An event in the life cycle of an item: its kind, its time, the person causing it, and the other items involved.
Its parent is the item, which lists it in :attr:`~BaseItem.History`, in chronological order. A split or a merge names
the other items involved, e.g. the requirements a requirement was split into, or merged with.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] = (BaseItem, ) #: An event is in the history of an item.
_kind: EventKind #: The kind of the event.
_timestamp: datetime #: The time of the event.
_person: Nullable[_Person] #: The person causing the event, or ``None``.
_involved: list[BaseItem] #: The other items involved, in the order given.
_description: str #: The event's description, or ``""``.
[docs]
def __init__(
self,
kind: EventKind,
timestamp: datetime,
*,
person: Nullable[Person] = None,
involved: Nullable[Iterable[BaseItem]] = None,
description: str = "",
keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
parent: Nullable[BaseItem] = None
) -> None:
"""
Initializes a history event, and adds it to the history of its item.
:param kind: The kind of the event.
:param timestamp: The time of the event; without a time zone, it is a local time.
:param person: Optional, the person causing the event. Default: ``None``.
:param involved: Optional, the other items involved. Default: ``None``.
:param description: Optional, the event's description. Default: ``""``.
:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
:param parent: Optional, the item the event happened to. Default: ``None``.
:raises ValueError: If parameter ``kind`` is ``None``.
:raises TypeError: If parameter ``kind`` isn't of type :class:`EventKind`.
:raises ValueError: If parameter ``timestamp`` is ``None``.
:raises TypeError: If parameter ``timestamp`` isn't of type :class:`~datetime.datetime`.
:raises RequirementsError: If parameter ``timestamp`` is earlier than the item's creation or its last
event.
:raises TypeError: If parameter ``person`` isn't of type :class:`~pyEDAA.Reports.Person`.
:raises NotInSameSpecificationError: If parameter ``person`` isn't part of the item's specification.
:raises TypeError: If parameter ``involved`` isn't iterable, or is a single element.
:raises TypeError: If parameter ``involved`` contains an element not of type
:class:`BaseItem`.
:raises NotInSameSpecificationError: If parameter ``involved`` contains an item, which isn't part of the item's
specification.
:raises DuplicateRequirementError: If parameter ``involved`` contains a requirement twice.
:raises DuplicateSpecificationItemError: If parameter ``involved`` contains a specification item twice.
:raises ValueError: If parameter ``involved`` names no item for a split or a merge.
:raises ValueError: If parameter ``description`` is ``None``.
:raises TypeError: If parameter ``description`` isn't of type :class:`str`.
:raises TypeError: If parameter ``keyValuePairs`` isn't a mapping.
:raises TypeError: If parameter ``parent`` isn't of type :class:`BaseItem`.
"""
super().__init__(keyValuePairs=keyValuePairs, parent=parent)
if kind is None:
raise ValueError("Parameter 'kind' is None.")
elif not isinstance(kind, EventKind):
ex = TypeError("Parameter 'kind' is not of type 'EventKind'.")
ex.add_note(f"Got type '{getFullyQualifiedName(kind)}'.")
raise ex
if timestamp is None:
raise ValueError("Parameter 'timestamp' is None.")
elif not isinstance(timestamp, datetime):
ex = TypeError("Parameter 'timestamp' is not of type 'datetime'.")
ex.add_note(f"Got type '{getFullyQualifiedName(timestamp)}'.")
raise ex
if person is not None:
if not isinstance(person, Person):
ex = TypeError("Parameter 'person' is not of type 'Person'.")
ex.add_note(f"Got type '{getFullyQualifiedName(person)}'.")
raise ex
elif self._root is None or self._root._persons.get(person._userID) is not person:
ex = NotInSameSpecificationError("Parameter 'person' isn't part of the item's specification.")
ex.add_note(f"Got person '{person._userID}'.")
raise ex
self._involved = involvedList = []
if involved is not None:
if not isinstance(involved, Iterable):
ex = TypeError("Parameter 'involved' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(involved)}'.")
raise ex
elif isinstance(involved, KeyValuePairsMixin):
ex = TypeError("Parameter 'involved' is a single element, not an iterable of elements.")
ex.add_note(f"Got type '{getFullyQualifiedName(involved)}'.")
raise ex
for item in involved:
if not isinstance(item, BaseItem):
ex = TypeError("Parameter 'involved' contains an element not of type 'BaseItem'.")
ex.add_note(f"Got type '{getFullyQualifiedName(item)}'.")
raise ex
elif self._root is None or item._root is not self._root:
ex = NotInSameSpecificationError(
"Parameter 'involved' contains an item not part of the item's specification."
)
ex.add_note(f"Got item '{item._id}'.")
raise ex
elif item in self._involved:
ex = item._DUPLICATE_ERROR("Parameter 'involved' contains an item twice.")
ex.add_note(f"Got item '{item._id}'.")
raise ex
involvedList.append(item)
if len(self._involved) == 0 and kind in (EventKind.Split, EventKind.Merged):
raise ValueError(f"Parameter 'involved' names no item for a '{kind.name}' event.")
if description is None:
raise ValueError("Parameter 'description' is None.")
elif not isinstance(description, str):
ex = TypeError("Parameter 'description' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(description)}'.")
raise ex
self._kind = kind
self._timestamp = timestamp
self._person = person
self._description = description
if parent is not None:
parent._AddElement(self)
@readonly
def Kind(self) -> EventKind:
"""
Read-only property to access the kind of the event (:attr:`_kind`).
:returns: The event's kind.
"""
return self._kind
@readonly
def Timestamp(self) -> datetime:
"""
Read-only property to access the time of the event (:attr:`_timestamp`).
:returns: The time; without a time zone, it is a local time.
"""
return self._timestamp
@readonly
def Person(self) -> Nullable[Person]:
"""
Read-only property to access the person causing the event (:attr:`_person`).
:returns: The person, or ``None``.
"""
return self._person
@readonly
def Involved(self) -> list[BaseItem]:
"""
Read-only property to access the other items involved in the event (:attr:`_involved`).
:returns: The items, in the order given.
"""
return self._involved
@readonly
def Description(self) -> str:
"""
Read-only property to access the event's description (:attr:`_description`).
:returns: The description, or ``""``.
"""
return self._description