Code Style¶

General Conventions¶

Type Hints¶

Use type hints for function signatures:

def run(cmd, selection: str, cutoff: str = "3.5") -> str:
    ...

Note

Tool arguments are always strings (parsed from command text). Convert inside run():

cutoff_val = float(cutoff)

Imports¶

Standard library first, then third-party, then local
Prefer absolute imports: from codemol.tool_loader import dispatch
Lazy imports for heavy modules (rendering engine, numpy) when possible

Naming¶

Entity	Convention	Example
Tool files	lowercase, underscores	`salt_bridges.py`
Tool functions	always `run`	`def run(cmd, ...):`
Managers	PascalCase + Manager	`StructureManager`
Internal objects	underscore prefix	`_ribbons`, `_nearby`
Private methods	underscore prefix	`_handle_command()`
Constants	UPPER_SNAKE	`_SEL_KEYWORDS`

Tool Conventions¶

Docstrings¶

Every tool should have a module-level docstring with usage:

"""Short description.

Usage: /<group> <tool> <arg1> [arg2]
Example: /<group> <tool> protein 3.5
"""

Return Values¶

Always return a string
Include units: "Distance: 3.45 Å"
Prefix errors: "Error: no atoms selected"
Prefix dry-run: "[dry-run] would measure distance"

Dry-Run Support¶

def run(cmd, selection: str) -> str:
    if cmd is None:
        return f"[dry-run] {selection}"
    # ...

Theme / UI¶

The UI uses a Catppuccin-inspired dark theme defined in codemol/theme.py. When creating UI components:

from codemol.theme import BASE, MANTLE, TEXT, MAUVE, SURFACE0

widget.setStyleSheet(f"""
    background-color: {BASE};
    color: {TEXT};
    border: 1px solid {SURFACE0};
""")

Key colors:

Name	Hex	Usage
`BASE`	`#1e1e2e`	Main background
`MANTLE`	`#181825`	Panel/sidebar background
`SURFACE0`	`#313244`	Borders, separators
`TEXT`	`#cdd6f4`	Primary text
`MAUVE`	`#cba6f7`	Accent (selections, highlights)
`GREEN`	`#a6e3a1`	Success messages
`RED`	`#f38ba8`	Error messages
`YELLOW`	`#f9e2af`	Warnings

File Organization¶

One tool per file
One manager per file
Panels/sidebars in their own files
Keep window.py as thin as possible — delegate to managers