esf-format

Read and write esf/1, the plain-text format for EVE Online ship fits. Text, canonical and binary forms. No dependencies.

pip install esf-format

Usage

import esf_format
from esf_format import Entry, EsfFit, Location, State

fit = EsfFit(
    hull=587,  # Rifter
    name="Shield Buffer",
    entries=[
        Entry(2889, count=3, charge=21898),  # 3 guns, a full load of ammo each
        Entry(None, location=Location.HIGH),  # an empty high slot
        Entry(448, state=State.OFF),  # an offline module
        Entry(2048),  # goes in its own rack
        Entry(2456, count=5),  # 5 drones
        Entry(21898, count=1000, location=Location.CARGO),
    ],
)

text = esf_format.save([fit], catalog)  # canonical text
data = esf_format.save_binary([fit], catalog)  # binary
fits = esf_format.load(data, catalog)  # text or binary

url = esf_format.to_base64url(data)  # the binary form in a URL
data = esf_format.from_base64url(url)

save() and save_binary() take entries in any order, and check every rule of the spec. load() returns fits in canonical form. All three raise esf_format.EsfError when a rule is broken. It says where: line for text, or fit and entry (counting from 1) for fits.

Fits

An EsfFit is one fit: hull, name, tactical mode and its entries. hull is None for a fit without a ship. A document can hold more than one fit.

Each Entry is one line of the fit. None means the default:

The Catalog

The library holds no game data. You give it a Catalog: an object that looks up types and attributes in your copy of the SDE.

class MyCatalog:
    def type(self, folded: str) -> esf_format.TypeRecord | None: ...
    def type_by_id(self, type_id: int) -> esf_format.TypeRecord | None: ...
    def attribute(self, folded: str) -> esf_format.AttributeRecord | None: ...
    def attribute_by_id(self, attribute_id: int) -> esf_format.AttributeRecord | None: ...

    # Optional. Without them, no hull has tactical modes and no type has mutaplasmids.
    def modes(self, hull_id: int) -> Sequence[esf_format.TypeRecord]: ...
    def mutaplasmids(self, type_id: int) -> Sequence[esf_format.MutaplasmidRecord]: ...

Names are looked up folded: index them with esf_format.fold(name). Where names are shared, published wins, then the lowest ID (§4.2). tests/catalog.py is a complete example.

Tests

The test cases live in esf-format:

git clone --branch v1.0 https://github.com/EVEShipFit/esf-format
uv sync
uv run --project esf-format/tools esf-test -- .venv/bin/python tests/program.py
uv run pytest