Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/content/docs/docs/development/python.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ It is schema-dist's own [folder checker](/docs/schema/folders#rules-for-tools),
## What it covers

- **World folders**: `read_folder` and `write_folder` implement the folder format (v0.3.24 since 0.126.0, `FORMAT_VERSION`; a folder's existing stamp is kept, older stamps read as before). A world's `origin` is carried as given, from `GET /world` or a read `world.json`, and never derived. An export writes the [`producer` line](/docs/schema/folders#worldjson) as the folder's maker (`{"tool": "onlyworlds", "version", "input": "server"}`); a tool that runs the export in its own name passes `producer=` with its own line. A folder written from another folder keeps the line it carries. Since 0.37.0 `push` sends nothing for an element whose folder copy carries `hidden: true` while the server's does not, and names it in `PushResult.hidden`: the server takes the hidden mark only through its own route, so a patch would edit an element every reader still sees. `patch_world` never sends the folder-only keys (`format_version`, `source`, `exported_as`, `producer`, `writable`, `api`, `snapshot_*`) and pass its shared conformance fixture. Since 0.9.0 a [known-of](/docs/schema/folders#known-of-elements) stub is written without its unset fields (since 0.10.0 with every field it was served with a value, such as a Character's public fields; `PUBLIC_FIELDS` lists them per type), flagged on read (`folder.known_of`, `is_known_of`), never pushed (`PushPlan.known_of` lists it), and refused by the client's writes before anything is sent. The reader never changes a folder. It skips a file that is not JSON, not an object or has no `id`, and since 0.5.1 a dot-prefixed file in a type folder (a tool's litter, not an element); `folder.skipped` lists each with the reason. An element found in both the current `elements/` layout and Atlas's older `spatial/` one is served from `elements/`, and `folder.in_both_layouts` lists it (since 0.5.0).
- **Archives** (since 0.17.0): `read_world_file(path_or_bytes)` opens a `.owworld` file as the [folder format](/docs/schema/folders#folders-and-onlyworldscom)'s archive rules say (the directory checked before anything is inflated; a refusal is `WorldFileError` with `reason` one of the twelve causes, under the same names as the TypeScript SDK's; since 0.45.1 two names that are one after NFC and simple case folding are compared at Unicode 15.1, built from Unicode's own files rather than the interpreter's, and the NFC is exported as `onlyworlds.worldfile.nfc`) and `.to_folder(dest)` writes it out as a folder; `write_world_file(folder, path, top_dir=None, private_dir=None)` and `world_file_bytes(folder)` write one: the `mimetype` marker first and stored, every entry stamped 1980-01-01 in UTF-8 byte order, only `world.json`, `elements/`, `spatial/`, `media/`, `records/` and the one dot-folder named in `private_dir`, the same folder giving the same bytes (within one zlib build). From 0.32.0 the records a producer marks `"private": true` in `records/RECORDS.json` stay home: left out whole, `RECORDS.json` kept as it is, unless `include_private_records=True`; a manifest it cannot read raises `ValueError` unless you pass that ([private records](/docs/schema/folders#folders-and-onlyworldscom)). From 0.43.0 both take `include_hidden=True`: a world file is a copy, and a [hidden](/docs/development/api/hidden) element's file travels byte for byte. For a file made to hand to someone else, `include_hidden=False` leaves every element file (one directly in a type folder of `elements/` or `spatial/`, since 0.90.1 only those) whose JSON object carries the mark out whole, nothing else rewritten (a link to it keeps the id, which dangles); a list passed as `hidden_left_out=` receives the left-out files' paths, sorted, so its length is the count. From 0.90.0 a world file leaves out who wrote each element: `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors` leave every element file that holds them, which is written in the folder's own form (two-space indent, a trailing newline, its other keys in their order); `include_author_fields=True` writes every file byte for byte, for an archive of your own world. The package's own test runs the 99-case conformance set from its schema pin; the directory it writes matches the TypeScript writer's entry for entry.
- **Archives** (since 0.17.0): `read_world_file(path_or_bytes)` opens a `.owworld` file as the [folder format](/docs/schema/folders#folders-and-onlyworldscom)'s archive rules say (the directory checked before anything is inflated; a refusal is `WorldFileError` with `reason` one of the twelve causes, under the same names as the TypeScript SDK's; since 0.45.1 two names that are one after NFC and simple case folding are compared at Unicode 15.1, built from Unicode's own files rather than the interpreter's, and the NFC is exported as `onlyworlds.worldfile.nfc`) and `.to_folder(dest)` writes it out as a folder; `write_world_file(folder, path, top_dir=None, private_dir=None)` and `world_file_bytes(folder)` write one: the `mimetype` marker first and stored, every entry stamped 1980-01-01 in UTF-8 byte order, only `world.json`, `elements/`, `spatial/`, `media/`, `records/` and the one dot-folder named in `private_dir`, the same folder giving the same bytes (within one zlib build). From 0.32.0 the records a producer marks `"private": true` in `records/RECORDS.json` stay home: left out whole, `RECORDS.json` kept as it is, unless `include_private_records=True`; a manifest it cannot read raises `ValueError` unless you pass that ([private records](/docs/schema/folders#folders-and-onlyworldscom)). From 0.43.0 both take `include_hidden=True`: a world file is a copy, and a [hidden](/docs/development/api/hidden) element's file travels byte for byte. For a file made to hand to someone else, `include_hidden=False` leaves every element file (one directly in a type folder of `elements/` or `spatial/`, since 0.90.1 only those) whose JSON object carries the mark out whole, nothing else rewritten (a link to it keeps the id, which dangles); a list passed as `hidden_left_out=` receives the left-out files' paths, sorted, so its length is the count. From 0.90.0 a world file leaves out who wrote each element: `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors` leave every element file that holds them, which is written in the folder's own form (two-space indent, a trailing newline, its other keys in their order); `include_author_fields=True` writes every file byte for byte, for an archive of your own world. The package's own test runs the conformance set from its schema pin; the directory it writes matches the TypeScript writer's entry for entry.
- **Import from other apps**: importers for Campfire, Kanka, LegendKeeper, Notion and World Anvil read each app's export into a world folder (LegendKeeper's also through its API), as `python -m onlyworlds.<app>` or from Python as `import_campfire`, `import_kanka`, `import_legendkeeper`, `import_notion` and `import_worldanvil`. Each has its own section on [Import from other apps](/docs/development/python-import).
- **The calendar profile** (since 0.68.0): `onlyworlds.calendar` reads a world's own calendars as the [calendar profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/calendar.md) defines them. `read_calendar_value(raw)` reads an `atlas_calendar` value (an object, or the same object as a JSON string) and gives `None` for anything the profile refuses; `world_calendars(elements)` finds every calendar in a world by the field, and `resolve_calendar` picks the one to read dates through (named `resolve_calendar_lens` before 0.69.0; the old name still answers, with a deprecation warning). `breakdown_step(cfg, step)` and `format_step(cfg, step)` turn an integer step into the calendar's date (months, days outside the months, weekdays, eras, and version 2's leap exceptions and offset), and `parse_date(cfg, text)` reads written words back to a step. It is the [TypeScript SDK](/docs/development/typescript)'s calendar reader under snake_case names, gives the same answers (both replay the profile's fixture, and the two were compared on 175,705 inputs before the release), and reads the calendars the LegendKeeper door writes.
- **The lens profile** (since 0.74.0): `resolve_lens(world, lens, reader, as_of=, clock=)` reads a world through a lens for one reader (the kept elements in order, the cut by reason, the mail part), with `is_lens`, `is_template` and `lenses_in_use`, as [Lenses](/docs/lenses) describes. Since 0.77.0, `world_graph(world, reader, *, lens=None, as_of=None, clock=None, rooms=False, hidden=False, proposed=False, map_space=False, reading_aids=False)` (`reading_aids` since 0.103.0: the charter, its guide and its domains back in a graph without a lens, each marked `reading_aid`) reads the same snapshot as nodes and edges, with `edges_cut` counting by reason the links it leaves out; a refused flag raises `ValueError` naming it. Since 0.78.0, `degree_of(graph)` gives each node's count of edges, in or out: rank by it for "most linked". Since 0.79.0, `DATE_FIELD` is the profile's date table and `date_of(el)` an element's date as that table reads it (the whole number in its type's date field, else `None`), so a timeline dates elements exactly as the lens's fence does. Since 0.82.0 a lens's rows for a reader below the owner are the bodies the API serves that reader, the owner's the bodies as stored; since 0.82.1 a contributor's or a guest's row keeps a link to a proposed element it sees, and a lens's note keyed to one, the public rung loses both, and no row carries a stored `x_served_trimmed`.
Expand Down
Loading
Loading