open-dragoman 0.2.2__py3-none-win_amd64.whl

dragoman/__init__.py

@@ -0,0 +1,348 @@
+"""Dragoman -- translate maps between Open Doctrines and Greater Diplomacy 5.
+
+    import dragoman
+
+    report = dragoman.convert("1914.odmap", "base_maps/1914", to="gd5")
+    for entry in report.warnings:
+        print(entry.code, entry.message)
+
+    world = dragoman.load("1914.odmap")
+    print(world.name, len(world.provinces), "provinces")
+
+The whole model is available as plain Python data through `World.to_dict()`,
+so a map can be inspected or edited here and written back out without this
+package needing an accessor for every field the two games have.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+from ._ffi import Options, declare, load_library
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "abi_version",
+    "library_version",
+    "Format",
+    "Severity",
+    "Diagnostic",
+    "Report",
+    "World",
+    "DragomanError",
+    "detect",
+    "load",
+    "convert",
+    "roundtrip_check",
+]
+
+_lib = None
+
+
+def _library():
+    global _lib
+    if _lib is None:
+        _lib = declare(load_library())
+    return _lib
+
+
+class DragomanError(RuntimeError):
+    """A conversion that could not be completed.
+
+    Carries the report as well as the message, because the reason a map failed
+    is usually in a diagnostic rather than in the final error string.
+    """
+
+    def __init__(self, message: str, report: Optional["Report"] = None):
+        super().__init__(message)
+        self.report = report
+
+
+class Format:
+    UNKNOWN = 0
+    ODMAP = 1
+    GD5 = 2
+
+    _BY_NAME = {"odmap": ODMAP, "od": ODMAP, "gd5": GD5, "gd": GD5, "unknown": UNKNOWN}
+
+    @classmethod
+    def parse(cls, value: Union[int, str, None]) -> int:
+        if value is None:
+            return cls.UNKNOWN
+        if isinstance(value, int):
+            return value
+        key = value.strip().lower()
+        if key not in cls._BY_NAME:
+            raise ValueError(f"unknown format {value!r}; use 'odmap' or 'gd5'")
+        return cls._BY_NAME[key]
+
+    @staticmethod
+    def name(value: int) -> str:
+        return _library().dg_format_name(value).decode()
+
+
+class Severity:
+    INFO = 0
+    WARNING = 1
+    ERROR = 2
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    severity: int
+    code: str
+    message: str
+
+    @property
+    def is_warning(self) -> bool:
+        return self.severity == Severity.WARNING
+
+    @property
+    def is_error(self) -> bool:
+        return self.severity == Severity.ERROR
+
+    def __str__(self) -> str:
+        label = {0: "note", 1: "warning", 2: "error"}[self.severity]
+        return f"{label} {self.code}: {self.message}"
+
+
+class Report:
+    """What the translation could not do exactly, and why."""
+
+    def __init__(self, entries: List[Diagnostic]):
+        self._entries = entries
+
+    def __iter__(self):
+        return iter(self._entries)
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __repr__(self) -> str:
+        return f"<Report {len(self._entries)} entries, worst={self.worst}>"
+
+    @property
+    def entries(self) -> List[Diagnostic]:
+        return list(self._entries)
+
+    @property
+    def warnings(self) -> List[Diagnostic]:
+        return [e for e in self._entries if e.severity == Severity.WARNING]
+
+    @property
+    def errors(self) -> List[Diagnostic]:
+        return [e for e in self._entries if e.severity == Severity.ERROR]
+
+    @property
+    def worst(self) -> int:
+        return max((e.severity for e in self._entries), default=Severity.INFO)
+
+    @property
+    def ok(self) -> bool:
+        return self.worst < Severity.ERROR
+
+
+def _take_report(handle) -> Report:
+    """Read a dg_report out and free it. Always called, even on failure."""
+    lib = _library()
+    entries: List[Diagnostic] = []
+    if handle:
+        for i in range(lib.dg_report_count(handle)):
+            entries.append(
+                Diagnostic(
+                    severity=lib.dg_report_severity(handle, i),
+                    code=lib.dg_report_code(handle, i).decode(),
+                    message=lib.dg_report_message(handle, i).decode(),
+                )
+            )
+        lib.dg_report_free(handle)
+    return Report(entries)
+
+
+def _take_string(pointer) -> str:
+    """Read a char* the library allocated and hand it back to the library."""
+    if not pointer:
+        return ""
+    lib = _library()
+    text = ctypes.cast(pointer, ctypes.c_char_p).value or b""
+    lib.dg_string_free(pointer)
+    return text.decode()
+
+
+def _options(
+    carry_sidecar: bool = True,
+    derive_geometry: bool = True,
+    translate_scripts: bool = True,
+    strict: bool = False,
+    reencode_images: bool = False,
+    synthesise_ocean: bool = True,
+) -> Options:
+    opts = Options()
+    _library().dg_options_defaults(ctypes.byref(opts))
+    opts.carry_sidecar = int(carry_sidecar)
+    opts.derive_geometry = int(derive_geometry)
+    opts.translate_scripts = int(translate_scripts)
+    opts.strict = int(strict)
+    opts.reencode_images = int(reencode_images)
+    opts.synthesise_ocean = int(synthesise_ocean)
+    return opts
+
+
+class World:
+    """A loaded map, in neither game's layout but in the shared model."""
+
+    def __init__(self, handle, report: Report):
+        self._handle = handle
+        self._dict: Optional[Dict[str, Any]] = None
+        self.report = report
+
+    def __del__(self):
+        self.close()
+
+    def __enter__(self) -> "World":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if getattr(self, "_handle", None):
+            _library().dg_world_free(self._handle)
+            self._handle = None
+
+    def _require(self):
+        if not self._handle:
+            raise DragomanError("this world has already been closed")
+        return self._handle
+
+    def __repr__(self) -> str:
+        return (
+            f"<World {self.name!r} {len(self.provinces)} provinces "
+            f"{len(self.nations)} nations from {self.origin}>"
+        )
+
+    @property
+    def name(self) -> str:
+        return _library().dg_world_name(self._require()).decode()
+
+    @property
+    def origin(self) -> str:
+        return Format.name(_library().dg_world_origin(self._require()))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """The whole interchange model as plain Python data.
+
+        Parsed once and kept, because on a world map this is a few megabytes
+        of JSON and callers reach for `.provinces` in a loop.
+        """
+        if self._dict is None:
+            self._dict = json.loads(_take_string(_library().dg_world_to_json(self._require())))
+        return self._dict
+
+    @property
+    def provinces(self) -> List[Dict[str, Any]]:
+        return self.to_dict().get("provinces", [])
+
+    @property
+    def nations(self) -> List[Dict[str, Any]]:
+        return self.to_dict().get("nations", [])
+
+    @property
+    def events(self) -> List[Dict[str, Any]]:
+        return self.to_dict().get("events", [])
+
+    @property
+    def scripts(self) -> List[Dict[str, Any]]:
+        return self.to_dict().get("scripts", [])
+
+    def save(self, path: str, to: Union[int, str], **options) -> Report:
+        lib = _library()
+        opts = _options(**options)
+        handle = ctypes.c_void_p()
+        rc = lib.dg_save(
+            self._require(),
+            str(path).encode(),
+            Format.parse(to),
+            ctypes.byref(opts),
+            ctypes.byref(handle),
+        )
+        report = _take_report(handle)
+        if rc != 0:
+            raise DragomanError(lib.dg_last_error().decode(), report)
+        return report
+
+
+def library_version() -> str:
+    """The version of the shared library, which a wheel may outlive."""
+    return _library().dg_version_string().decode()
+
+
+def abi_version() -> int:
+    return _library().dg_abi_version()
+
+
+def detect(path: str) -> str:
+    """'odmap', 'gd5' or 'unknown', decided by content rather than by name."""
+    return Format.name(_library().dg_detect(str(path).encode()))
+
+
+def load(path: str, fmt: Union[int, str, None] = None, **options) -> World:
+    lib = _library()
+    opts = _options(**options)
+    handle = ctypes.c_void_p()
+    world = lib.dg_load(
+        str(path).encode(), Format.parse(fmt), ctypes.byref(opts), ctypes.byref(handle)
+    )
+    report = _take_report(handle)
+    if not world:
+        raise DragomanError(lib.dg_last_error().decode(), report)
+    return World(world, report)
+
+
+def convert(src: str, dst: str, to: Union[int, str, None] = None, **options) -> Report:
+    """Translate a map. With no `to`, converts to whichever format `src` is not."""
+    lib = _library()
+    if to is None:
+        found = _library().dg_detect(str(src).encode())
+        if found == Format.UNKNOWN:
+            raise DragomanError(f"cannot tell what {src} is; pass to='odmap' or to='gd5'")
+        to = Format.GD5 if found == Format.ODMAP else Format.ODMAP
+
+    opts = _options(**options)
+    handle = ctypes.c_void_p()
+    rc = lib.dg_convert(
+        str(src).encode(), str(dst).encode(), Format.parse(to), ctypes.byref(opts),
+        ctypes.byref(handle),
+    )
+    report = _take_report(handle)
+    if rc != 0:
+        raise DragomanError(lib.dg_last_error().decode(), report)
+    return report
+
+
+def roundtrip_check(path: str, to: Union[int, str, None] = None, **options):
+    """Convert to `to` and back; return (identical, report).
+
+    'Identical' means every province, nation, relation, claim, script and
+    carried file returned unchanged and the province raster hashes the same --
+    not that the two container files are byte-for-byte equal, which deflate
+    does not promise across implementations.
+    """
+    lib = _library()
+    if to is None:
+        found = lib.dg_detect(str(path).encode())
+        to = Format.GD5 if found == Format.ODMAP else Format.ODMAP
+
+    opts = _options(**options)
+    handle = ctypes.c_void_p()
+    rc = lib.dg_roundtrip_check(
+        str(path).encode(), Format.parse(to), ctypes.byref(opts), ctypes.byref(handle)
+    )
+    report = _take_report(handle)
+    if rc < 0:
+        raise DragomanError(lib.dg_last_error().decode(), report)
+    return rc == 1, report

dragoman/__main__.py

@@ -0,0 +1,139 @@
+"""The `dragoman` command, for people who installed with pip.
+
+The C++ build produces a command line tool of its own; this is the same set of
+subcommands over the same library, so that `pip install dragoman` gives a
+working command without anyone needing to know there is a binary underneath or
+where it went.
+
+    dragoman convert 1914.odmap base_maps/1914
+    dragoman roundtrip 1914.odmap
+    dragoman inspect 1914.odmap --json
+    dragoman detect some-file
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import DragomanError, Severity, __version__, abi_version, convert
+from . import detect as detect_format
+from . import library_version, load, roundtrip_check
+
+_LABEL = {Severity.INFO: "note", Severity.WARNING: "warning", Severity.ERROR: "error"}
+
+
+def _print_report(report, quiet: bool) -> int:
+    for entry in report:
+        if quiet and entry.severity == Severity.INFO:
+            continue
+        stream = sys.stdout if entry.severity == Severity.INFO else sys.stderr
+        print(f"  {_LABEL[entry.severity]:<7} {entry.code}: {entry.message}", file=stream)
+    return report.worst
+
+
+def _options(args) -> dict:
+    return {
+        "carry_sidecar": not args.no_sidecar,
+        "derive_geometry": not args.no_geometry,
+        "translate_scripts": not args.no_scripts,
+        "synthesise_ocean": not args.no_ocean,
+        "strict": args.strict,
+    }
+
+
+def _add_common(parser) -> None:
+    parser.add_argument("--no-sidecar", action="store_true",
+                        help="do not carry what the target format cannot hold")
+    parser.add_argument("--no-geometry", action="store_true",
+                        help="do not derive adjacency, centres or the land/sea mask")
+    parser.add_argument("--no-scripts", action="store_true",
+                        help="do not translate scripts or scripted events")
+    parser.add_argument("--no-ocean", action="store_true",
+                        help="do not invent sea provinces for a game that draws none")
+    parser.add_argument("--strict", action="store_true",
+                        help="treat any warning as a failure")
+    parser.add_argument("--quiet", action="store_true", help="warnings and errors only")
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="dragoman",
+        description="Translate maps between Open Doctrines and Greater Diplomacy 5.",
+        epilog="Documentation: https://github.com/Pr1nted/dragoman/wiki",
+    )
+    parser.add_argument("--version", action="store_true", help="print versions and exit")
+    sub = parser.add_subparsers(dest="command")
+
+    p = sub.add_parser("convert", help="convert a map to the other format")
+    p.add_argument("input")
+    p.add_argument("output")
+    p.add_argument("--to", choices=["odmap", "gd5"],
+                   help="target format; inferred from the source when omitted")
+    _add_common(p)
+
+    p = sub.add_parser("roundtrip", help="convert to the other format and back, and compare")
+    p.add_argument("map")
+    p.add_argument("--to", choices=["odmap", "gd5"])
+    _add_common(p)
+
+    p = sub.add_parser("inspect", help="summarise a map, or dump the whole model")
+    p.add_argument("map")
+    p.add_argument("--json", action="store_true", help="print the interchange model")
+
+    p = sub.add_parser("detect", help="say what a file is: odmap, gd5, or unknown")
+    p.add_argument("path")
+
+    args = parser.parse_args(argv)
+
+    if args.version or args.command is None:
+        if args.version:
+            print(f"dragoman {__version__} (library {library_version()}, abi {abi_version()})")
+            return 0
+        parser.print_help()
+        return 2
+
+    try:
+        if args.command == "detect":
+            found = detect_format(args.path)
+            print(found)
+            return 1 if found == "unknown" else 0
+
+        if args.command == "inspect":
+            with load(args.map) as world:
+                if args.json:
+                    print(json.dumps(world.to_dict(), indent=1))
+                else:
+                    print(world.name)
+                    print(f"  format     {world.origin}")
+                    print(f"  provinces  {len(world.provinces)}")
+                    print(f"  nations    {len(world.nations)}")
+                    print(f"  scripts    {len(world.scripts) + len(world.events)}")
+            return 0
+
+        if args.command == "convert":
+            report = convert(args.input, args.output, to=args.to, **_options(args))
+            if not args.quiet:
+                print(f"converted {args.input} -> {args.output}")
+            return 1 if _print_report(report, args.quiet) >= Severity.ERROR else 0
+
+        if args.command == "roundtrip":
+            identical, report = roundtrip_check(args.map, to=args.to, **_options(args))
+            print("round trip preserved every modelled field and the province raster"
+                  if identical else "round trip changed the map -- see below")
+            _print_report(report, args.quiet)
+            return 0 if identical else 1
+
+    except DragomanError as exc:
+        print(f"dragoman: {exc}", file=sys.stderr)
+        if exc.report is not None:
+            _print_report(exc.report, quiet=False)
+        return 1
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dragoman/_ffi.py

@@ -0,0 +1,129 @@
+"""Finding and declaring the shared library.
+
+ctypes rather than a compiled extension on purpose. Greater Diplomacy 5 is a
+pygame project whose players install it by unzipping it, and asking that
+audience for a C compiler to convert a map is asking too much. ctypes needs
+only the .so/.dylib/.dll, which CI builds for each platform and the wheel
+carries.
+
+The search order is: an explicit DRAGOMAN_LIBRARY, then a copy shipped inside
+this package (how a wheel is laid out), then a CMake build tree beside the
+checkout (how a contributor runs it), then the system loader.
+"""
+
+import ctypes
+import os
+import sys
+from pathlib import Path
+
+_LIB_NAMES = {
+    "win32": ["dragoman.dll", "libdragoman.dll"],
+    "darwin": ["libdragoman.dylib"],
+}
+_DEFAULT_NAMES = ["libdragoman.so"]
+
+
+def _candidate_names():
+    return _LIB_NAMES.get(sys.platform, _DEFAULT_NAMES)
+
+
+def _candidate_paths():
+    override = os.environ.get("DRAGOMAN_LIBRARY")
+    if override:
+        yield Path(override)
+
+    here = Path(__file__).resolve().parent
+    for name in _candidate_names():
+        yield here / name
+
+    # A CMake build tree beside the repository, which is what a contributor
+    # who just ran `cmake --build build` has.
+    repo = here.parents[2]
+    for build in ("build", "cmake-build-debug", "cmake-build-release", "out"):
+        for name in _candidate_names():
+            yield repo / build / name
+            yield repo / build / "Release" / name
+            yield repo / build / "Debug" / name
+
+
+def load_library():
+    tried = []
+    for path in _candidate_paths():
+        tried.append(str(path))
+        if path.exists():
+            return ctypes.CDLL(str(path))
+
+    # Last resort: let the platform loader look on its own search path.
+    for name in _candidate_names():
+        try:
+            return ctypes.CDLL(name)
+        except OSError:
+            tried.append(name)
+
+    raise OSError(
+        "could not find the dragoman shared library. Build it with\n"
+        "    cmake -S . -B build && cmake --build build\n"
+        "or set DRAGOMAN_LIBRARY to its path. Looked in:\n  "
+        + "\n  ".join(tried)
+    )
+
+
+class Options(ctypes.Structure):
+    _fields_ = [
+        ("carry_sidecar", ctypes.c_int),
+        ("derive_geometry", ctypes.c_int),
+        ("translate_scripts", ctypes.c_int),
+        ("strict", ctypes.c_int),
+        ("reencode_images", ctypes.c_int),
+        ("synthesise_ocean", ctypes.c_int),
+    ]
+
+
+def declare(lib):
+    """Give every symbol its signature.
+
+    Without this ctypes assumes an int return, which silently truncates a
+    64-bit pointer on the first call that returns a handle -- the failure
+    looks like a corrupt map rather than a binding mistake, so it is worth
+    being exhaustive here.
+    """
+    c = ctypes
+    p = c.c_void_p
+    s = c.c_char_p
+
+    sigs = {
+        "dg_version_string": ([], s),
+        "dg_version_major": ([], c.c_int),
+        "dg_version_minor": ([], c.c_int),
+        "dg_version_patch": ([], c.c_int),
+        "dg_abi_version": ([], c.c_int),
+        "dg_format_name": ([c.c_int], s),
+        "dg_detect": ([s], c.c_int),
+        "dg_options_defaults": ([c.POINTER(Options)], None),
+        "dg_load": ([s, c.c_int, c.POINTER(Options), c.POINTER(p)], p),
+        "dg_save": ([p, s, c.c_int, c.POINTER(Options), c.POINTER(p)], c.c_int),
+        "dg_convert": ([s, s, c.c_int, c.POINTER(Options), c.POINTER(p)], c.c_int),
+        "dg_roundtrip_check": ([s, c.c_int, c.POINTER(Options), c.POINTER(p)], c.c_int),
+        "dg_world_free": ([p], None),
+        "dg_world_province_count": ([p], c.c_int),
+        "dg_world_nation_count": ([p], c.c_int),
+        "dg_world_script_count": ([p], c.c_int),
+        "dg_world_name": ([p], s),
+        "dg_world_origin": ([p], c.c_int),
+        "dg_world_to_json": ([p], p),
+        "dg_world_from_json": ([s, c.POINTER(p)], p),
+        "dg_report_count": ([p], c.c_int),
+        "dg_report_severity": ([p, c.c_int], c.c_int),
+        "dg_report_code": ([p, c.c_int], s),
+        "dg_report_message": ([p, c.c_int], s),
+        "dg_report_worst": ([p], c.c_int),
+        "dg_report_to_json": ([p], p),
+        "dg_report_free": ([p], None),
+        "dg_string_free": ([p], None),
+        "dg_last_error": ([], s),
+    }
+    for name, (argtypes, restype) in sigs.items():
+        fn = getattr(lib, name)
+        fn.argtypes = argtypes
+        fn.restype = restype
+    return lib

dragoman/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

open_dragoman-0.2.2.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.2
+Name: open-dragoman
+Version: 0.2.2
+Summary: Translate maps between Open Doctrines and Greater Diplomacy 5
+Keywords: grand-strategy,map,conversion,opendoctrines,greater-diplomacy,modding
+Author: Dragoman contributors
+License: MIT License
+         
+         Copyright (c) 2026 Dragoman contributors
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+         
+         ---
+         
+         Dragoman is an independent implementation, written from observing the two file
+         formats it converts between. No source code from either game is included in or
+         derived into it.
+         
+         The games themselves remain under their own licences, and neither project's
+         maps are redistributed here:
+         
+           Open Doctrines        OpenDoctrines Non-Commercial License
+           Greater Diplomacy 5   GNU General Public License v3.0
+                                 https://github.com/GitGetGot415/Greater-Diplomacy-5
+         
+         Vendored third-party code, all permissively licensed:
+         
+           third_party/miniz     miniz 11.3.1, MIT
+                                 https://github.com/richgel999/miniz
+           third_party/stb       stb_image / stb_image_write, MIT or public domain
+                                 https://github.com/nothings/stb
+           third_party/json      nlohmann/json 3.11.3, MIT
+                                 https://github.com/nlohmann/json
+         
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: File Formats
+Project-URL: Homepage, https://github.com/Pr1nted/dragoman
+Project-URL: Documentation, https://github.com/Pr1nted/dragoman/wiki
+Project-URL: Changelog, https://github.com/Pr1nted/dragoman/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Pr1nted/dragoman/issues
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Dragoman
+
+Translate maps between **Open Doctrines** (`.odmap`) and **Greater Diplomacy 5**
+(map directories), in both directions, losing as little as the two formats
+allow — and nothing at all on a round trip.
+
+A *dragoman* was the interpreter attached to an embassy: the person through
+whom two powers who shared no language could nonetheless sign something. This
+is that, for map files.
+
+```bash
+pip install open-dragoman
+
+dragoman convert 1914.odmap base_maps/1914 --to gd5
+dragoman convert base_maps/GD4 gd4.odmap   --to odmap
+dragoman roundtrip 1914.odmap              # prove nothing was lost
+```
+
+```python
+import dragoman
+
+dragoman.convert("1914.odmap", "base_maps/1914", to="gd5")
+
+world = dragoman.load("1914.odmap")
+print(world.name, len(world.provinces), "provinces")
+```
+
+**[Read the wiki →](https://github.com/Pr1nted/dragoman/wiki)** — what it is,
+how to use it, what every message means, and what it cannot do.
+
+## Status
+
+Every map both games ship round-trips without losing a single modelled field:
+
+| Suite | Result |
+|---|---|
+| Greater Diplomacy 5 maps (12 base maps + 16 scenarios) | **28 / 28** |
+| Open Doctrines maps (5 scenarios + the world map) | **6 / 6** |
+| Unit tests (raster, scripts, ABI, versioning, round trip) | **5 / 5** |
+
+Verified against Open Doctrines and against
+[GitGetGot415/Greater-Diplomacy-5](https://github.com/GitGetGot415/Greater-Diplomacy-5).
+Reproduce with `python3 tools/conformance.py <directory of maps>`.
+
+Converted maps have also been **played in both games**, not merely loaded by
+this library. Open Doctrines' world map converted to GD5 boots through GD5's
+own `Controller` and `Map` state with all 23 screens, its flags drawn, its
+oceans navigable and every province centre inside its own province; a GD5 map
+converted to Open Doctrines plays five AI turns under `OpenDoctrines
+--simulate`. Nearly everything this library gets right, it gets right because
+somebody opened the result in the game and looked at it — the flag encoding,
+the ocean, the political layer's colour key and the province-border fill were
+all found that way.
+
+One thing crossing to Open Doctrines still needs a human: GD5 starts its
+nations with an empty stockpile and Open Doctrines expects a starting
+endowment, so a converted map bankrupts its world on the first turn unless
+treasuries are set. Reported as `od.treasury` rather than guessed at.
+
+## What "lossless" means here
+
+The two games are not the same game, so a straight translation always loses
+something: Open Doctrines models a province's population, its port and its
+ethnic minorities, and GD5 has no field for any of them; GD5 models terrain,
+province adjacency, unit rosters and research, and Open Doctrines has no field
+for those.
+
+Dragoman writes the difference down. Everything the destination cannot hold
+goes into a **sidecar** beside the map — `dragoman_sidecar/` in a GD5
+directory, `dragoman/` inside a `.odmap` archive. Both games read a fixed list
+of filenames and ignore everything else, so the sidecar is invisible to them
+and costs the converted map nothing.
+
+The result:
+
+- **Converting one way** is as faithful as the target format permits, and every
+  approximation is reported by a stable code you can act on.
+- **Converting back** restores what the target could not hold. `A → B → A` keeps
+  every province, nation, relation, claim, core, script and carried file, and
+  the province raster hashes identical.
+
+`dragoman roundtrip <map>` asserts exactly that. Pass `--no-sidecar` for a
+smaller, genuinely lossy conversion — the round trip then fails, on purpose.
+
+Not promised: byte-identical container files. Two zip archives holding
+identical members are different files, because deflate is not reproducible
+across implementations, and Open Doctrines packs with Python's zlib while this
+packs with miniz. Every file *inside* is preserved exactly.
+
+## What crosses
+
+| | Open Doctrines | Greater Diplomacy 5 |
+|---|---|---|
+| Province raster | `provinces.png`, id packed big-endian | `id_map.png`, id packed little-endian |
+| Province identity | preserved exactly — the rasters differ only by swapping red and blue |||
+| Owner, name, claims | ✅ | ✅ |
+| Cores | — | ✅ (carried) |
+| Sea provinces | — (**synthesised** for GD5) | ✅ |
+| Population, ports, fortification | ✅ | — (carried) |
+| Minorities, political compass, policies | ✅ | — (carried) |
+| Terrain, adjacency, province centres | — (**derived** from the raster) | ✅ |
+| Units, buildings, research, factions | — (armies carried) | ✅ |
+| Flags | a PNG in the archive | raw 60x40 pixels, base64 |
+| Relations | ally, non-aggression, guarantee | war and alliance only (rest carried) |
+| Scripts | imperative `#OD/MapEngine/1` | declarative scripted events |
+
+Adjacency and centroids are computed from the province raster when converting
+to GD5, since Open Doctrines derives both at load and never stores them. The
+centroid finder deliberately handles crescent-shaped provinces, whose mean
+pixel falls outside themselves.
+
+Full field-by-field detail: [docs/mapping.md](docs/mapping.md).
+
+## Scripts
+
+Open Doctrines' scripting is imperative and line-based, with loops and
+`waitUntil` suspension points. GD5's is a list of declarative events, each a
+set of conditions and a set of actions. The overlap is the shape both express:
+a gate, and things that happen when it opens.
+
+An Open Doctrines script written as top-level `waitUntil` stages becomes GD5
+events, one stage at a time. A GD5 event becomes an entry script with a
+`waitUntil` and some `set` lines. Anything outside that overlap — a `foreach`
+over a country's provinces, conditions chained with `XOR` — is reported by name
+and carried unchanged rather than half-translated. GD5 event types this library
+has never heard of pass through untouched, so a GD5 → OD → GD5 trip is lossless
+even for conditions added to the game after this was written.
+
+Details and the full vocabulary: [docs/scripting.md](docs/scripting.md).
+
+## Installing
+
+```bash
+pip install open-dragoman
+```
+
+The wheel carries the compiled library inside the package, so there is no
+compiler needed at install time and nothing to locate afterwards. You get both
+the Python API and a `dragoman` command.
+
+Prebuilt binaries for people who want nothing to do with Python are attached to
+each [release](https://github.com/Pr1nted/dragoman/releases). The full set of
+options — release archives, source builds, CMake `FetchContent` — is on
+[the Installing page](https://github.com/Pr1nted/dragoman/wiki/Installing).
+
+## Building from source
+
+Needs CMake 3.16 and a C++17 compiler. There are no external dependencies —
+miniz, stb and nlohmann/json are vendored, all MIT or public domain.
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+This produces `libdragoman.a`, a shared `libdragoman.{so,dylib,dll}`, and the
+`dragoman` command line tool.
+
+## Using it from your language
+
+The core is C++17 behind a flat **C99 ABI**, so anything with an FFI can call
+it. The whole interchange model is available as JSON through
+`dg_world_to_json`, which is how a binding reads or edits a map without needing
+an accessor per field.
+
+- **C** — `#include <dragoman/dragoman.h>`, link `dragoman`. See
+  [bindings/c/example.c](bindings/c/example.c).
+- **C++** — `#include <dragoman/dragoman.hpp>` for an RAII wrapper over the same
+  ABI. See [bindings/cpp/example.cpp](bindings/cpp/example.cpp).
+- **Python** — `pip install open-dragoman`. Pure ctypes, and the wheel carries the
+  library, so no compiler is needed at install time.
+- **Anything else** — Rust, Go, C#, Java, Lua and WebAssembly all bind the same
+  header. [docs/abi.md](docs/abi.md) documents the contract.
+
+## Versioning
+
+Two numbers that move for different reasons:
+
+- **Library version** (`VERSION`, semver) — the release. Currently `0.2.0`.
+- **ABI version** (`DRAGOMAN_ABI_VERSION`) — bumped only when an existing symbol
+  changes meaning, so a binding can refuse to load a library it cannot speak to
+  without parsing semver.
+
+The version lives in `VERSION` and is mirrored into the C header, the Python
+package and the CMake project. `tools/check_version.py` and
+`tests/test_version.cpp` both fail if any copy drifts, and CI runs them on every
+push. Details: [docs/versioning.md](docs/versioning.md).
+
+## Licence
+
+Dragoman is MIT. It is an independent implementation written from observing
+both file formats; no code from either game is copied into it. Open Doctrines
+and Greater Diplomacy 5 remain under their own licences (Open Doctrines
+Non-Commercial, and GPL-3.0 respectively), and neither project's maps are
+redistributed here.

open_dragoman-0.2.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+dragoman/__init__.py,sha256=jlYzSX1zdfBMNDsoqWJFlR42WCqQdE2PoKyrSWH5A4M,10497
+dragoman/__main__.py,sha256=y6JHFD8TiG3h652J1KR9X3fjZXdClBg_0xJwWEBeQxQ,5473
+dragoman/_ffi.py,sha256=vz9PiWxmYP0GFE6G-1QKSIAbzfsLhKuJhIuopH_TdMQ,4528
+dragoman/_version.py,sha256=anBcPGggCP0f-o9w0IsZYV49rl6HvJbHcuDN39x3mxw,23
+dragoman/dragoman.dll,sha256=MUcqF4m-RpBmYyiMIZIPWWdXoEfGElACZjKRS3LrNvk,703488
+open_dragoman-0.2.2.dist-info/METADATA,sha256=lYx8oAoVnQglETSoL69a4S_v2TxY1-nEeohB5cAI9KU,12004
+open_dragoman-0.2.2.dist-info/WHEEL,sha256=k8ugwGhXAI0--PEoWE0F6sXc-nX2zbZqyTgxRg_imsk,102
+open_dragoman-0.2.2.dist-info/entry_points.txt,sha256=oSIpRxsoPRA5OKPlIPTg4zOt1N937ZUMEyocpf9oIY8,53
+open_dragoman-0.2.2.dist-info/licenses/LICENSE,sha256=P7RsI-F89-a0HjEqhSpzC_oMu9Bii2KZT4r8k__7Gx0,1997
+open_dragoman-0.2.2.dist-info/RECORD,,

open_dragoman-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 1.0.3
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

open_dragoman-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dragoman = dragoman.__main__:main
+

open_dragoman-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,43 @@
+MIT License
+
+Copyright (c) 2026 Dragoman contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Dragoman is an independent implementation, written from observing the two file
+formats it converts between. No source code from either game is included in or
+derived into it.
+
+The games themselves remain under their own licences, and neither project's
+maps are redistributed here:
+
+  Open Doctrines        OpenDoctrines Non-Commercial License
+  Greater Diplomacy 5   GNU General Public License v3.0
+                        https://github.com/GitGetGot415/Greater-Diplomacy-5
+
+Vendored third-party code, all permissively licensed:
+
+  third_party/miniz     miniz 11.3.1, MIT
+                        https://github.com/richgel999/miniz
+  third_party/stb       stb_image / stb_image_write, MIT or public domain
+                        https://github.com/nothings/stb
+  third_party/json      nlohmann/json 3.11.3, MIT
+                        https://github.com/nlohmann/json