SnapGene File Format Parser

A reverse-engineered parser and writer for SnapGene .dna / .rna / .prot files. Supports all 17 known block types with typed Python models, a chainable builder pattern, and a history operations API.

Installation

pip install sgffp

Requires Python 3.10+.

Quick Start

from sgffp import SgffReader, SgffWriter, SgffObject

# Read a SnapGene file
sgff = SgffReader.from_file("plasmid.dna")

# Access data via typed properties
print(sgff.sequence.value)
print(sgff.features[0].name)

# Modify and write back
sgff.sequence.topology = "circular"
SgffWriter.to_file(sgff, "output.dna")

# Create a new file from scratch
sgff = (
    SgffObject.new("ATGCATGCATGC", topology="circular")
    .add_feature("GFP", "CDS", 0, 8)
    .add_primer("fwd", "ATGC", bind_position=0)
)
SgffWriter.to_file(sgff, "new_plasmid.dna")

History Operations

Record cloning operations with automatic history tracking:

sgff.ops.insert_fragment("ATCGATCG")
sgff.ops.digest("GGCC", InputSummary={"manipulation": "digest"})

# Or build an entire tree from multiple source files
vector = SgffReader.from_file("vector.dna")
insert = SgffReader.from_file("insert.dna")

sgff.ops.build_from_spec(
    [
        {"id": 1, "operation": "insertFragment", "sequence": "...",
         "name": "Final", "children": [2, 3]},
        {"id": 2, "source": vector},
        {"id": 3, "source": insert},
    ],
    final_sequence="...",
)

How It Works

SnapGene files use a TLV (Type-Length-Value) binary format after a 19-byte header. Each block has a 1-byte type ID and a 4-byte length, with encoding varying by type: UTF-8 for sequences, XML for annotations, 2-bit GATC encoding for compressed DNA, LZMA for history, and ZTR for chromatogram traces.

SgffReader parses blocks via a version-aware SCHEME dispatch table (resolved from the file's export_version, so old and new SnapGene layouts are handled without version branches in the parsers themselves) and stores them in SgffObject.blocks (a Dict[int, List]). Typed model properties (sgff.sequence, sgff.features, sgff.history, etc.) are lazily loaded from the blocks dict and sync changes back automatically. SgffWriter serializes blocks back to binary in sorted order, normalizing to the modern format by default (or preserving the source version with preserve=True).

Supported Block Types

Blocks 2, 3, 13, 35 are SnapGene enzyme caches. Modern SnapGene (export_version >= 15) regenerates them, so they are skipped; legacy files (< 15) are not regenerated by SnapGene, so blocks 2, 3, 13 are retained there to keep enzymes on round-trip. See Versioning.

CLI

sff parse plasmid.dna           # Export to JSON
sff info plasmid.dna -v         # Show detailed file info
sff tree plasmid.dna            # Display history timeline
sff check plasmid.dna -l        # List block types
sff filter plasmid.dna -k 0,10 -o minimal.dna
sff convert old.dna -o new.dna         # Re-save, normalizing to the modern format
sff convert old.dna -o new.dna -p      # Re-save, preserving the source version

All read commands accept stdin (cat file.dna | sff info).

Development

git clone https://github.com/merv1n34k/sgffp.git
cd sgffp
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Docs (VitePress)
cd docs && bun install && bun run docs:dev

Documentation

Full guides, API reference, CLI reference, and binary format specification:

merv1n34k.github.io/sgffp

Acknowledgments

This project would not have been possible without previous work done by

• Damien Goutte-Gattat, see his PDF on SGFF structure: https://incenp.org/dvlpt/docs/binary-sequence-formats/binary-sequence-formats.pdf
• Isaac Luo, for his version of SnapGene reader: https://github.com/IsaacLuo/SnapGeneFileReader
• Kale Kundert, for autosnapgene, a SnapGene automation tool: https://github.com/kalekundert/autosnapgene

Contributions

Also would like to say thank for the people who helped the project:

• Manuel Lera-Ramirez (@manulera) for his PRs and suggestions
• Cory Tobin (@cory-mozza) for reviewing new blocks
• Nicola Zilio (@nicolazilio) for legacy SnapGene support and issue reviews

License

Distributed under MIT licence, see LICENSE for more.