How tucan-nest/tucan works
Project type and purpose
• TUCAN is a Python library/tool, not a web or full‐stack app.
Main architectural components
a. IO Layer
– tucan/io/molfile_reader, molfile_v2000_reader, molfile_v3000_reader, molfile_writer
– Exception classes (tucan/io/exception.py)
b. Parser Layer
– ANTLR‐generated parser (tucan/parser/*.py, *.g4, *.bnfplayground)
– parser/parser.py orchestrates tokenization and AST → graph conversion
c. Core Graph Model & Utilities
– Graph representation (likely networkx or custom in tucan/graph_utils.py)
– Element and graph attributes (element_attributes.py, graph_attributes.py)
– Test utilities (tucan/test_utils.py)
d. Canonicalization
e. Serialization
– tucan/serialization.py: emit final TUCAN string (e.g., C2H4O2/(…))
f. Visualization
– tucan/visualization.py: optional graph‐to‐image or Jupyter output
g. Packaging & Configuration
– pyproject.toml: dependencies, build backend (poetry/flake8, etc.)
– .github/workflows: CI, formatting, dataset generation
– docs folder: demo notebooks, static images
Relationships and data flows
• molfile input (.mol)
↓
• IO Layer reads file → raw token stream or text
↓
• Parser Layer builds intermediate graph structure (nodes=atoms, edges=bonds)
↓
• Graph Utilities annotate degrees, attributes
↓
• Canonicalization orders/renumbers graph → canonical graph
↓
• Serialization produces TUCAN string
↓
• Visualization (optional) renders 2D/3D depiction from canonical graph
• Tests call each layer individually (unit tests for IO, parser, canonicalization, serialization)
• CI workflows run tests, format checks, build docs
Architectural patterns and design principles
• Modular Python package: each subpackage focuses on one responsibility
• Use of generated parser code (ANTLR) to separate grammar from business logic
• Test‐driven design: extensive tests for every component
Technologies & frameworks
• Python ≥3.10
• ANTLR‐generated parser (tucan.parser)
• Pytest for testing
• Jupyter notebooks (docs)
• GitHub Actions (CI, formatting)