cli

Description

Internal CLI exposed to Python.

Index

Classes

Interactive		Options for the interactive command.
ExtContext		External command context
ExternalCommand		An external CLI command that may be invoked by the command line argument parser.
WorkspaceContents		Contents of a loaded workspace.

Functions

load_workspace		Read config and document sources as if invoking CLI.
main		Entry point to internal Syside CLI. Returns exit code on completion.

---

Functions

load_workspace(executor: .syside.Executor, paths: typing.Sequence[str | os.PathLike[typing.AnyStr]], exclude: typing.Sequence[str | os.PathLike[typing.AnyStr]] = (), include: typing.Sequence[str | os.PathLike[typing.AnyStr]] = (), config: bool | str | os.PathLike[typing.AnyStr] | None = False, sysand_dir: bool | str | os.PathLike[typing.AnyStr] | None = False, tier: .syside.DocumentTier = syside.DocumentTier.Project) → syside.cli.WorkspaceContents

Read config and document sources as if invoking CLI.

In contrast to the CLI, configuration and Sysand search is optional and disabled by default, and the standard library and current working directory paths are not implicit:

• config and sysand_dir additionally accept boolean values. If values are false (default), corresponding files are not loaded and not used, whereas the CLI uses default values. To use default values, pass None or True instead.

• Standard library is not included in the loaded documents. Combine with Python Environment instead.

• Current directory is not searched if paths are empty.

Finally, this function only performs filesystem search and file reading. The returned documents will not have CST nor AST constructed. They need to be constructed explicitly, e.g. by passing them through the pipeline.

main(args: Sequence[str], interactive: Callable[[syside.cli.Interactive], int] | None = None, external: Sequence[syside.cli.ExternalCommand] = ()) → int

Entry point to internal Syside CLI. Returns exit code on completion.

args must either be <syside> args... or <python> -m <syside> args..., i.e. they must be the same as called from the command line, e.g. sys.argv.

The interactive argument is used to provide Python implementation for the interactive command.

Raises anything interactive or external may raise if executed.

The server command will use underlying native stdin and stdout streams directly, any modifications to sys.stdout and sys.stdin will not be propagated.

Warning

Multiple threads running server command simultaneously are not supported as it overrides global exit and error hooks. If multiple servers are needed, run them in separate processes.

Note

Syside depends on output streams supporting full Unicode range. If the standard stream encoding is not Unicode, e.g. not encoding.startswith("utf"), it will be temporarily reconfigured to platform-specific encoding:

• Windows: utf-16 because by default PowerShell converts all redirected output to utf-16 regardless. Note that this inserts byte order mark (BOM) into the output stream. If another encoding is required or BOM is unwanted:

  • call sys.std*.reconfigure(encoding="utf-*") from Python provided they are instances of io.TextIOWrapper.

  • run python with PYTHONIOENCODING="utf-*" environment variable:

    $env:PYTHONIOENCODING="utf-8"
    python ...
    

  • run python in UTF-8 mode:

    python -X utf8 ...
    

    or:

    $env:PYTHONUTF8="1"
    python ...
    

  • change terminal or system locale to Unicode (chcp 65001 does not seem to have any effect on Python)

• Linux, macOS: utf-8. This is typically the default in all cases.