\*Allotrope® is a registered trademark of the Allotrope Foundation; no affiliation with the Allotrope Foundation is claimed or implied.
# Introduction
Welcome to `allotropy` -- a Python library by Benchling for converting instrument data into the Allotrope Simple Model (ASM).
View the list of instrument software currently supported in [SUPPORTED_INSTRUMENT_SOFTWARE](https://github.com/Benchling-Open-Source/allotropy/blob/main/SUPPORTED_INSTRUMENT_SOFTWARE.adoc).
The objective of this library is to read text or Excel based instrument software output and return a JSON representation that conforms to the published ASM schema. Note that some schemas do not yet match the published ASM schema, in these cases the CHANGE_NOTES.md file included alongside the schema details the differences and proposed changes to ASM or the library schema. The code in this library does not convert from proprietary/binary output formats and so has no need to interact with any of the specific vendor softwares.
If you aren't familiar with Allotrope, we suggest you start by reading the [Allotrope Product Overview](https://www.allotrope.org/product-overview).
We have chosen to have this library output ASM since JSON is easy to read and consume in most modern systems and can be checked by humans without any special tools needed. All of the published open source ASMs can be found in the [ASM Gitlab repository](https://gitlab.com/allotrope-public/asm).
This code is published under the permissive MIT license because we believe that standardized instrument data is a benefit for everyone in science.
# Contributing
We welcome community contributions to this library and we hope that together we can expand the coverage of ASM-ready data for everyone. If you are interested, please read our [contribution guidelines](CONTRIBUTING.md).
# Usage
Convert a file to an ASM dictionary:
```sh
from allotropy.parser_factory import Vendor
from allotropy.to_allotrope import allotrope_from_file
asm_dict = allotrope_from_file("filepath.txt", Vendor.MOLDEV_SOFTMAX_PRO)
```
or, convert any IO:
```sh
from allotropy.parser_factory import Vendor
from allotropy.to_allotrope import allotrope_from_io
with open("filename.txt") as f:
asm_dict = allotrope_from_io(f, Vendor.MOLDEV_SOFTMAX_PRO)
bytes_io = BytesIO(file_stream)
asm_dict = allotrope_from_io(bytes_io, Vendor.MOLDEV_SOFTMAX_PRO)
```
# Specific setup and build instructions
`.gitignore`: used standard GitHub Python template and added their recommended JetBrains lines
### Setup
Install Hatch: https://hatch.pypa.io/latest/
Install Python: https://www.python.org/downloads/
This library supports Python 3.10 or higher. Hatch will install a matching version of Python (defined in `pyproject.toml`) when it sets up your environment.
Tell git to use .githooks:
```sh
git config core.hooksPath .githooks
```
#### Dependencies
To add requirements used by the library, update `dependencies` in `pyproject.toml`:
- For project dependencies, update `dependencies` under `[project]`.
- For script dependencies, update `dependencies` under `[tool.hatch.envs.default]`.
- For lint dependencies, update `dependencies` under `[tool.hatch.envs.lint]`.
- For test dependencies, update `dependencies` under `[tool.hatch.envs.test]`.
### Useful Hatch commands
List all environments:
```sh
hatch env show
```
Run all lint:
```sh
hatch run lint:all
```
Auto-fix all possible lint issues:
```sh
hatch run fix
```
Run all tests in the default python enviroment (currently: 3.11.9)
```sh
hatch run test
```
Run all tests against all supported python versions (currently 3.10-3.12)
Note: this is checked against in CI - your change must pass this to merge.
```sh
hatch run test_all:test
```
Run against a specific python version (useful for debugging if a test is failing in one environment)
```sh
hatch run test_all.py3.12:test
```
Run a specific test file (replace the filepath with your own):
```sh
hatch run test tests/allotrope/allotrope_test.py
```
Run all tests with coverage:
```sh
hatch run test:cov
```
Spawn a shell within an environment for development:
```sh
hatch shell
```
### Publish
NOTE: only package admins can publish allotropy.
To publish a new version:
```sh
hatch run scripts:update-version
```
Merge the resulting PR, and then run on `main`:
```
hatch build
hatch publish
```
Raw data
{
"_id": null,
"home_page": null,
"name": "allotropy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "allotrope, allotropy, asm, benchling, converters",
"author": null,
"author_email": "Benchling Open Source <opensource@benchling.com>, Lukas Boelling <lukas.boelling@deepgenomics.com>, Nick Collins <nick.collins@benchling.com>, Danielle Chou <danielle.chou@benchling.com>, Chris Friedline <chris.friedline@benchling.com>, Kathy Garcia <kathy@benchling.com>, Trevor Halum <trevor.halum@deepgenomics.com>, Joshua Hernandez <jherna@benchling.com>, Sebastian Lopez <sebastian.cardona@benchling.com>, James Leinas <james.leinas@benchling.com>, Mindren Lu <mindren.lu@benchling.com>, Keith Macaulay <keith.macaulay@benchling.com>, Joe Negri <joe.negri@benchling.com>, Preston Olinger <preston.olinger@benchling.com>, Alejando Salgado <alejando.salgado@benchling.com>, Nathan Stender <nathan.stender@benchling.com>, Eihab Syed <eihabsyed@gmail.com>, Yukthi Wickramarachchi <yukthi.wickramarachchi@deepgenomics.com>, Greg Wilson <gvwilson@third-bit.com>, Ben Wolfe <bwolfe@benchling.com>, Stephen Worlow <stephen.worlow@benchling.com>, Brian Worth <brian@benchling.com>, Alex Reis <alex@manifold.bio>",
"download_url": "https://files.pythonhosted.org/packages/da/a2/760a7b7ccea0d65320b923392ab713830420aca9ab03d98339dfa900e44e/allotropy-0.1.72.tar.gz",
"platform": null,
"description": "\\*Allotrope\u00ae is a registered trademark of the Allotrope Foundation; no affiliation with the Allotrope Foundation is claimed or implied.\n\n# Introduction\nWelcome to `allotropy` -- a Python library by Benchling for converting instrument data into the Allotrope Simple Model (ASM).\n\nView the list of instrument software currently supported in [SUPPORTED_INSTRUMENT_SOFTWARE](https://github.com/Benchling-Open-Source/allotropy/blob/main/SUPPORTED_INSTRUMENT_SOFTWARE.adoc).\n\nThe objective of this library is to read text or Excel based instrument software output and return a JSON representation that conforms to the published ASM schema. Note that some schemas do not yet match the published ASM schema, in these cases the CHANGE_NOTES.md file included alongside the schema details the differences and proposed changes to ASM or the library schema. The code in this library does not convert from proprietary/binary output formats and so has no need to interact with any of the specific vendor softwares.\n\nIf you aren't familiar with Allotrope, we suggest you start by reading the [Allotrope Product Overview](https://www.allotrope.org/product-overview).\n\nWe have chosen to have this library output ASM since JSON is easy to read and consume in most modern systems and can be checked by humans without any special tools needed. All of the published open source ASMs can be found in the [ASM Gitlab repository](https://gitlab.com/allotrope-public/asm).\n\nThis code is published under the permissive MIT license because we believe that standardized instrument data is a benefit for everyone in science.\n\n# Contributing\nWe welcome community contributions to this library and we hope that together we can expand the coverage of ASM-ready data for everyone. If you are interested, please read our [contribution guidelines](CONTRIBUTING.md).\n\n\n# Usage\n\nConvert a file to an ASM dictionary:\n\n```sh\nfrom allotropy.parser_factory import Vendor\nfrom allotropy.to_allotrope import allotrope_from_file\n\nasm_dict = allotrope_from_file(\"filepath.txt\", Vendor.MOLDEV_SOFTMAX_PRO)\n```\n\nor, convert any IO:\n\n```sh\nfrom allotropy.parser_factory import Vendor\nfrom allotropy.to_allotrope import allotrope_from_io\n\nwith open(\"filename.txt\") as f:\n asm_dict = allotrope_from_io(f, Vendor.MOLDEV_SOFTMAX_PRO)\n\nbytes_io = BytesIO(file_stream)\nasm_dict = allotrope_from_io(bytes_io, Vendor.MOLDEV_SOFTMAX_PRO)\n```\n\n# Specific setup and build instructions\n\n`.gitignore`: used standard GitHub Python template and added their recommended JetBrains lines\n\n\n### Setup\n\nInstall Hatch: https://hatch.pypa.io/latest/\nInstall Python: https://www.python.org/downloads/\nThis library supports Python 3.10 or higher. Hatch will install a matching version of Python (defined in `pyproject.toml`) when it sets up your environment.\n\nTell git to use .githooks:\n```sh\ngit config core.hooksPath .githooks\n```\n\n#### Dependencies\n\nTo add requirements used by the library, update `dependencies` in `pyproject.toml`:\n- For project dependencies, update `dependencies` under `[project]`.\n- For script dependencies, update `dependencies` under `[tool.hatch.envs.default]`.\n- For lint dependencies, update `dependencies` under `[tool.hatch.envs.lint]`.\n- For test dependencies, update `dependencies` under `[tool.hatch.envs.test]`.\n\n### Useful Hatch commands\nList all environments:\n```sh\nhatch env show\n```\n\nRun all lint:\n```sh\nhatch run lint:all\n```\n\nAuto-fix all possible lint issues:\n```sh\nhatch run fix\n```\n\nRun all tests in the default python enviroment (currently: 3.11.9)\n```sh\nhatch run test\n```\n\nRun all tests against all supported python versions (currently 3.10-3.12)\nNote: this is checked against in CI - your change must pass this to merge.\n```sh\nhatch run test_all:test\n```\n\nRun against a specific python version (useful for debugging if a test is failing in one environment)\n```sh\nhatch run test_all.py3.12:test\n```\n\nRun a specific test file (replace the filepath with your own):\n```sh\nhatch run test tests/allotrope/allotrope_test.py\n```\n\nRun all tests with coverage:\n```sh\nhatch run test:cov\n```\n\nSpawn a shell within an environment for development:\n```sh\nhatch shell\n```\n\n### Publish\n\nNOTE: only package admins can publish allotropy.\n\nTo publish a new version:\n\n```sh\nhatch run scripts:update-version\n```\n\nMerge the resulting PR, and then run on `main`:\n```\nhatch build\nhatch publish\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Converts to ASM (Allotrope Simple Model) from various file formats.",
"version": "0.1.72",
"project_urls": {
"Documentation": "https://github.com/Benchling-Open-Source/allotropy#readme",
"Issues": "https://github.com/Benchling-Open-Source/allotropy/issues",
"Source": "https://github.com/Benchling-Open-Source/allotropy"
},
"split_keywords": [
"allotrope",
" allotropy",
" asm",
" benchling",
" converters"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ddbff7e2f760517a6960ef7d5796138bfab1a9768afb3d7be5109617039c44f6",
"md5": "1803b931d5a52452949e2aaa63c3aaa3",
"sha256": "7804c4ee51cf54328dfdf5c22424f2014bb16ee7a85bb5c08697ccea63dd949a"
},
"downloads": -1,
"filename": "allotropy-0.1.72-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1803b931d5a52452949e2aaa63c3aaa3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 974899,
"upload_time": "2025-01-21T19:09:40",
"upload_time_iso_8601": "2025-01-21T19:09:40.899742Z",
"url": "https://files.pythonhosted.org/packages/dd/bf/f7e2f760517a6960ef7d5796138bfab1a9768afb3d7be5109617039c44f6/allotropy-0.1.72-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "daa2760a7b7ccea0d65320b923392ab713830420aca9ab03d98339dfa900e44e",
"md5": "11fbc5ec0c7b7327ab5250cd47a9de4b",
"sha256": "bcb36512ccfc56281639e5da8113be061a3a7ef0f0210e06f22ee3b966a34be7"
},
"downloads": -1,
"filename": "allotropy-0.1.72.tar.gz",
"has_sig": false,
"md5_digest": "11fbc5ec0c7b7327ab5250cd47a9de4b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 728650,
"upload_time": "2025-01-21T19:09:38",
"upload_time_iso_8601": "2025-01-21T19:09:38.790997Z",
"url": "https://files.pythonhosted.org/packages/da/a2/760a7b7ccea0d65320b923392ab713830420aca9ab03d98339dfa900e44e/allotropy-0.1.72.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-21 19:09:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Benchling-Open-Source",
"github_project": "allotropy#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "allotropy"
}
JSON
