API Reference: EntityReader#

Complete reference for the EntityReader class.

class bfabric.entities.core.entity_reader.EntityReader(client: Bfabric, *, _private: bool)#

Bases: object

Reads entities from B-Fabric by URI or ID, respecting the cache stack if configured.

This class provides multiple methods to read entities from B-Fabric: - By URI(s): read_uri(), read_uris() - By ID(s): read_id(), read_ids() - By query criteria: query()

All methods use the cache stack when available to minimize API calls.

classmethod for_client(client: Bfabric) → EntityReader#: Create an EntityReader for a single B-Fabric client.

query(entity_type: str, obj: ApiRequestObjectType, bfabric_instance: str | None = None, max_results: int | None = 100) → dict[EntityUri, Entity | None]#

Query entities by search criteria and return them as Entity objects.

Combines client.read() with automatic entity instantiation and caching.

Args:: entity_type: B-Fabric entity type to query obj: Dictionary of search criteria (e.g., {"name": "MySample"}) bfabric_instance: B-Fabric instance URL (defaults to client’s configured instance) max_results: Maximum number of results to return (default: 100, None for all)
Returns:: Dictionary mapping entity URIs to their objects

read_id(entity_type: str, entity_id: int, bfabric_instance: str | None = None, *, expected_type: type[EntityT] = <class 'bfabric.entities.core.entity.Entity'>) → EntityT | None#

Read a single entity by its type and ID.

Args:: entity_type: B-Fabric entity type (e.g., “sample”, “project”) entity_id: Numeric ID of entity bfabric_instance: B-Fabric instance URL (defaults to client’s configured instance) expected_type: Entity class to validate and cast the result
Returns:: Entity object or None if not found
Raises:: ValueError: If instance doesn’t match the client’s configuration

read_ids(entity_type: str, entity_ids: list[int], bfabric_instance: str | None = None, *, expected_type: type[~bfabric.entities.core.entity_reader.EntityT] = <class 'bfabric.entities.core.entity.Entity'>) → dict[EntityUri, EntityT | None]#

Read multiple entities of the same type by their IDs.

Args:: entity_type: B-Fabric entity type (e.g., “sample”) entity_ids: List of numeric IDs bfabric_instance: B-Fabric instance URL (defaults to client’s configured instance) expected_type: Entity class to validate and cast all results
Returns:: Dictionary mapping entity URIs to their objects (or None if not found)

read_uri(uri: EntityUri | str, *, expected_type: type[EntityT] = <class 'bfabric.entities.core.entity.Entity'>) → EntityT | None#

Read a single entity by its B-Fabric URI.

Args:: uri: B-Fabric URI of the entity (e.g., “https://…/sample/show.html?id=123”) expected_type: Entity class (e.g., Sample) for type validation and casting
Returns:: Entity object or None if not found
Raises:: ValueError: If URI is invalid or from a different B-Fabric instance TypeError: If entity exists but doesn’t match expected_type

read_uris(uris: ~collections.abc.Iterable[~bfabric.entities.core.uri.EntityUri | str], *, expected_type: type[~bfabric.entities.core.entity_reader.EntityT] = <class 'bfabric.entities.core.entity.Entity'>) → dict[EntityUri, EntityT | None]#

Read multiple entities by their URIs efficiently.

Entities are grouped by type and retrieved in batches to minimize API calls. Uses the cache stack if configured.

Args:: uris: Iterable of B-Fabric URIs (can be different entity types) expected_type: Entity class to validate and cast all results
Returns:: Dictionary mapping each input URI to its entity object (or None if not found)
Raises:: ValueError: If any URI is from a different B-Fabric instance

Overview#

The EntityReader provides methods to read B-Fabric entities as typed objects with caching support.

Key Features#

URI Support: Read entities by their B-Fabric URIs
Batch Operations: Efficiently read multiple entities
Caching: Automatic caching with cache_entities() context
Type Safety: Use expected_type parameter for type checking
Query Support: Search entities by criteria

Quick Examples#

Read by URI#

from bfabric import Bfabric

client = Bfabric.connect()
reader = client.reader

# Single entity
uri = "https://fgcz-bfabric.uzh.ch/bfabric/sample/show.html?id=123"
sample = reader.read_uri(uri)

# Multiple entities (mixed types)
uris = [
    "https://fgcz-bfabric.uzh.ch/bfabric/sample/show.html?id=123",
    "https://fgcz-bfabric.uzh.ch/bfabric/project/show.html?id=456",
]
entities = reader.read_uris(uris)

Read by ID#

# Single entity
sample = reader.read_id(entity_type="sample", entity_id=123)

# Multiple entities of same type
samples = reader.read_ids(entity_type="sample", entity_ids=[123, 456, 789])

Query#

# Search by criteria
samples = reader.query(
    entity_type="sample",
    obj={"name": "MySample", "projectid": 123},
    max_results=100,
)

With Type Safety#

from bfabric.entities import Sample

# Read with expected type
sample = reader.read_id(
    entity_type="sample",
    entity_id=123,
    expected_type=Sample,  # Type-safe!
)

# IDE knows about Sample methods
print(sample.container)  # Autocomplete available

With Caching#

from bfabric.entities.cache.context import cache_entities

# Cache entities for performance
with cache_entities(["sample", "project"], max_size=1000):
    # First access fetches from API
    project1 = reader.read_id(entity_type="project", entity_id=1)

    # Second access uses cache (no API call)
    project2 = reader.read_id(entity_type="project", entity_id=1)

    assert project1 is project2  # Same object

API Reference: EntityReader

Contents