esf-format 1.0.0__py3-none-any.whl

esf_format/__init__.py

@@ -0,0 +1,104 @@
+"""Read and write esf/1 (https://github.com/EVEShipFit/esf-format)."""
+
+import base64
+import re
+
+from . import binary, canonical, resolve, source, text
+from .canonical import CanonFit
+from .catalog import (
+    AttributeRecord,
+    Catalog,
+    Kind,
+    ModeCatalog,
+    MutaplasmidCatalog,
+    MutaplasmidRecord,
+    TypeRecord,
+)
+from .errors import EsfError
+from .model import Entry, EsfFit, Location, State
+from .names import fold
+
+__all__ = [
+    "AttributeRecord",
+    "Catalog",
+    "Entry",
+    "EsfError",
+    "EsfFit",
+    "Kind",
+    "Location",
+    "ModeCatalog",
+    "MutaplasmidCatalog",
+    "MutaplasmidRecord",
+    "State",
+    "TypeRecord",
+    "fold",
+    "from_base64url",
+    "is_text",
+    "load",
+    "save",
+    "save_binary",
+    "to_base64url",
+]
+
+_BASE64URL = re.compile(r"[A-Za-z0-9_-]*")
+
+
+def is_text(data: bytes | str) -> bool:
+    """Whether a document is text, by its first character (§10)."""
+    return data[:1] in (b"%", b" ", "%", " ")
+
+
+def _canonical(
+    blocks: list[text.FitBlock], catalog: Catalog, given: list[EsfFit] | None = None
+) -> list[CanonFit]:
+    fits = resolve.resolve(blocks, catalog)
+    if given is not None:
+        source.verify(fits, given)
+    return [canonical.canonical_fit(f, catalog) for f in fits]
+
+
+def _checked(fits: list[EsfFit], catalog: Catalog) -> list[CanonFit]:
+    data, where = source.source(fits, catalog)
+    try:
+        return _canonical(text.parse(data), catalog, fits)
+    except EsfError as e:
+        if e.line is None:
+            raise
+        fit, entry = where[e.line - 1]
+        raise EsfError(e.message, fit=fit, entry=entry) from None
+
+
+def load(data: bytes | str, catalog: Catalog) -> list[EsfFit]:
+    """Read a text or binary document, in canonical form."""
+    if isinstance(data, str):
+        data = data.encode("utf-8", "surrogatepass")
+    if not data:
+        raise EsfError("the document is empty")
+    if is_text(data):
+        fits = _canonical(text.parse(data), catalog)
+    else:
+        fits = _checked(binary.decode(data), catalog)
+    return [canonical.to_model(f) for f in fits]
+
+
+def save(fits: list[EsfFit], catalog: Catalog) -> str:
+    """Write fits as canonical text (§8)."""
+    return canonical.render(_checked(fits, catalog))
+
+
+def save_binary(fits: list[EsfFit], catalog: Catalog) -> bytes:
+    """Write fits in the binary form (§10)."""
+    return binary.encode([canonical.to_model(f) for f in _checked(fits, catalog)])
+
+
+def to_base64url(data: bytes) -> str:
+    """The binary form as base64url without padding, for URLs (§10.4)."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def from_base64url(encoded: str) -> bytes:
+    """The binary form from base64url without padding (§10.4)."""
+    encoded = encoded.strip()
+    if not _BASE64URL.fullmatch(encoded) or len(encoded) % 4 == 1:
+        raise EsfError("not valid base64url")
+    return base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4))

esf_format/binary.py

@@ -0,0 +1,185 @@
+"""The binary form (SPEC §10)."""
+
+import struct
+from typing import TypeVar
+
+from . import wire
+from .model import Entry, EsfFit, Location, State
+
+T = TypeVar("T")
+from .errors import EsfError
+from .text import UINT32_MAX
+
+STATES = {State.OFF: 1, State.ON: 2, State.HEAT: 3}
+LOCATIONS = {
+    Location.HIGH: 1,
+    Location.MID: 2,
+    Location.LOW: 3,
+    Location.RIG: 4,
+    Location.SUB: 5,
+    Location.SVC: 6,
+    Location.CARGO: 7,
+    Location.BAY: 8,
+    Location.AMMO: 9,
+    Location.BOOSTER: 10,
+    Location.COMMAND: 11,
+    Location.CORPSE: 12,
+    Location.DEPOT: 13,
+    Location.EXPEDITION: 14,
+    Location.FLEET: 15,
+    Location.FRIGATE: 16,
+    Location.FUEL: 17,
+    Location.GAS: 18,
+    Location.ICE: 19,
+    Location.INFRASTRUCTURE: 20,
+    Location.MAINTENANCE: 21,
+    Location.MINERAL: 22,
+    Location.MINING: 23,
+    Location.MOON: 24,
+    Location.PLANETARY: 25,
+    Location.QUAFE: 26,
+    Location.SUBSYSTEM: 27,
+}
+
+
+def _encode_entry(entry: Entry) -> bytes:
+    out = []
+    if entry.type is not None:
+        out.append(wire.uint(1, entry.type))
+    if entry.count is not None:
+        out.append(wire.uint(2, entry.count))
+    if entry.fit_name:
+        out.append(wire.record(3, entry.fit_name.encode()))
+    if entry.charge is not None:
+        out.append(wire.uint(4, entry.charge))
+    if entry.charge_count is not None:
+        out.append(wire.uint(5, entry.charge_count))
+    if entry.mutaplasmid is not None:
+        out.append(wire.uint(6, entry.mutaplasmid))
+    if entry.overrides:
+        out.append(wire.packed_uints(7, list(entry.overrides)))
+        out.append(wire.packed_doubles(8, list(entry.overrides.values())))
+    if entry.state is not None:
+        out.append(wire.uint(9, STATES[entry.state]))
+    if entry.location is not None:
+        out.append(wire.uint(10, LOCATIONS[entry.location]))
+    return b"".join(out)
+
+
+def _encode_fit(fit: EsfFit) -> bytes:
+    out = [wire.uint(1, 1)]
+    if fit.hull is not None:
+        out.append(wire.uint(2, fit.hull))
+    if fit.name:
+        out.append(wire.record(3, fit.name.encode()))
+    if fit.mode is not None:
+        out.append(wire.uint(4, fit.mode))
+    out += [wire.record(5, _encode_entry(entry)) for entry in fit.entries]
+    return b"".join(out)
+
+
+def encode(fits: list[EsfFit]) -> bytes:
+    return b"".join(wire.record(1, _encode_fit(fit)) for fit in fits)
+
+
+def _uint32(value: int, what: str) -> int:
+    if value > UINT32_MAX:
+        raise EsfError(f"binary: {what} is out of range")
+    return value
+
+
+def _string(payload: bytes, what: str) -> str | None:
+    try:
+        return payload.decode("utf-8") or None
+    except UnicodeDecodeError:
+        raise EsfError(f"binary: {what} is not valid UTF-8") from None
+
+
+def _enum(numbers: dict[T, int], value: int, what: str) -> T | None:
+    if value == 0:
+        return None
+    for member, number in numbers.items():
+        if number == value:
+            return member
+    raise EsfError(f"binary: unknown {what} value {value}")
+
+
+def _not_in_schema(what: str) -> EsfError:
+    return EsfError(f"binary: {what} has a field that is not in the schema")
+
+
+def _decode_entry(data: bytes) -> Entry:
+    e = Entry(None)
+    attributes: list[int] = []
+    values: list[float] = []
+    for tag, wire_type, value in wire.fields(data):
+        match tag, wire_type:
+            case 1, wire.VARINT:
+                e.type = _uint32(value, "Entry.type")
+            case 2, wire.VARINT:
+                e.count = _uint32(value, "Entry.count")
+            case 3, wire.LEN:
+                e.fit_name = _string(value, "Entry.fit_name")
+            case 4, wire.VARINT:
+                e.charge = _uint32(value, "Entry.charge")
+            case 5, wire.VARINT:
+                e.charge_count = _uint32(value, "Entry.charge_count")
+            case 6, wire.VARINT:
+                e.mutaplasmid = _uint32(value, "Entry.mutaplasmid")
+            case 7, wire.VARINT:
+                attributes.append(_uint32(value, "Entry.override_attributes"))
+            case 7, wire.LEN:
+                attributes += [
+                    _uint32(v, "Entry.override_attributes") for v in wire.unpack_uints(value)
+                ]
+            case 8, wire.I64:
+                values.append(struct.unpack("<d", value)[0])
+            case 8, wire.LEN:
+                values += wire.unpack_doubles(value)
+            case 9, wire.VARINT:
+                e.state = _enum(STATES, value, "State")
+            case 10, wire.VARINT:
+                e.location = _enum(LOCATIONS, value, "Location")
+            case _:
+                raise _not_in_schema("Entry")
+    if len(attributes) != len(values):
+        raise EsfError("binary: override fields have different lengths")
+    e.overrides = dict(zip(attributes, values))
+    if len(e.overrides) != len(attributes):
+        raise EsfError("binary: an attribute is overridden twice")
+    return e
+
+
+def _decode_fit(data: bytes) -> EsfFit:
+    fit = EsfFit()
+    version = 0
+    for tag, wire_type, value in wire.fields(data):
+        match tag, wire_type:
+            case 1, wire.VARINT:
+                version = _uint32(value, "Fit.version")
+            case 2, wire.VARINT:
+                fit.hull = _uint32(value, "Fit.hull")
+            case 3, wire.LEN:
+                fit.name = _string(value, "Fit.name")
+            case 4, wire.VARINT:
+                fit.mode = _uint32(value, "Fit.tactical_mode")
+            case 5, wire.LEN:
+                fit.entries.append(_decode_entry(value))
+            case _:
+                raise _not_in_schema("Fit")
+    if version != 1:
+        raise EsfError(f"binary: unsupported Fit.version {version}")
+    return fit
+
+
+def decode(data: bytes) -> list[EsfFit]:
+    fits = []
+    for tag, wire_type, value in wire.fields(data):
+        if tag != 1:
+            continue
+        if wire_type != wire.LEN:
+            raise EsfError("binary: Document.fits has the wrong wire type")
+        fits.append(_decode_fit(value))
+    if not fits:
+        raise EsfError("binary: a document holds at least one fit")
+    return fits

esf_format/canonical.py

@@ -0,0 +1,285 @@
+"""Canonical form (SPEC §8)."""
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+from . import catalog as cat
+from .catalog import AttributeRecord, Catalog, MutaplasmidRecord, TypeRecord
+from .errors import EsfError
+from .model import Entry, EsfFit, Location, State
+from .names import fold, shortest_unique
+from .resolve import (
+    DEFAULT_PLACES,
+    DRONES,
+    FIGHTERS,
+    PLUGGED,
+    EmptySlot,
+    Fit,
+    Item,
+    default_place,
+    mode_name,
+)
+from .text import HOLDS, RACKS, SIGILS, UINT32_MAX, is_count
+
+GROUPS = (*RACKS, DRONES, FIGHTERS, Location.CARGO, *HOLDS, *PLUGGED)
+
+
+@dataclass
+class CanonLine:
+    type: TypeRecord | None
+    count: int | None = None
+    fit_name: str | None = None
+    charge: TypeRecord | None = None
+    charge_count: int | None = None
+    mutaplasmid: MutaplasmidRecord | None = None
+    mutaplasmid_name: str | None = None
+    overrides: list[tuple[AttributeRecord, float]] = field(default_factory=list)
+    state: str | None = None
+    location: str | None = None
+
+    def body(self) -> str:
+        parts = [quote_type(self.type.name) if self.type else "-"]
+        if self.fit_name is not None:
+            parts.append(quote(self.fit_name))
+        if self.charge is not None:
+            count = "" if self.charge_count is None else f"{self.charge_count}x "
+            parts.append(f":{count}{quote_type(self.charge.name)}")
+        if self.mutaplasmid_name is not None:
+            parts.append(f"+{quote_type(self.mutaplasmid_name)}")
+        if self.overrides:
+            pairs = ", ".join(f"{a.name} {number(v)}" for a, v in self.overrides)
+            parts.append(f"{{{pairs}}}")
+        if self.state is not None:
+            parts.append(f"!{self.state}")
+        if self.location is not None:
+            parts.append(f"@{self.location}")
+        return " ".join(parts)
+
+    def text(self) -> str:
+        if self.count is None:
+            return self.body()
+        return f"{self.count}x {self.body()}"
+
+
+@dataclass
+class CanonFit:
+    hull: TypeRecord | None
+    name: str | None
+    mode: TypeRecord | None
+    mode_text: str | None
+    groups: list[list[CanonLine]]
+
+    @property
+    def lines(self) -> list[CanonLine]:
+        return [line for group in self.groups for line in group]
+
+    def text(self) -> str:
+        hull = [quote_type(self.hull.name) if self.hull else "-"]
+        if self.name is not None:
+            hull.append(quote(self.name))
+        if self.mode_text is not None:
+            hull.append(f"/{quote_type(self.mode_text)}")
+        out = f"%esf/1\n{' '.join(hull)}\n"
+        for group in self.groups:
+            out += "\n" + "".join(line.text() + "\n" for line in group)
+        return out
+
+
+def quote(s: str) -> str:
+    return '"' + s.replace('"', '""') + '"'
+
+
+def needs_quotes(name: str) -> bool:
+    words = name.split(" ")
+    return (
+        words[0][:1] in ("-", "%", "")
+        or is_count(words[0])
+        or any(w[:1] in SIGILS or w == "" for w in words)
+    )
+
+
+def quote_type(name: str) -> str:
+    return quote(name) if needs_quotes(name) else name
+
+
+def number(value: float) -> str:
+    """The shortest decimal, without exponent, that reads back as the same float."""
+    if value == 0:
+        value = 0.0
+    text = repr(value)
+    if "e" in text:
+        text = format(Decimal(text), "f")
+    return text.removesuffix(".0")
+
+
+def _default_state(item: Item) -> str | None:
+    """The state an item has when its line names none; None is active."""
+    if item.place in PLUGGED or not item.type.active:
+        return "on"
+    return None
+
+
+def _line(item: Item, fit: Fit, catalog: Catalog) -> CanonLine:
+    line = item.line
+    out = CanonLine(item.type)
+
+    if item.reference is not None:
+        out.fit_name = item.reference.name
+
+    if item.charge is not None:
+        out.charge = item.charge
+        full = cat.full_load(item.type, item.charge)
+        if line.charge_count is not None and line.charge_count != full:
+            out.charge_count = line.charge_count
+
+    overrides = {a.id: (a, v or 0.0) for a, v in item.overrides}
+    if item.mutaplasmid is not None:
+        out.mutaplasmid = item.mutaplasmid
+        own = item.mutaplasmid.type.name
+        others = [m.type.name for m in cat.mutaplasmids_of(catalog, item.type)]
+        others.remove(own)
+        out.mutaplasmid_name = shortest_unique(own, others)
+        for attr_id, base in item.mutaplasmid.rolls:
+            if attr_id not in overrides:
+                overrides[attr_id] = (cat.attribute_of(catalog, attr_id), base)
+    out.overrides = sorted(overrides.values(), key=lambda o: (fold(o[0].name), o[0].name))
+
+    if line.state is not None and line.state != _default_state(item):
+        out.state = line.state
+
+    if item.place != default_place(item.type.kind, fit.cargo_only) and item.place not in RACKS:
+        out.location = item.place
+    return out
+
+
+def _sort_key(type_: TypeRecord, text: str) -> tuple[str, bytes]:
+    return (fold(type_.name), text.encode())
+
+
+def _collapse(lines: list[tuple[bool, CanonLine]]) -> list[CanonLine]:
+    """Merge adjacent identical repeatable lines into one count."""
+    out: list[tuple[bool, CanonLine]] = []
+    for repeatable, line in lines:
+        if out and repeatable and out[-1][0] and out[-1][1].body() == line.body():
+            prev = out[-1][1]
+            prev.count = (prev.count or 1) + (line.count or 1)
+            if prev.count > UINT32_MAX:
+                raise EsfError(f"lines collapse into a count of {prev.count}, which is too large")
+            continue
+        out.append((repeatable, line))
+    for _, line in out:
+        if line.count == 1:
+            line.count = None
+    return [line for _, line in out]
+
+
+def _rack(fit: Fit, rack: str, catalog: Catalog) -> list[CanonLine]:
+    runs = list(fit.racks.get(rack, []))
+    while runs and runs[-1].item is None:
+        runs.pop()
+    lines = []
+    for run in runs:
+        if run.item is None:
+            line = CanonLine(None, location=rack)
+        else:
+            line = _line(run.item, fit, catalog)
+        line.count = run.length
+        lines.append((True, line))
+    return _collapse(lines)
+
+
+def _sorted(items: list[Item], fit: Fit, catalog: Catalog) -> list[CanonLine]:
+    lines = []
+    for item in items:
+        line = _line(item, fit, catalog)
+        repeatable = not item.stored
+        count = item.line.count or 1
+        if repeatable:
+            line.count = count
+            key = _sort_key(item.type, line.body())
+        else:
+            line.count = None if count == 1 else count
+            key = _sort_key(item.type, line.text())
+        lines.append((key, repeatable, line))
+    lines.sort(key=lambda entry: entry[0])
+    return _collapse([(repeatable, line) for _, repeatable, line in lines])
+
+
+def _fighters(items: list[Item], fit: Fit, catalog: Catalog) -> list[CanonLine]:
+    tubes = [i for i in items if i.place == FIGHTERS]
+    lines = []
+    for item in tubes:
+        line = _line(item, fit, catalog)
+        count = item.line.count
+        if count is not None and count != item.type.squadron_size:
+            line.count = count
+        lines.append(line)
+    return lines + _sorted([i for i in items if i.place == Location.BAY], fit, catalog)
+
+
+def _drones(items: list[Item], fit: Fit, catalog: Catalog) -> list[CanonLine]:
+    space = _sorted([i for i in items if i.place == DRONES], fit, catalog)
+    return space + _sorted([i for i in items if i.place == Location.BAY], fit, catalog)
+
+
+def canonical_fit(fit: Fit, catalog: Catalog) -> CanonFit:
+    groups: dict[str, list[Item]] = {}
+    for item in fit.items:
+        if isinstance(item, EmptySlot) or item.place in RACKS:
+            continue
+        group = item.place
+        if group == Location.BAY:
+            group = DEFAULT_PLACES[item.type.kind]
+        groups.setdefault(group, []).append(item)
+
+    chunks = []
+    for group in GROUPS:
+        if group in RACKS:
+            chunk = _rack(fit, group, catalog)
+        elif group == DRONES:
+            chunk = _drones(groups.get(group, []), fit, catalog)
+        elif group == FIGHTERS:
+            chunk = _fighters(groups.get(group, []), fit, catalog)
+        else:
+            chunk = _sorted(groups.get(group, []), fit, catalog)
+        if chunk:
+            chunks.append(chunk)
+
+    mode_text = None
+    if fit.hull is not None and fit.mode is not None:
+        others = [mode_name(fit.hull, m) for m in cat.modes_of(catalog, fit.hull)]
+        own = mode_name(fit.hull, fit.mode)
+        others.remove(own)
+        mode_text = shortest_unique(own, others)
+
+    return CanonFit(fit.hull, fit.name, fit.mode, mode_text, chunks)
+
+
+def render(fits: list[CanonFit]) -> str:
+    return "\n".join(fit.text() for fit in fits)
+
+
+def _id(record: TypeRecord | None) -> int | None:
+    return None if record is None else record.id
+
+
+def to_model(fit: CanonFit) -> EsfFit:
+    return EsfFit(
+        _id(fit.hull),
+        fit.name,
+        _id(fit.mode),
+        [
+            Entry(
+                _id(line.type),
+                line.count,
+                line.fit_name,
+                _id(line.charge),
+                line.charge_count,
+                _id(line.mutaplasmid.type) if line.mutaplasmid else None,
+                {a.id: v for a, v in line.overrides},
+                State(line.state) if line.state else None,
+                Location(line.location) if line.location else None,
+            )
+            for line in fit.lines
+        ],
+    )

esf_format/catalog.py

@@ -0,0 +1,94 @@
+"""What esf/1 needs to know about types and attributes (SPEC §5, §6)."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from fractions import Fraction
+from typing import Protocol
+
+
+class Kind(StrEnum):
+    """What a type is (§5)."""
+
+    HULL = "hull"
+    CONTAINER = "container"
+    MODE = "mode"
+    SUB = "sub"
+    HIGH = "high"
+    MID = "mid"
+    LOW = "low"
+    RIG = "rig"
+    SVC = "svc"
+    DRONE = "drone"
+    FIGHTER = "fighter"
+    CHARGE = "charge"
+    IMPLANT = "implant"
+    BOOSTER = "booster"
+    OTHER = "other"
+
+
+@dataclass(frozen=True)
+class TypeRecord:
+    id: int
+    name: str
+    kind: Kind
+    active: bool
+    capacity: float
+    volume: float
+    squadron_size: int | None = None
+
+
+@dataclass(frozen=True)
+class AttributeRecord:
+    id: int
+    name: str
+
+
+@dataclass(frozen=True)
+class MutaplasmidRecord:
+    type: TypeRecord
+    rolls: tuple[tuple[int, float], ...]
+
+
+class Catalog(Protocol):
+    """Types and attributes, by folded name (§6.10) or by ID."""
+
+    def type(self, folded: str) -> TypeRecord | None: ...
+
+    def type_by_id(self, type_id: int) -> TypeRecord | None: ...
+
+    def attribute(self, folded: str) -> AttributeRecord | None: ...
+
+    def attribute_by_id(self, attribute_id: int) -> AttributeRecord | None: ...
+
+
+class ModeCatalog(Catalog, Protocol):
+    def modes(self, hull_id: int) -> Sequence[TypeRecord]: ...
+
+
+class MutaplasmidCatalog(Catalog, Protocol):
+    def mutaplasmids(self, type_id: int) -> Sequence[MutaplasmidRecord]: ...
+
+
+def modes_of(catalog: Catalog, hull: TypeRecord) -> Sequence[TypeRecord]:
+    modes = getattr(catalog, "modes", None)
+    return () if modes is None else modes(hull.id)
+
+
+def mutaplasmids_of(catalog: Catalog, base: TypeRecord) -> Sequence[MutaplasmidRecord]:
+    mutaplasmids = getattr(catalog, "mutaplasmids", None)
+    return () if mutaplasmids is None else mutaplasmids(base.id)
+
+
+def attribute_of(catalog: Catalog, attribute_id: int) -> AttributeRecord:
+    attribute = catalog.attribute_by_id(attribute_id)
+    if attribute is None:
+        raise LookupError(f"the catalog has no attribute {attribute_id}")
+    return attribute
+
+
+def full_load(item: TypeRecord, charge: TypeRecord) -> int | None:
+    """How many charges fit in an item (§6.5)."""
+    if item.capacity <= 0 or charge.volume <= 0:
+        return None
+    return int(Fraction(str(item.capacity)) / Fraction(str(charge.volume)))

esf_format/errors.py

@@ -0,0 +1,28 @@
+"""The error for a document or fit that breaks a rule of esf/1."""
+
+
+class EsfError(Exception):
+    """A broken rule, and where: a line of text, or a fit and entry, counting from 1."""
+
+    def __init__(
+        self,
+        message: str,
+        line: int | None = None,
+        fit: int | None = None,
+        entry: int | None = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.line = line
+        self.fit = fit
+        self.entry = entry
+
+    def __str__(self) -> str:
+        if self.fit is not None:
+            where = (
+                f"fit {self.fit}" if self.entry is None else f"fit {self.fit}, entry {self.entry}"
+            )
+            return f"{where}: {self.message}"
+        if self.line is not None:
+            return f"line {self.line}: {self.message}"
+        return self.message