jvrana / benchling-api

A python wrapper for the benchling api

BenchlingAPI

The (unofficial) python API wrapper for Benchling. For more information, see documentation at https://klavinslab.github.io/benchling-api/index.

Installation

pip install benchlingapi -U

Getting Started

Initialize a session using your Benchling-provided API key:

from benchlingapi import Session
session = Session("your_secret_benchling_api_key")

From there, you can access various models:

session.DNASequence
session.AASequence
session.Oligo
session.Folder
session.Project
session.Registry
session.Translation
session.EntitySchema
session.Batch
session.CustomEntity

Finding models:

# get one model
dna = session.DNASequence.one()

# find a specific model by its id
dna = session.DNASequence.find('sdg_4tg23')

# get the last 50 amino acids
proteins = session.AASequence.last(50)

# get a registry by name
registry = session.Registry.find_by_name("Klavins Lab Registry")

Updating models:

dna = session.DNASequence.one()
dna.name = "My new name"
dna.bases = "AGGTAGGGTAGGGCCAGAGA"

# update the sequence on the server
dna.update()

Saving new models:

folder = session.Folder.find_by_name("My API Folder")
dna = session.DNASequence(
    name = 'my new dna',
    bases = 'AGGTAGGATGGCCA',
    folder_id = folder.id,
    is_circular = False
)

# save the dna to your Benchling account
dna.save()

Registering models to your registry:

dna.set_schema("My DNA Schema")
dna.register()

See the documentation for more information: https://klavinslab.github.io/benchling-api/index

Testing

Testing is done using pytest. Tests will create live requests to a Benchling account. Since testing is done live, a Benchling account will need to be setup along with testing data.

To run tests, you must have a Benchling Account with an API key. Tests require a file in 'tests/secrets/config.json' with the following format:

{
  "credentials": {
    "api_key": "asdahhjwrthsdfgadfadfgadadsfa"
  },
  "sharelinks": [
    "https://benchling.com/s/seq-asdfadsfaee"
  ],
  "project": {
    "name": "API"
  },
  "trash_folder": {
    "name": "API_Trash"
  },
  "inventory_folder": {
    "name": "API_Inventory"
  }
}

On the Benchling side of things, in the account liked to the credentials["api_key"], you must have a project corresponding to the project["name"] value above. Within this project, you should have two folder corresponding to the trash_folder and inventory_folder values above. Additionally, you should have at least one example of an AminoAcid, DNASequence, CustomEntity, and Oligo stored within your inventory_folder. Tests will copy the examples from the inventory_folder for downstream tests. After the tests, conclude, inventory in the trash_folder will get archived.

Happy Cloning!

benchling-api's Issues

Licence

This project looks promising and useful. Under what licence is this published?

Method for sequence alignments

There should be a method to submit a sequence alignment onto Benchling. The current workaround is:

data = None # file data
seq_id = None # the benchling sequence_id
post_data = {
        "name": "Trident Submitted Alignment",
        "algorithm": "mafft",
        "templateSequenceId": seq_id,
        "files": []
    }
    
    uploads = data['uploads']
    for upload in uploads:
        b64data = base64.b64encode(data.content).decode('utf-8')
        post_data['files'].append({
            'name': upload.name,
            'data': b64data
        })
    
    result = benchapi.http.post('dna-alignments', action='create-template-alignment', json=post_data)

Delete method

Some models (DNASequenceAlignment) should have a delete method.

Missing Oligo.find_by_name

I'm not clear on why Oligo doesn't inherit from ListMixin. This would allow using Oligo.find_by_name just as you can with DNASequence.

Currently I'm using the following monkey-patch, which seems to work:

if benchlingapi.models.mixins.ListMixin not in benchlingapi.models.Oligo.__bases__:
    benchlingapi.models.Oligo.__bases__ = (
        benchlingapi.models.mixins.ListMixin,
    ) + benchlingapi.models.Oligo.__bases__

Develop mocked API for running tests

Motivation
Testing an API client based on a third-party's continually-evolving API is challenging. It's made even more challenging by the fact that some API features (#38) are not available to all users. Setup/teardown may not be a viable concept for some more complex endpoints and is not necessarily sustainable. There are also no create endpoints for certain actions, such as creating schemas in the registry, precluding tests of many schema-requiring endpoints on a fresh environment.

Proposal A
There might be a possibility for soft tests that just check for syntax/types in an intercepted request's body. The V2 endpoints are variable in their finickiness, so this could take a while to get right, but would be a lightweight solution. If the underlying request-forming functions are appropriately strict, developing and testing on top of them would be much faster this way.

Proposal B
Fully mock the API with an implementation akin to moto, enabling a test workflow that could e.g. create, get, archive an object without having seen it before. The logic would still be equivalently tricky here. For example, in storage, matrix plates are created with capitalized wells, but are returned with lower-case wells.

Create DNA Sequence in Benchling from .gb file

Is your feature request related to a problem? Please describe.
Create DNA Sequence in Benchling from .gb file

Describe the solution you'd like
Function which convert .gb file to DNA Sequence

Describe alternatives you've considered
I have used BioPython and manual way of conversion

Additional context
Currently Benchling does not support Import in its API. I have looked for such function in DNA Sequence model, as well as in utils file. Additional problem is that Benchling does not define the format of annotation field in its API, and in order to understand it I have to fetch the DNA sequence from benchling over API client and examine it.

Find DNA by sequence

Describe the solution you'd like
There should be a method in session.DNASequence that allows a search fo plasmids by sequence, just as in the Benchling UI.

Amino Acid Sequence Dropped during DNASequence Dump

Describe the bug
The amino acid sequence information is lost when DNASequences are dumped to python dicts.

To Reproduce
Create a DNASequence object with a translation that contains amino acid information. Use the dump function on that sequence. See the code snippet below.

ex_seq = models.DNASequence(bases='atgcataa', 
                            translations=[{'start'=0,  
                                           'end'=8, 'strand'=1, 
                                           'aminoAcids': 'MHK'}])

print(ex_seq.translations)
print(ex_seq.dump())

From this you will see different output for the translationSchema.

Expected behavior
The amino acid sequence information follows the translation dict during the data dump. In this example, for the translationSchema's of the two print statements to match up.

Additional context
One hacky fix is you can restore the amino acid sequence by saving a temporary translation and replacing the translation in the dump.

Shared link

Q: Is there any way to generate a shared link with your API lib?

Use case?

Hi, this looks very interesting. What is your use case?

Benchling API v2 Support

v1 of the API is deprecated and is no longer supported by Benchling. Are there plans to update the repo so it supports v2?

https://docs.benchling.com/v2/

Create folders

It would be useful if you could create and update new folders (and even projects).

Right now I'm using the following monkey-patch, and it seems to work.

benchlingapi.models.Folder.CREATE_SCHEMA = dict(
    only=("id", "name", "parent_folder_id", "project_id", "archive_record")
)
benchlingapi.models.Folder.__bases__ = (
    benchlingapi.models.mixins.CreateMixin,
) + benchlingapi.models.Folder.__bases__

Enterprise Features

Proposal
Extend features to cover enterprise use-cases including requests, workflows, transfers, inventory management, warehouse, and (soon) "automation"

Rationale
A large number of "quiet" users require integrations with these API endpoints, and constructing simple integration APIs is non-trivial. Extending the object-oriented framework here would make developing these integrations much easier.

Caveats
One hurdle is that of testing, without access to the features we would need to develop a mocking suite capable of recapitulating the API response.

Potential Solution
Reach out to Benchling directly about setting up a development environment with enterprise features. They have contributed some examples to github and may be receptive.

I'd be happy to chip away at some of these implementations, but would like some guidance on structure and test design to follow the style in place. For example, many of these endpoints can have many (hundreds) of various API actions in a single "unit". I'd be interested in hearing some design ideas for expanding the data model to the enterprise features.

Sessions do not work with URL-encoded servers.

Some Benchling users have URLs of the form "https://{my_org}.benchling.com/api/v2/", currently Http and subsequently Session are hardcoded to "https://benchling.com/api/v2".

To Reproduce
Steps to reproduce the behavior:

1. Have a URL-encoded org

Expected behavior
Session accepts setting the Http.HOME url