Package: ce-bnch-sdk
CE Benchling SDKThis is the Customer Engineering team's branch of the Benchling SDK, containing features that we are not yet ready to release to customers.Currently, the only difference from the main Benchling SDK is the Benchling Apps CLI.Benching Apps CLIThe SDK comes with a CLI for managing Benchling Apps, which is still under alpha testing.Each integration corresponds to a Benchling App. You declare the app's dependencies in a manifest file, typically a top-level file namedmanifest.yaml. For example:manifestVersion:1# Currently only version 1 existsinfo:name:My Appversion:0.0.1description:Cure cancer# Optionalconfiguration:-name:My Plasmid# Should match the actual name in Benchling, if possible, as apps tries to find the dependency by nametype:entity_schema# Corresponds to the API namespace, in this case /entity-schemassubtype:dna_sequence# This section is only used by resources with type "entity-schema"# Possible values for entities are: "custom_entity", "dna_sequence", or "aa_sequence"description:Plasmid schema of interest# OptionalfieldDefinitions:-name:My Backbone-name:My Resistances-name:Optical Density Assaytype:assay_run_schemafieldDefinitions:-name:optical_density# Run, result, and request schemas use the snake-cased "warehouse name"-name:Resistancetype:dropdownoptions:-name:1 - Ampicillin-name:2 - Penicillin-name:My Projecttype:projectAny resource type which is served by the Benchling API can be referenced, using its kebab-cased name. Below is the full list of possible values forresourceType. Schema types:entity_schemacontainer_schemaplate_schemabox_schemalocation_schemaassay_result_schemaassay_run_schemarequest_schemaentry_schemaworkflow_task_schemadropdownworkflow_task_statusIndividual resource types:aa_sequenceassay_resultassay_runautomation_input_generatorautomation_output_processorblobboxcontainercustom_entitydna_alignmentdna_oligodna_sequenceentryfolderlabel_printerlabel_templatelocationplateprojectregistryrequestOnce you've declared the dependencies, you can generate thedependencies.pyfile and the model classes (in this casemy_plasmid.py,optical_density_assay.py, andresistance.py) using the command:# Optional arguments `--manifest-file-path`, `dependencies_file_path`, `model_directory_path` to specify the exact pathspoetryrunbenchling-sdkappdependenciesscaffoldNext, once a Benchling tenant has been set up where you want to run the integration, you can link each dependency to its corresponding Benchling API ID by using the configuration UI for Benchling Apps in the tenant.Now the integration will have full access to all its required dependencies. See the documentation in the generated files for more detailed instructions on usage in the integration code.General UsageFor more detailed usage of the SDK, refer to thepublic release notes, which are stored as part of the project
inpublish/README.public.md.Simple usage example iterating through DNA sequences:frombenchling_sdk.auth.api_key_authimportApiKeyAuthfrombenchling_sdk.benchlingimportBenchlingbenchling=Benchling(url="https://my.benchling.com",auth_method=ApiKeyAuth("api_key"))dna_sequence_pages=benchling.dna_sequences.list()forpageindna_sequence_pages:fordna_sequenceinpage:print(dna_sequence.bases)Developer NotesThebenching_sdk.benchling.Benchlingobject serves as the point of entry for the SDK. API calls are organized into
services that generally correspond toCapillary documentation.Each method calling the API is wrapped with an@api_methoddecorator. This decorator applies several global
behaviors which may not be readily obvious including:Conditionally adding some logging on each method callApplying retries via the backoff library whenRetryStrategyis configuredLogging in the SDK follows thePython best practiceof only adding thelogging.NullHandler(). An example of enabling basic logging:importlogginglogging.basicConfig(level=logging.INFO)For more details on configuring or disablingRetryStrategy, refer toAdvanced Use Casesinpublish/README.public.md.HTTP errors like404not found are all caught viaraise_for_status()and transformed into
a standardizedBenchlingErrorwhich wraps the underlying error for a better general error handling experience.
A caught BenchlingError can be inspected to learn the status triggering it, and the full contents of the error
response returned from the Benchling server.Exporting ModelsAlthough generated models are packaged inbenchling_api_client.modelsand its files, we externalize the models viabenchling_sdk.modelsin
order to abstractbenchling_api_clientfrom users such that they may
simply importbenchling_sdk.models.ExampleModelClass.This is accomplished inbenchling_sdk/models/__init__.py. This file
is automatically generated from a Jinja template intemplates/by
runningpoetry run task models. Changes should be committed to source
control. All tasks should be run from the root directory of the project.Missing models frombenchling_api_clientare verified by unit
test inbenchling-sdk/tests/unit/test_models.py.Configuring pre-push Git Hookspoetryrunpre-commitinstall--hook-typepre-pushPublishing ReleasesTo create a release of the SDK, create a tag in Git from themainbranch. CI will then
initiate a build, generate the client, and publish the resulting packages.The published version will reflect the tag, so a tag of1.0.4will publish version1.0.4. Tags that do not meet
Poetry'sversion formatwill create a failed build when publishing is attempted.This README will not be published alongside the public package. To modify the public README, modifypublish/README.public.md. The changes will be copied over when preparing for publishing.NOTE: There are some scripts executed that make changes to the working directory and its files with the intention
of them being discarded (e.g., during CI). If running the scripts locally, exercise caution and save your changes
first.Code Generation Unit TestsThis project uses a feature of theopenapi-python-clientdependency to override one of the templates used for code
generation in that project.  Since this project alters how code generation works, it includes unit testing around that
generation in the form of diffing against a known-good version of the generated code, referred to as thegolden-record(taken from the upstream's naming for their version of this test).  Unit testing will break if the overridden template
which lives underbenchling_sdk/codegen/templatesis altered in a way which changes the output of the generated code.In the event that the breaking changes to this test are intentional, you can regenerate the golden-record:poetry run task regenerate_golden_recordIntegration TestsIntegration tests must be run manually, either via IDE test runners or by command line:poetryruntaskintegrationIntegration tests will not run under CI yet and are currently tightly coupled to cesdktest.bnch.org. They
are most effective for quickly running manual regression testing.