From 2cb669758b249e91d5dfe5d367f3fea3ccdec775 Mon Sep 17 00:00:00 2001 From: Leonardo Schwarz Date: Fri, 9 Aug 2024 14:39:54 +0200 Subject: [PATCH] add initial docs for entities --- docs/entities.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/entities.md diff --git a/docs/entities.md b/docs/entities.md new file mode 100644 index 00000000..10056c30 --- /dev/null +++ b/docs/entities.md @@ -0,0 +1,33 @@ +## High-level `bfabric.entities` API + +The `bfabric.entities` module offers a high-level, **read-only** API for retrieval of entities in the B-Fabric system. + +This API is designed to simplify entity access by providing lazy-loading capabilities for associated entities. Entities within this module can maintain a reference to a B-Fabric client instance, enabling seamless integration and data retrieval. + +### Key Features + +- **Read-Only Access**: This module is strictly for read-only operations. None of the classes or methods should be used to modify the database. +- **Lazy-Loading**: Entities are initialized with basic data as returned by a .read operation on its endpoint. However, associated entities are not loaded until explicitly requested, enhancing performance and reducing unnecessary data processing. +- **Modular Design**: Only include generic functionality within this module. Avoid adding highly specific logic to ensure the module remains maintainable over time. +- **No Circular Imports**: Ensure there are no circular dependencies between entities by deferring imports of other entities inside modules until all relevant modules are processed. + +### Entity + +Each entity has to provide the name of its B-Fabric of its class name as `ENDPOINT`. +An entity is defined uniquely by its `classname` and `id`. + +Entities are initialized with the full result structure obtained from a `read` operation on its particular endpoint. +A `return_id_only` result is generally not supposed to be used to initialize an entity instance and behavior is undefined as of now. +In cases where it makes sense to operate on the ids, it's better to directly call the `Bfabric` client methods. + +Entities can be retrieved with the methods `Entity.find` and `Entity.find_all`, whenever loading multiple entities of the same type the latter should be preferred since it reduces the number of API calls and returns a dictionary mapping entity ID to instance. + +### Relationships + +Custom descriptors are available which are used to represent relationships and enable lazy-loading of data. +Currently the following descriptors are available: + +- `HasOne`: Defines a one-to-one relationship between entities. +- `HasMany`: Defines a one-to-many relationship between entities. + +Both support setting an additional argument `optional=True` which will ensure `None` (in the case of `HasOne`) and an empty collection (in the case of `HasMany`) are returned when there is no field at all in the result returned by the API.