Command line#

The scenet command. See the CLI reference for the interface itself; this page documents the functions behind it.

scenet.cli#

Command-line entry point.

scenet.cli.build_parser()[source]#

Build the argument parser for the scenet command.

Exposed separately from main so that tests, shell-completion generators and documentation tooling can inspect the interface without running it.

Return type:

ArgumentParser

Returns:

A parser with the build, check, schema and mcp subcommands defined.

scenet.cli.run_build(args)[source]#

Run a one-shot build or keep rebuilding while compilation inputs change.

Return type:

int

scenet.cli.run_check(args)[source]#

Run the check subcommand: validate documents and report what is wrong.

Parameters:

args (Namespace) – Parsed arguments from build_parser.

Return type:

int

Returns:

A process exit status – 0 when no document has an error (notes may have been printed), 1 when any has one, 2 when a file does not exist or has an extension no frontend reads.

Unlike build, this never stops at the first fault. pydantic reports every field error at once and a run over several files reports all of them, because a caller fixing them – a person or an agent – wants the whole list, not one round trip per mistake.

scenet.cli.run_schema(args)[source]#

Emit the panel JSON Schema.

Generated from the pydantic models rather than hand-written, so editor completion is derived from the compiler’s own definition of the language and the two cannot disagree. It describes the syntax as written, not the IR it normalises into; see scenet.schema.

Return type:

int

scenet.cli.run_mcp(args)[source]#

Run the mcp subcommand: serve the tools until the client disconnects.

Parameters:

args (Namespace) – Parsed arguments from build_parser.

Return type:

int

Returns:

A process exit status – 0 once the client has gone, 2 when the optional mcp dependency is not installed.

Nothing is printed to stdout, before or after: on the stdio transport stdout is the protocol stream. The server module is imported here rather than at the top of the file, so every other command works without the extra installed.

scenet.cli.main(argv=None)[source]#

Entry point for the scenet command.

Parameters:

argv (Sequence[str] | None) – Arguments to parse. Defaults to sys.argv[1:], which is what happens when the installed console script runs; pass a list explicitly from tests.

Return type:

int

Returns:

A process exit status. 0 on success, 1 for a document that will not compile, 2 for a usage error or a missing file.

Example

>>> from scenet.cli import main
>>> main(["--definitely-not-a-flag"])
Traceback (most recent call last):
  ...
SystemExit: 2

scenet.watch#

Dependency-aware watch mode for the build command.

class scenet.watch.WatchSession[source]#

Bases: object

What one watch keeps between polls: a file watcher, and each file’s stat and hash.

__init__(*, now=<built-in function time_ns>, sleep=<built-in function sleep>, read=<function Path.read_bytes>)[source]#

Start a session with no watcher open and nothing hashed yet.

Parameters:
  • now (Callable[[], int]) – The wall clock in nanoseconds, compared with modification times to decide whether a file’s stat can be trusted yet. It decides a reread, nothing else.

  • sleep (Callable[[float], None]) – How a wait without a file watcher passes the time.

  • read (Callable[[Path], bytes]) – How a file is read to be hashed.

snapshot(paths)[source]#

Return a stable fingerprint of tracked files and directories.

A file is hashed again only when its size or modification time moved since the previous snapshot, or when its stat was then too recent to trust. The fingerprint holds the hash alone, so touching a file without changing it changes nothing.

Return type:

tuple[tuple[str, object], ...]

wait(interval, dependencies)[source]#

Wait for a filesystem event, or for interval seconds at most.

With watchfiles installed, one watcher serves every wait until the dependencies, or the folders they are watched from, change. It watches each folder without its subfolders, as the snapshot looks no deeper. Without watchfiles, or once a watcher failed for these dependencies, a wait sleeps and the next snapshot decides.

Return type:

None

close()[source]#

Close the file watcher, if one is open.

Return type:

None

scenet.watch.snapshot(paths)[source]#

Return a stable fingerprint of tracked files and directories, hashing every file.

Return type:

tuple[tuple[str, object], ...]

scenet.watch.watch_loop(dependencies, rebuild, *, interval=0.1, debounce=0.3, wait=None, take_snapshot=None, clock=<built-in function monotonic>, max_iterations=None)[source]#

Rebuild once dependencies have remained unchanged for the debounce window.

wait and take_snapshot default to those of a WatchSession made for this watch, which is closed when the watch ends, Ctrl-C included.

Return type:

None