How synbiodex/sbol-utilities works
Project Type and Its Purpose
• This project is a utilities library focused on SBOL data transformation and analysis—for both command-line usage and as an importable Python module.
• It is not a full-stack web application, but an open-source tool/library that exposes several independent command-line utilities and Python functions to work with SBOL data.
File Structure for Architectural Clues
• The top-level directories include:
• .github directory: Contains workflows for continuous integration (e.g., testing, docstring coverage) which indicate a CI/CD pipeline.
• docs: Documentation source files (using Sphinx with a Makefile, conf.py) for project documentation via ReadTheDocs.
• sbol_utilities: The core package where all main utility functions and scripts (such as conversion, graphing, sequence calculation, etc.) are found.
• test: A comprehensive test suite validating the various utilities and ensuring proper functioning.
• Files such as setup.py, setup.cfg, and pyproject.toml: Indicate packaging and dependency management.
• There are also external assets like the Excel template (sbol_library_template.xlsx) and several CSV files which seem crucial for conversions (e.g., gb2so.csv, so2gb.csv).
README for Further Architectural Insights
• The README describes multiple utilities (graphing, converting between SBOL and GenBank/FASTA, expanding combinatorial derivations, calculating sequences or synthesis complexities, and computing diffs between SBOL documents).
• Usage instructions are provided both for command-line interfaces and for integration within a host application.
a. Main Components:
• SBOL Core Library (represented by the sbol_utilities module) that contains common functions and classes for different operations.
• Individual Utilities:
• Excel-to-SBOL Converter: Processes an Excel library template file and converts it into SBOL.
• Format Converters: Utilities for converting between SBOL3, SBOL2, GenBank, and FASTA.
• Derivation Expander: Module that identifies combinatorial derivations and expands them.
• Sequence Calculator: Computes DNA sequences from component parts.
• Complexity Calculator: Evaluates sequence synthesis complexity via the external IDT API.
• SBOL Diff Tool: Compares two SBOL documents and identifies differences.
• External Dependencies:
• Node.js for execution of JavaScript components (e.g., sbolgraph-standalone.js).
• IDT’s API as an external service for the complexity score computation.
• Testing and CI:
• Continuous integration workflows (GitHub Actions) and a robust test suite ensure that any changes are validated.
• Packaging/Distribution:
• Setup and configuration files indicate the system’s preparedness for distribution via PyPI.
b. Relationships and Data Flow:
• The core library (sbol_utilities) serves as the “engine” that each utility leverages.
c. Architectural Patterns and Design Principles:
• Modular design: Each utility functions as an independent module, promoting separation of concerns within the core library.
• Command-line interface abstraction: Clearly separate functions meant for direct command-line execution (e.g., using if __name__ == '__main__') from those intended as callable Python functions.
• Integration with external tools: The design includes wrappers over third-party libraries and APIs, ensuring loose coupling between the core logic and external dependencies.
d. Technologies and Frameworks:
• Python as the programming language.
• Sphinx for documentation (as seen under docs/).
• Node.js for some SBOL conversion utilities.
• Pytest (and CI workflows) for testing.