About

A Python 3.7+ SDK for the Benchling platform designed to provide typed, fluent interactions with Benchling APIs.

📘

Not Using Python?

Our Python SDK leverages models generated from our OpenAPI specification. You can always generate a client in the language of your choice using the same specification through open source generators like this one at OpenAPI Generator. Please note that we do not test our OpenAPI specification with these generators though, and there might be unforeseen issues with the specific generator used.

Why Use the SDK

Developers often create internal libraries (or leverage third-party ones) to handle interactions with Benchling's API, such as facilitating sleep & retry strategies after encountering a rate-limit error. The maintenance of these internal and/or third-party libraries can create significant overhead and make it harder to get started with our APIs.

We've helped alleviate much of this overhead with our Python SDK. At a high-level, our Python SDK provides a hassle-free library of Python classes and methods to handle the nuances of interacting with Benchling’s API endpoints in a first-class manner.

Some notable benefits of leveraging Benchling’s Python SDK include:

• Get started faster - An SDK package and an API key are all you need to start interacting with Benchling.
• Work with Benchling Objects - Resources are automatically constructed and deserialized into Python classes, freeing developers from JSON.
• Fewer errors, More development - Our Python SDK handles all of the nuances of connections, authentication, error handling, pagination, and retries in an off-the-shelf library.

Consider leveraging Benchling’s Python SDK to shorten development timelines for all your software integrations using Benchling's APIs.

📘

An SDK, not an API

This SDK is purely an abstraction on our existing APIs. It does not provide any interactions above and beyond those that are available by interacting with the APIs directly in another language, or through another package like requests.

Getting Started

Installation

Stable

Install the latest stable release of the Benchling SDK via Poetry (if applicable):

poetry add benchling-sdk

Or via Pip:

pip install benchling-sdk

Preview

Benchling also publishes preview builds, which are tagged “pre-release” in the benchling-sdk release history. Preview builds are pre-release, published frequently, and generally include features that are in active development. For the purposes of our Stability Guidelines preview builds are considered alpha functionality, and are not intended for production use. We highly encourage you to provide feedback on them!

Install the latest preview release of the Benchling SDK by specifying the preview version; this can be done via Poetry (if applicable):

poetry add benchling-sdk --allow-prereleases

Or via Pip:

pip install benchling-sdk --pre

Using the SDK

The Benchling SDK can use an API key or OAuth credentials for authentication. If you're using an API key, start by obtaining a valid API key from your Benchling account and provide it to the SDK, along with the URL for your tenant.

Example:

from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.api_key_auth import ApiKeyAuth

benchling = Benchling(url="https://my.benchling.com", auth_method=ApiKeyAuth("api_key"))

If you're using OAuth credentials from an app, start by obtaining a valid client ID and client secret from the app's settings page in Benchling. Then, provide the client ID and secret to the SDK, along with the URL for your tenant. You can also find more examples using the SDK with an app here.

Example:

from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

auth_method = ClientCredentialsOAuth2(client_id="{id_here}",client_secret="{secret_here}")
benchling = Benchling(url="https://{tenant_name}.benchling.com", auth_method=auth_method)

Now, with Benchling instantiated, make a sample call to list DNA Sequences:

example_entities = benchling.dna_sequences.list()
for page in example_entities:
  for sequence in page:
    print(f"name: {sequence.name}\nid:{sequence.id}\n")

And you've successfully made a call to list DNA sequences from your tenant! To iterate through the list of DNA sequences you just retrieved, refer to the guidance in our Common SDK Interactions and Examples

Next Steps

Check out Common SDK Interactions and Examples for code walkthroughs of other types of interactions users frequently do in our SDK, or check out Browsing the SDK Reference to understand the full functionality that's exposed in the SDK!

Support

If you have any issues with or question about the SDK, please contact Benchling support at [email protected].