Bfabric Client API Reference

Bfabric Client API Reference#

Complete API reference for the Bfabric client class, automatically generated from source code documentation.

Quick Links#

Creating a Client - Step-by-step guides for different use cases
Configuration - Config file setup and options
Quick Start - 5-minute tutorial

API Overview#

The Bfabric class provides methods for:

Category	Methods
Client Creation	`connect()`, `connect_token()`, `from_token_data()`
Read Operations	`read()`, `exists()`
Write Operations	`save()`, `delete()`, `upload_resource()`
Configuration	`config`, `auth`, `config_data` properties
Entity Operations	`reader` property for `EntityReader`
Context Management	`with_auth()`

Bfabric Class#

class bfabric.Bfabric(config_data: ConfigData)#

Bases: object

Bfabric client class, providing general functionality for interaction with the B-Fabric API.

Use Bfabric.connect() or Bfabric.connect_webapp to create a new instance, and check out their docstrings for more details on how to use.

property auth: BfabricAuth#: Returns the auth object. :raises ValueError: If authentication is not available

property config: BfabricClientConfig#: Returns the config object.

property config_data: ConfigData#: Returns the config data object.

classmethod connect(*, config_file_path: Path | str = PosixPath('~/.bfabricpy.yml'), config_file_env: str | Literal['default'] | None = 'default', include_auth: bool = True) → Bfabric#

Returns a new Bfabric instance.

If a BFABRICPY_CONFIG_OVERRIDE environment variable is set, all configuration will originate from it.

If it’s not present, and config_file_env is not None, your config file (~/.bfabricpy.yml by default) will be used instead. If config_file_env is “default”, then if available the environment according to env variable BFABRICPY_CONFIG_ENV will be used, otherwise the default environment in the config file will be used. Otherwise, config_file_env specifies the name of the environment.

Parameters:

config_file_path – a non-standard configuration file to use, if config file is selected as a config source
config_file_env – name of environment to use, if config file is selected as a config source. if “default” is specified, the default environment will be used. if None is specified, the file will not be used as a config source.
include_auth – whether auth information should be included (for servers, setting this to False is useful)

classmethod connect_token(token: str | SecretStr, settings: TokenValidationSettingsProtocol) → tuple[Bfabric, TokenData]#

Returns a new Bfabric instance configured with the provided token.

Calls connect_token_async, if you are in a coroutine then you have to call connect_token_async instead.

async classmethod connect_token_async(token: str | SecretStr, settings: TokenValidationSettingsProtocol) → tuple[Bfabric, TokenData]#

Returns a new Bfabric instance configured with the provided token.

Settings needs to be configured to allow the desired B-Fabric instances.

classmethod connect_webapp(token: str, *, validation_instance_url: str = 'https://fgcz-bfabric.uzh.ch/bfabric/', config_file_path: None = None, config_file_env: None = None) → tuple[Bfabric, TokenData]#

Returns a new Bfabric instance, configured with the user configuration file and the provided token.

Parameters:

token – the token to use for authentication
validation_instance_url – the URL of the B-Fabric instance to use for token validation, in principle validation can be performed on any B-Fabric instance as the token describes the caller too

Returns:

a tuple of the Bfabric instance and the token data

delete(endpoint: str, id: int | list[int], check: bool = True) → ResultContainer#: Deletes the object with the specified ID from the specified endpoint. :param endpoint: the endpoint to delete from, e.g. “sample” :param id: the ID of the object to delete :param check: whether to raise an error if the response is not successful :return a ResultContainer describing the deleted object if successful

exists(endpoint: str, key: str, value: int | str, query: ApiRequestObjectType | None = None, check: bool = True) → bool#: Returns whether an object with the specified key-value pair exists in the specified endpoint. Further conditions can be specified in the query. :param endpoint: the endpoint to check, e.g. “sample” :param key: the key to check, e.g. “id” :param value: the value to check, e.g. 123 :param query: additional query conditions (optional) :param check: whether to raise an error if the response is not successful

Returns a new Bfabric instance, configured with the user configuration file. If the config_env is specified then it will be used, if it is not specified the default environment will be determined by checking the following in order (picking the first one that is found): - The BFABRICPY_CONFIG_ENV environment variable - The default_config field in the config file “GENERAL” section

Parameters:

config_env – Configuration environment to use. If not given, it is deduced as described above.
config_path – Path to the config file, in case it is different from default
auth – Authentication to use. If “config” is given, the authentication will be read from the config file. If it is set to None, no authentication will be used.
engine – Engine to use for the API.

classmethod from_token_data(token_data: TokenData) → Bfabric#: Creates a new Bfabric instance from token data.

read(endpoint: str, obj: ApiRequestObjectType, max_results: int | None = 100, offset: int = 0, check: bool = True, return_id_only: bool = False) → ResultContainer#

Reads from the specified endpoint matching all specified attributes in obj.

By setting max_results it is possible to change the number of results that are returned.

Parameters:

endpoint – The B-Fabric endpoint to query (e.g., “sample”, “project”, “workunit”).
obj – A dictionary containing the query criteria. For every field, multiple possible values can be provided as a list (treated as OR). Multiple fields are treated as AND.
max_results – Maximum number of results to return. The client will automatically handle pagination to reach this limit. Set to None to retrieve all available results. Note: results are fetched in blocks of 100.
offset – Number of results to skip before starting to return results.
check – If True (default), raises a RuntimeError if the query fails.
return_id_only – If True, only returns entity IDs instead of full data (faster).

Returns:

A ResultContainer containing the query results.

property reader: EntityReader#: Returns an EntityReader for this client.

save(endpoint: str, obj: ApiRequestObjectType | list[ApiRequestObjectType], check: bool = True, method: str = 'save') → ResultContainer#

Saves the provided object to the specified endpoint. :param endpoint: the endpoint to save to, e.g. “sample” :param obj: the object(s) to save :param check: whether to raise an error if the response is not successful :param method: the method to use for saving, generally “save”, but in some cases e.g. “update” is more appropriate to be used instead.

:return a ResultContainer describing the saved object if successful

upload_resource(resource_name: str, content: bytes, workunit_id: int, check: bool = True) → ResultContainer#: Uploads a resource to B-Fabric, only intended for relatively small files that will be tracked by B-Fabric and not one of the dedicated experimental data stores. :param resource_name: the name of the resource to create (the same name can only exist once per workunit) :param content: the content of the resource as bytes :param workunit_id: the workunit ID to which the resource belongs :param check: whether to check for errors in the response

with_auth(auth: BfabricAuth) → Generator[None, None, None]#: Context manager that temporarily (within the scope of the context) sets the authentication for the Bfabric object to the provided value. This is useful when authenticating multiple users, to avoid accidental use of the wrong credentials.

Client Creation Methods#

For Interactive/Scripted Usage#

classmethod Bfabric.connect(*, config_file_path: Path | str = PosixPath('~/.bfabricpy.yml'), config_file_env: str | Literal['default'] | None = 'default', include_auth: bool = True) → Bfabric#

Returns a new Bfabric instance.

If a BFABRICPY_CONFIG_OVERRIDE environment variable is set, all configuration will originate from it.

Parameters:

config_file_path – a non-standard configuration file to use, if config file is selected as a config source
config_file_env – name of environment to use, if config file is selected as a config source. if “default” is specified, the default environment will be used. if None is specified, the file will not be used as a config source.
include_auth – whether auth information should be included (for servers, setting this to False is useful)

Deprecated Methods#

Parameters:

config_env – Configuration environment to use. If not given, it is deduced as described above.
config_path – Path to the config file, in case it is different from default
auth – Authentication to use. If “config” is given, the authentication will be read from the config file. If it is set to None, no authentication will be used.
engine – Engine to use for the API.

classmethod Bfabric.connect_webapp(token: str, *, validation_instance_url: str = 'https://fgcz-bfabric.uzh.ch/bfabric/', config_file_path: None = None, config_file_env: None = None) → tuple[Bfabric, TokenData]#

Returns a new Bfabric instance, configured with the user configuration file and the provided token.

Parameters:

token – the token to use for authentication
validation_instance_url – the URL of the B-Fabric instance to use for token validation, in principle validation can be performed on any B-Fabric instance as the token describes the caller too

Returns:

a tuple of the Bfabric instance and the token data

For Server/Webapp Usage#

classmethod Bfabric.connect_token(token: str | SecretStr, settings: TokenValidationSettingsProtocol) → tuple[Bfabric, TokenData]#

Returns a new Bfabric instance configured with the provided token.

Calls connect_token_async, if you are in a coroutine then you have to call connect_token_async instead.

classmethod Bfabric.from_token_data(token_data: TokenData) → Bfabric#: Creates a new Bfabric instance from token data.

Read Operations#

Bfabric.read(endpoint: str, obj: ApiRequestObjectType, max_results: int | None = 100, offset: int = 0, check: bool = True, return_id_only: bool = False) → ResultContainer#

Reads from the specified endpoint matching all specified attributes in obj.

By setting max_results it is possible to change the number of results that are returned.

Parameters:

endpoint – The B-Fabric endpoint to query (e.g., “sample”, “project”, “workunit”).
obj – A dictionary containing the query criteria. For every field, multiple possible values can be provided as a list (treated as OR). Multiple fields are treated as AND.
max_results – Maximum number of results to return. The client will automatically handle pagination to reach this limit. Set to None to retrieve all available results. Note: results are fetched in blocks of 100.
offset – Number of results to skip before starting to return results.
check – If True (default), raises a RuntimeError if the query fails.
return_id_only – If True, only returns entity IDs instead of full data (faster).

Returns:

A ResultContainer containing the query results.

Bfabric.exists(endpoint: str, key: str, value: int | str, query: ApiRequestObjectType | None = None, check: bool = True) → bool#: Returns whether an object with the specified key-value pair exists in the specified endpoint. Further conditions can be specified in the query. :param endpoint: the endpoint to check, e.g. “sample” :param key: the key to check, e.g. “id” :param value: the value to check, e.g. 123 :param query: additional query conditions (optional) :param check: whether to raise an error if the response is not successful

Write Operations#

Bfabric.save(endpoint: str, obj: ApiRequestObjectType | list[ApiRequestObjectType], check: bool = True, method: str = 'save') → ResultContainer#

:return a ResultContainer describing the saved object if successful

Bfabric.delete(endpoint: str, id: int | list[int], check: bool = True) → ResultContainer#: Deletes the object with the specified ID from the specified endpoint. :param endpoint: the endpoint to delete from, e.g. “sample” :param id: the ID of the object to delete :param check: whether to raise an error if the response is not successful :return a ResultContainer describing the deleted object if successful

Bfabric.upload_resource(resource_name: str, content: bytes, workunit_id: int, check: bool = True) → ResultContainer#: Uploads a resource to B-Fabric, only intended for relatively small files that will be tracked by B-Fabric and not one of the dedicated experimental data stores. :param resource_name: the name of the resource to create (the same name can only exist once per workunit) :param content: the content of the resource as bytes :param workunit_id: the workunit ID to which the resource belongs :param check: whether to check for errors in the response

Configuration and Authentication#

Bfabric.config#: Returns the config object.

Bfabric.auth#: Returns the auth object. :raises ValueError: If authentication is not available

Bfabric.config_data#: Returns the config data object.

Context Management#

Bfabric.with_auth(auth: BfabricAuth) → Generator[None, None, None]#: Context manager that temporarily (within the scope of the context) sets the authentication for the Bfabric object to the provided value. This is useful when authenticating multiple users, to avoid accidental use of the wrong credentials.

EntityReader Access#

Bfabric.reader#: Returns an EntityReader for this client.

Bfabric Client API Reference

Contents

Bfabric Client API Reference#

Quick Links#

API Overview#

Bfabric Class#

Client Creation Methods#

For Interactive/Scripted Usage#

Deprecated Methods#

For Server/Webapp Usage#

Read Operations#

Write Operations#

Configuration and Authentication#

Context Management#

EntityReader Access#

Related Documentation#