API Reference: EntityUri

API Reference: EntityUri#

Complete reference for entity URI classes.

class bfabric.entities.core.uri.EntityUri(uri: str | EntityUri)#

Bases: str

B-Fabric entity URI with validation and component parsing.

URIs follow the pattern: https://instance/bfabric/{entity_type}/show.html?id={id}

Example:
>>> uri = EntityUri("https://fgcz-bfabric.uzh.ch/bfabric/sample/show.html?id=123")
>>> uri.components.entity_type
'sample'
>>> uri.components.entity_id
123
property components: EntityUriComponents#

Access parsed URI components.

classmethod from_components(bfabric_instance: str, entity_type: str, entity_id: int) → EntityUri#

Create EntityUri from individual components.

Args:

bfabric_instance: B-Fabric instance URL (e.g., “https://fgcz-bfabric.uzh.ch/bfabric/”) entity_type: Entity type name (e.g., “sample”, “project”) entity_id: Numeric ID of the entity

Returns:

Validated EntityUri string

class bfabric.entities.core.uri.EntityUriComponents(*, bfabric_instance: ~pydantic.networks.HttpUrl, entity_type: ~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[a-z]+$)], entity_id: ~typing.Annotated[int, ~annotated_types.Gt(gt=0)])#

Bases: BaseModel

Parsed components of an EntityUri.

Attributes:

bfabric_instance: B-Fabric instance URL entity_type: Entity type name (lowercase letters only) entity_id: Numeric entity ID (must be positive)

as_uri() → EntityUri#

Convert components back to EntityUri string.

model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class bfabric.entities.core.uri.GroupedUris(*, groups: dict[GroupKey, list[EntityUri]] = {})#

Bases: BaseModel

Groups EntityUris by B-Fabric instance and entity type for batch processing.

Used internally by EntityReader to batch API calls efficiently.

class GroupKey(*, bfabric_instance: str, entity_type: str)#

Bases: BaseModel

Grouping key for EntityUris.

model_config = {'frozen': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod from_uris(uris: list[EntityUri]) → GroupedUris#

Create GroupedUris from a list of EntityUris.

Args:

uris: List of EntityUri objects to group

Returns:

GroupedUris with URIs grouped by instance and type

items() → Iterator[tuple[GroupKey, list[EntityUri]]]#

Iterate over grouped URIs.

model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Overview#

The EntityUri system provides validated entity identifiers that work across B-Fabric instances.

URI Format#

B-Fabric entity URIs follow this pattern:

https://<instance>/bfabric/<entity_type>/show.html?id=<id>

Example: https://fgcz-bfabric.uzh.ch/bfabric/sample/show.html?id=123

Key Features#

  • Validation: Automatic validation of URI format and structure

  • Parsing: Extract entity type and ID from URIs

  • Construction: Create URIs from components

  • Cross-instance: Reference entities from any B-Fabric instance

Usage Examples#

Parse Existing URI#

from bfabric.entities.core.uri import EntityUri

# Parse URI from string
uri = EntityUri("https://fgcz-bfabric.uzh.ch/bfabric/sample/show.html?id=123")

# Access components
print(uri.components.bfabric_instance)  # "https://fgcz-bfabric.uzh.ch/bfabric/"
print(uri.components.entity_type)  # "sample"
print(uri.components.entity_id)  # 123

Construct URI from Components#

from bfabric.entities.core.uri import EntityUri

# Build URI from parts
uri = EntityUri.from_components(
    bfabric_instance="https://fgcz-bfabric.uzh.ch/bfabric/",
    entity_type="sample",
    entity_id=123,
)
print(uri)  # "https://fgcz-bfabric.uzh.ch/bfabric/sample/show.html?id=123"

With EntityReader#

from bfabric import Bfabric

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

# Read by URI
uri = EntityUri("https://fgcz-bfabric.uzh.ch/bfabric/sample/show.html?id=123")
sample = reader.read_uri(uri)

Read Multiple URIs#

from bfabric.entities.core.uri import EntityUri

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)

URI Format Details#

Component Breakdown#

Component

Description

Example

bfabric_instance

Base URL of B-Fabric instance

https://fgcz-bfabric.uzh.ch/bfabric/

entity_type

Entity name (lowercase)

sample, project, workunit

entity_id

Numeric entity ID

123

Supported Entity Types#

All lowercase B-Fabric entity types are valid:

  • sample, project, order, container

  • workunit, dataset, resource

  • application, executable, parameter

  • workflow, workflowstep

  • And all other B-Fabric entity types

Error Handling#

from bfabric.entities.core.uri import EntityUri

try:
    # Invalid URI
    uri = EntityUri("https://example.com/invalid")
except ValueError as e:
    print(f"Invalid URI: {e}")

See Also#

Contents