benchling_sdk.benchling module

Provides the Benchling class, which is the main interface for accessing Benchling’s API functionality.

class Benchling

Bases: object

A facade for interactions with the Benchling platform.

Methods are organized into namespaces which generally correspond to Resources in Benchling’s public API doc.

See https://benchling.com/api/reference

__init__(url: str, auth_method: benchling_api_client.v2.benchling_client.AuthorizationMethod, base_path: Optional[str] = _DEFAULT_BASE_PATH, retry_strategy: Optional[RetryStrategy] = _DEFAULT_RETRY_STRATEGY, client_decorator: Optional[BenchlingApiClientDecorator] = None, httpx_client: Optional[httpx.Client] = None)

Initialize Benchling.

Parameters
  • url – A server URL (host and optional port) including scheme such as https://benchling.com

  • auth_method – A provider of an HTTP Authorization header for usage with the Benchling API. Pass an instance of benchling_sdk.auth.api_key_auth.ApiKeyAuth with a valid Benchling API token for authentication and authorization through HTTP Basic Authentication, or a client_id and client_secret pair with benchling_sdk.auth.client_credentials_oauth2.ClientCredentialsOAuth2 for authentication and authorization through OAuth2 client_credentials Bearer token flow.

  • base_path – If provided, will append to the host. Otherwise, assumes the V2 API. This is a workaround until the generated client supports the servers block. See BNCH-15422

  • retry_strategy – An optional retry strategy for retrying HTTP calls on failure. Setting to None will disable retries

  • client_decorator – An optional function that accepts a BenchlingApiClient configured with default settings and mutates its state as desired

  • httpx_client – An optional httpx Client which will be used to execute HTTP calls. The Client can be used to modify the behavior of the HTTP calls made to Benchling through means such as adding proxies and certificates or introducing retry logic for transport-level errors.

property aa_sequences: AaSequenceService

AA Sequences.

AA Sequences are the working units of cells that make everything run (they help make structures, catalyze reactions and allow for signaling - a kind of internal cell communication). On Benchling, these are comprised of a string of amino acids and collections of other attributes, such as annotations.

See https://benchling.com/api/reference#/AA%20Sequences

property api: ApiService

Make custom API calls with the underlying BenchlingApiClient.

A common use case for this is making calls to API endpoints which may not yet be supported in the current SDK release. It’s capable of making more “generic” calls utilizing our authorization scheme, as well as supporting some simple serialization and deserialization for custom models.

property apps: AppService

Apps.

Apps provide a framework for you to customize your teams’ experiences on Benchling with custom applications.

See https://benchling.com/api/reference#/Apps and https://docs.benchling.com/docs/getting-started-benchling-apps

property assay_results: AssayResultService

Assay Results.

Results represent the output of assays that have been performed. You can customize the schemas of results to fit your needs. Results can link to runs, batches, and other types.

See https://benchling.com/api/reference#/Assay%20Results

property assay_runs: AssayRunService

Assay Runs.

Runs capture the details / parameters of a run that was performed. Results are usually nested under a run.

See https://benchling.com/api/reference#/Assay%20Runs

property blobs: BlobService

Blobs.

Blobs are opaque files that can be linked to other items in Benchling, like assay runs or results. For example, you can upload a blob, then upload an assay result that links to that blob by ID. The blob will then appear as part of the assay result in the Benchling web UI.

See https://benchling.com/api/reference#/Blobs

property boxes: BoxService

Boxes.

Boxes are a structured storage type, consisting of a grid of positions that can each hold one container. Unlike locations, there are a maximum number of containers that a box can hold (one per position).

Boxes are all associated with schemas, which define the type of the box (e.g. “10x10 Cryo Box”) along with the fields that are tracked and the dimensions of the box.

Like all storage, every Box has a barcode that is unique across the registry.

See https://benchling.com/api/reference#/Boxes

property client: benchling_api_client.v2.client.Client

Provide access to the underlying generated Benchling Client.

Should generally not be used except for advanced use cases which may not be well supported by the SDK itself.

property containers: ContainerService

Containers.

Containers are the backbone of sample management in Benchling. They represent physical containers, such as tubes or wells, that hold quantities of biological samples (represented by the batches inside the container). The container itself tracks its total volume, and the concentration of every batch inside of it.

Containers are all associated with schemas, which define the type of the container (e.g. “Tube”) along with the fields that are tracked.

Like all storage, every container has a barcode that is unique across the registry.

See https://benchling.com/api/reference#/Containers

property custom_entities: CustomEntityService

Custom Entities.

Benchling supports custom entities for biological entities that are neither sequences or proteins. Custom entities must have an entity schema set and can have both schema fields and custom fields.

See https://benchling.com/api/reference#/Custom%20Entities

property dna_alignments: DnaAlignmentsService

DNA Alignments.

A DNA alignment is a Benchling object representing an alignment of multiple DNA sequences.

See https://benchling.com/api/reference#/DNA%20Alignments

property dna_oligos: DnaOligoService

DNA Oligos.

DNA Oligos are short linear DNA sequences that can be attached as primers to full DNA sequences. Just like other entities, they support schemas, tags, and aliases.

See https://benchling.com/api/reference#/DNA%20Oligos

property dna_sequences: DnaSequenceService

DNA Sequences.

DNA sequences are the bread and butter of the Benchling Molecular Biology suite. On Benchling, these are comprised of a string of nucleotides and collections of other attributes, such as annotations and primers.

See https://benchling.com/api/reference#/DNA%20Sequences

property dropdowns: DropdownService

Dropdowns.

Dropdowns are registry-wide enums. Use dropdowns to standardize on spelling and naming conventions, especially for important metadata like resistance markers.

See https://benchling.com/api/reference#/Dropdowns

property entries: EntryService

Entries.

Entries are rich text documents that allow you to capture all of your experimental data in one place.

See https://benchling.com/api/reference#/Entries

property events: EventService

Events.

The Events system allows external services to subscribe to events that are triggered in Benchling (e.g. plasmid registration, request submission, etc).

See https://benchling.com/api/reference#/Events

property exports: ExportService

Exports.

Export a Notebook Entry.

See https://benchling.com/api/reference#/Exports

property feature_libraries: FeatureLibraryService

Feature Libraries.

Feature Libraries are collections of shared canonical patterns that can be used to generate annotations on matching regions of DNA Sequences or AA Sequences.

See https://benchling.com/api/reference#/Feature%20Libraries

property folders: FolderService

Folders.

Manage folder objects.

See https://benchling.com/api/reference#/Folders

property inventory: InventoryService

Inventory.

Manage inventory wide objects.

See https://benchling.com/api/reference#/Inventory

property lab_automation: LabAutomationService

Lab Automation.

Lab Automation endpoints support integration with lab instruments, and liquid handlers to create samples or results, and capture transfers between containers at scale.

See https://benchling.com/api/reference#/Lab%20Automation

property label_templates: LabelTemplateService

Label Templates.

List label templates.

See https://benchling.com/api/reference#/Label%20Templates

property locations: LocationService

Locations.

Manage locations objects. Like all storage, every Location has a barcode that is unique across the registry.

See https://benchling.com/api/reference#/Locations

property mixtures: MixtureService

Mixtures.

Mixtures are solutions comprised of multiple ingredients where the exact quantities of each ingredient are important to track. Each ingredient is uniquely identified by its component entity.

See https://benchling.com/api/reference#/Mixtures

property molecules: benchling_sdk.services.v2.stable.molecule_service.MoleculeService

Molecules.

Molecules are groups of atoms held together by bonds, representing entities smaller than DNA Sequences and AA Sequences. Just like other entities, they support schemas, tags, and aliases.

See https://benchling.com/api/reference#/Molecules

property nucleotide_alignments: benchling_sdk.services.v2.stable.nucleotide_alignments_service.NucleotideAlignmentsService

Nucleotide Alignments.

A Nucleotide Alignment is a Benchling object representing an alignment of multiple DNA and/or RNA sequences.

See https://benchling.com/api/reference#/Nucleotide%20Alignments

property oligos: OligoService

Oligos.

Oligos are short linear DNA sequences that can be attached as primers to full DNA sequences. Just like other entities, they support schemas, tags, and aliases.

Please migrate to the corresponding DNA Oligos endpoints so that we can support RNA Oligos.

See https://benchling.com/api/reference#/Oligos

property organizations: OrganizationService

Organizations.

View organization objects.

See https://benchling.com/api/reference#/Organizations

property plates: PlateService

Plates.

Plates are a structured storage type, grids of wells that each function like containers. Plates come in two types: a traditional “fixed” type, where the wells cannot move, and a “matrix” type. A matrix plate has similar functionality to a box, where the containers inside can be moved around and removed altogether.

Plates are all associated with schemas, which define the type of the plate (e.g. “96 Well Plate”) along with the fields that are tracked, the dimensions of the plate, and whether or not the plate is a matrix plate or a traditional well plate.

Like all storage, every Plate has a barcode that is unique across the registry.

See https://benchling.com/api/reference#/Plates

property printers: PrinterService

Printers.

List printers.

See https://benchling.com/api/reference#/Printers

property projects: ProjectService

Projects.

Manage project objects.

See https://benchling.com/api/reference#/Projects

property registry: RegistryService

Registry.

Manage registry objects.

See https://benchling.com/api/reference#/Registry

property requests: RequestService

Requests.

Requests allow scientists and teams to collaborate around experimental assays and workflows.

See https://benchling.com/api/reference#/Requests

property rna_oligos: RnaOligoService

RNA Oligos.

RNA Oligos are short linear RNA sequences that can be attached as primers to full DNA sequences. Just like other entities, they support schemas, tags, and aliases.

See https://benchling.com/api/reference#/RNA%20Oligos

property rna_sequences: benchling_sdk.services.v2.stable.rna_sequence_service.RnaSequenceService

RNA Sequences.

Chains of linear, single stranded RNA that support most capabilities and attributes of DNA Sequences.

See https://benchling.com/api/reference#/RNA%20Sequences

property schemas: SchemaService

Schemas.

Schemas represent custom configuration of objects in Benchling. See https://docs.benchling.com/docs/schemas in our documentation on how Schemas impact our developers

See https://benchling.com/api/reference#/Schemas

property tasks: TaskService

Tasks.

Endpoints that perform expensive computations launch long-running tasks. These endpoints return the task ID (a UUID) in the response body.

After launching a task, periodically invoke the Get a task endpoint with the task UUID (e.g., every 10 seconds), until the status is no longer RUNNING.

You can access a task for up to 30 minutes after its completion, after which its data will no longer be available.

See https://benchling.com/api/reference#/Tasks

property teams: TeamService

Teams.

View team objects.

See https://benchling.com/api/reference#/Teams

property users: UserService

Benchling users.

See https://benchling.com/api/reference#/Users

property v2: V2Service

V2.

Namespace containing support for the V2 Benchling API.

property warehouse: WarehouseService

Warehouse.

Manage warehouse credentials.

See https://benchling.com/api/reference#/Warehouse

property workflow_outputs: WorkflowOutputService

Workflow Outputs.

Workflow outputs are outputs of a workflow task.

See https://benchling.com/api/reference#/Workflow%20Outputs

property workflow_task_groups: WorkflowTaskGroupService

Workflow Tasks Groups.

Workflow task groups are groups of workflow tasks of the same schema.

See https://benchling.com/api/reference#/Workflow%20Task%20Groups

property workflow_tasks: WorkflowTaskService

Workflow Tasks.

Workflow tasks encapsulate a single unit of work.

See https://benchling.com/api/reference#/Workflow%20Tasks

class BenchlingApiClientDecorator

Bases: typing_extensions.Protocol

For customizing a BenchlingApiClient client, which gives access to the underlying HTTPX layer.

Functions implementing this Protocol will receive the default BenchlingApiClient and may mutate specific attributes, returning the updated BenchlingApiClient.

A common use case for this is extending the default HTTP timeout:

def higher_timeout_client(client: BenchlingApiClient) -> BenchlingApiClient: return client.with_timeout(180)

__init__(*args, **kwargs)