sl2.jsonout Namespace Reference

Functions
	meta_key (key)
	Normalise a CLI metadata key: lowercase, spaces and dashes to underscores.
	parse_meta (pairs, path=None)
	Build the environment block from repeated --meta key=value arguments and an optional JSON file.
	jsonable (value)
	Make a parsed value safe for json.dump, without changing what it says.
	character_json (slot_no, ch, report=None)
	One character as a JSON object: its slot number, then every field the parse actually set.
	build_json (save, filename, meta=None, validate=False, data=None)
	Build the whole JSON document for a parsed save.

Variables
str	SCHEMA_URL = "https://sl2-analyzer.darthdemono.com/schema.json"
	Where the schema is published.
str	SCHEMA_VERSION = "1.3.0"
	Schema version, semver.
tuple	KNOWN_META
	Environment keys the schema names explicitly.

Detailed Description

JSON output: the same parsed save the Markdown writer gets, as a machine-readable
document against a published schema.

The Markdown is written for a person (or an LLM) to read; this is written for a
program. Both start from `parse_save`, so a field can never say one thing in one
format and something else in the other.

Two rules shape the document. Nothing is invented to fill a hole — a field the save
does not carry is simply absent, exactly as in the Markdown, so a consumer can tell
"not in this game" from "zero". And nothing about the machine that produced it is
guessed: the environment block holds only what the caller passed on the command line.

Function Documentation

meta_key()

sl2.jsonout.meta_key

(

key

)

Normalise a CLI metadata key: lowercase, spaces and dashes to underscores.

"Proton version" and "proton-version" are the same key. The value is left exactly as typed — only the key is canonicalised, because the key is what a consumer looks up.

Parameters

key	Raw key as typed.

Returns

The canonical form.

Definition at line 56 of file jsonout.py.

Referenced by sl2.jsonout.parse_meta().

Here is the caller graph for this function:

parse_meta()

sl2.jsonout.parse_meta	(		pairs,
			path = None
	)

Build the environment block from repeated --meta key=value arguments and an optional JSON file.

A key given more than once becomes a LIST, in the order given — that is how --meta dlc=X --meta dlc=Y says two DLCs, with no comma-splitting guesswork (item and boss names are full of commas, so splitting on one would be a bug waiting). The JSON file is merged first so an explicit --meta on the command line wins.

Parameters

pairs	List of "key=value" strings, or None.
path	Path to a JSON object to merge underneath, or None.

Returns

An OrderedDict, empty when nothing was passed.

Exceptions

ValueError

on an argument with no "=", or a JSON file that is not an object.

Definition at line 71 of file jsonout.py.

References sl2.jsonout.meta_key().

Here is the call graph for this function:

jsonable()

sl2.jsonout.jsonable

(

value

)

Make a parsed value safe for json.dump, without changing what it says.

The parser uses sets for boss evidence and tuples for fixed-shape rows; both become lists, and a set is sorted so two runs of the same save produce the same bytes. Everything else passes through untouched.

Definition at line 100 of file jsonout.py.

References sl2.jsonout.jsonable().

Referenced by sl2.jsonout.character_json(), and sl2.jsonout.jsonable().

Here is the call graph for this function:

Here is the caller graph for this function:

character_json()

sl2.jsonout.character_json	(		slot_no,
			ch,
			report = None
	)

One character as a JSON object: its slot number, then every field the parse actually set.

Absent stays absent. The keys are the parser's own, which is deliberate — the Markdown, the web app and this document all name a field the same thing.

Parameters

slot_no	1-based slot number.
ch	The character dict.
report	A validation validators.models.Report, or None when the caller did not ask for one. It is emitted whole — findings, the rule count and the unimplemented list — because a consumer reading "no findings" is entitled to the same caveat the Markdown prints.

Definition at line 120 of file jsonout.py.

References sl2.jsonout.jsonable().

Referenced by sl2.jsonout.build_json().

Here is the call graph for this function:

Here is the caller graph for this function:

build_json()

sl2.jsonout.build_json	(		save,
			filename,
			meta = None,
			validate = False,
			data = None
	)

Build the whole JSON document for a parsed save.

Parameters

save	A sl2.convert.SaveData.
filename	The source filename, recorded so an export can be traced back.
meta	The environment block from parse_meta, or None.
validate	Attach each character's validation report (off by default).
data	The file bytes, when the caller has them: the file-level rules read the container rather than a character.

Returns

A dict ready for json.dump.

Definition at line 140 of file jsonout.py.

References sl2.jsonout.character_json().

Here is the call graph for this function:

Variable Documentation

SCHEMA_URL

str sl2.jsonout.SCHEMA_URL = "https://sl2-analyzer.darthdemono.com/schema.json"

Where the schema is published.

Static file at the site root, so a consumer can resolve it without cloning anything.

Definition at line 27 of file jsonout.py.

SCHEMA_VERSION

str sl2.jsonout.SCHEMA_VERSION = "1.3.0"

Schema version, semver.

MINOR for a new optional field, MAJOR for anything that would break a reader which trusted the previous shape.

Definition at line 31 of file jsonout.py.

KNOWN_META

tuple sl2.jsonout.KNOWN_META

Initial value:

=  (
    "source",
    "version",
    "dlc",
    "os",
    "launcher",
    "proton",
    "gamemode",
    "mangohud",
    "notes",
)

Environment keys the schema names explicitly.

Any other key is still accepted and written through — this list is what gets documented and type-checked, not a whitelist. The point of the block is that a save alone cannot tell you which store sold the game, which patch it ran, or what it ran under.

Definition at line 37 of file jsonout.py.