Bfabric Client API Reference

Bfabric Client API Reference#

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

API Overview#

The Bfabric class provides methods for:

Category

Methods

Client Creation

connect(), connect_oauth(), connect_pkce(), connect_device_code(), connect_pat(), 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, *, _credential_provider: OAuthCredentialProvider | None = None)#

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.

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.

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)

For OAuth-based Usage#

classmethod Bfabric.connect_oauth(client_id: str, client_secret: str, base_url: str, *, scope: str, token_cache_path: Path | None = None) → Bfabric#

Returns a new Bfabric instance that authenticates via OAuth 2.0 client credentials.

Tokens are fetched and refreshed automatically. Every SOAP call gets a fresh BfabricAuth(login="__oauth__", password=<jwt>) via the credential provider.

Parameters:

  • client_id – OAuth client ID (from register_client or admin setup)

  • client_secret – OAuth client secret

  • base_url – B-Fabric instance URL (e.g. https://bfabric.example.com/bfabric)

  • scope – OAuth scope

  • token_cache_path – Optional path to cache tokens on disk (survives restarts)

classmethod Bfabric.connect_pkce(base_url: str, *, client_id: str, scope: str, port: int = 0, open_browser: bool = True, timeout: float = 120.0, token_cache_path: Path | None = None) → Bfabric#

Returns a new Bfabric instance after interactive browser-based PKCE login.

Opens the user’s browser to the B-Fabric authorization page. After the user logs in, tokens are exchanged automatically and the returned client uses OAuthCredentialProvider for transparent refresh.

Parameters:

  • base_url – B-Fabric instance URL (e.g. https://bfabric.example.com/bfabric)

  • client_id – OAuth client ID

  • scope – OAuth scope

  • port – Local port for the callback server (0 = auto-assign)

  • open_browser – Whether to open the authorization URL in the browser

  • timeout – Seconds to wait for the user to complete login

  • token_cache_path – Optional path to cache tokens on disk (survives restarts)

classmethod Bfabric.connect_device_code(base_url: str, *, client_id: str, scope: str, timeout: float = 600.0, token_cache_path: Path | None = None) → Bfabric#

Returns a new Bfabric instance after device code authorization (RFC 8628).

Displays a user code and verification URI on stderr. The user visits the URI, enters the code, and authorizes the device. The returned client uses OAuthCredentialProvider for transparent token refresh.

This flow is suitable for headless environments (SSH, containers) where a localhost redirect is not feasible.

Parameters:

  • base_url – B-Fabric instance URL (e.g. https://bfabric.example.com/bfabric)

  • client_id – OAuth client ID

  • scope – OAuth scope

  • timeout – Seconds to wait for the user to authorize

  • token_cache_path – Optional path to cache tokens on disk (survives restarts)

classmethod Bfabric.connect_pat(base_url: str, pat: str | SecretStr) → Bfabric#

Returns a new Bfabric instance that authenticates via a Personal Access Token.

PATs are opaque bearer tokens issued by B-Fabric. Unlike JWTs they cannot be verified locally, but they also don’t need to be — the SOAP API accepts them directly. There is no automatic refresh; if the token expires a new one must be obtained.

Parameters:

  • base_url – B-Fabric instance URL (e.g. https://bfabric.example.com/bfabric)

  • pat – Personal Access Token (string or SecretStr)

Deprecated Methods#

classmethod Bfabric.from_config(config_env: str | None = None, config_path: str | None = None, auth: BfabricAuth | Literal['config'] | None = 'config', engine: BfabricAPIEngineType | None = None) → Bfabric#

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 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.

async classmethod Bfabric.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 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, 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#

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

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.

When a credential provider is present (OAuth), it returns a fresh BfabricAuth with the current access token.

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.

When a credential provider is active, it is temporarily disabled so the explicit auth takes priority.

EntityReader Access#

Bfabric.reader#

Returns an EntityReader for this client.