API Reference

scitex-app — Write-once interface for local + cloud SciTeX apps.

Standalone package. Zero dependencies (pure stdlib). When used with scitex, integration is automatic via scitex.app.

Public API (3 functions):

from scitex_app.sdk import get_files, register_backend, FilesBackend

# Get a file backend (auto-detects local vs cloud)
files = get_files("./project")

# Read/write files
content = files.read("data/config.yaml")
files.write("output/result.csv", csv_text)

# Register a custom backend
register_backend("s3", my_s3_factory)

scitex_app.get_files(root=None, *, backend=None, **kwargs)[source]

Get a files backend instance.

Auto-detection logic:

If backend is specified, use that.
If SCITEX_API_TOKEN env var is set and “cloud” backend is registered, use cloud.
Otherwise, use filesystem (default).

Parameters:

root (str or Path, optional) – Root directory for filesystem backend. Defaults to cwd.
backend (str, optional) – Explicit backend name. If None, auto-detected.
kwargs (Any)

Returns:

A backend instance.

Return type:

FilesBackend

Raises:

KeyError – If the requested backend is not registered.

scitex_app.register_backend(name, factory)[source]

Register a files backend factory.

Parameters:

name (str) – Backend identifier (e.g., “cloud”, “s3”).
factory (callable) – Callable(root, **kwargs) -> FilesBackend instance.

Return type:

None

scitex_app.build_tree(backend, directory='', *, extensions=None, skip_hidden=True, max_depth=10)[source]

Build a nested tree structure from a FilesBackend.

Parameters:

backend (FilesBackend) – A file storage backend implementing the FilesBackend protocol.
directory (str) – Starting directory (relative to backend root). Default: root.
extensions (list of str, optional) – Filter files by extension (e.g., [“.yaml”, “.png”]). Directories are always included for traversal.
skip_hidden (bool) – Skip files/directories starting with “.”. Default: True.
max_depth (int) – Maximum recursion depth to prevent runaway traversal. Default: 10.

Returns:

Nested tree structure:

[
    {"path": "subdir", "name": "subdir", "type": "directory",
     "children": [...]},
    {"path": "file.yaml", "name": "file.yaml", "type": "file"},
]

Return type:

list of dict

scitex_app.hosts_to_allow(host)[source]

What a given --host bind implies for ALLOWED_HOSTS. Pure function.

PUBLIC API, exported as scitex_app.hosts_to_allow. It became public because it was about to be depended on privately: scitex-scholar and figrecipe each carried a verbatim copy of this function, and on the 0.10.1 release both were replacing their copy with from scitex_app._standalone import _hosts_to_allow — three repositories committing to an underscore path, which is a promise nobody made. Deciding the public name before the dependency exists is cheaper than deprecating an accidental one afterwards.

That private alias is GONE as of 2026-09-04. It existed only for the migration window and was removed once both consumers had swapped, measured against their refs rather than their working trees. Import the public name.

Binding to an address IS the statement that you intend to be reached on it, so contribute it rather than making the caller set an env var to permit what they already asked for:

127.0.0.1 / localhost -> [] settings.py lists loopback 0.0.0.0 -> hostname + this machine’s interface addresses anything else -> [host]

The 0.0.0.0 rule is what makes DEBUG=False the safe default WITHOUT reintroducing the bug #126 fixed: a bind-all server receives requests whose Host header is the real interface address, and “0.0.0.0” in ALLOWED_HOSTS never matches that. Measured 2026-09-02 on the published 1.9.0 wheel: –host 0.0.0.0 with DJANGO_DEBUG=false answered 400 to every real address while loopback answered 200.

Return type:: list[str]
Parameters:: host (str)

scitex_app.read_file(path, *, root='.', binary=False)[source]

Read a single file via the resolved FilesBackend.

Equivalent to get_files(root).read(path, binary=binary); mirrors the app_read_file MCP tool.

Return type:

Union[str, bytes]

Parameters:

path (str)
root (str | Path)
binary (bool)

scitex_app.write_file(path, content, *, root='.')[source]

Write a file via the resolved FilesBackend.

Mirrors the app_write_file MCP tool.

Return type:

None

Parameters:

path (str)
content (str | bytes)
root (str | Path)

scitex_app.list_files(directory='', *, root='.', extensions=None)[source]

List file paths under directory.

Mirrors the app_list_files MCP tool.

Return type:

List[str]

Parameters:

directory (str)
root (str | Path)
extensions (List[str] | None)

scitex_app.file_exists(path, *, root='.')[source]

Return whether path exists in the resolved backend.

Mirrors the app_file_exists MCP tool.

Return type:

bool

Parameters:

path (str)
root (str | Path)

scitex_app.delete_file(path, *, root='.')[source]

Delete path in the resolved backend.

Mirrors the app_delete_file MCP tool.

Return type:

None

Parameters:

path (str)
root (str | Path)

scitex_app.copy_file(src_path, dest_path, *, root='.')[source]

Copy src_path to dest_path within the resolved backend.

Mirrors the app_copy_file MCP tool.

Return type:

None

Parameters:

src_path (str)
dest_path (str)
root (str | Path)

scitex_app.rename_file(old_path, new_path, *, root='.')[source]

Rename old_path to new_path within the resolved backend.

Mirrors the app_rename_file MCP tool.

Return type:

None

Parameters:

old_path (str)
new_path (str)
root (str | Path)

scitex_app.scaffold(target_dir='.', *, name=None, label=None, icon='fas fa-puzzle-piece', description='', frontend='html', overwrite=False)[source]

Generate a new SciTeX workspace app skeleton.

Mirrors the app_scaffold MCP tool. Auto-appends _app / -app to name (matching the MCP tool’s behaviour) so Python and MCP callers see the same result for the same inputs.

Return type:

List[Path]

Parameters:

target_dir (str | Path)
name (str | None)
label (str | None)
icon (str)
description (str)
frontend (str)
overwrite (bool)

scitex_app.validate(app_dir='.')[source]

Audit a SciTeX app for cloud-submission readiness.

Mirrors the app_validate MCP tool. Returns the list of errors (empty when the app is ready).

Return type:: List[str]
Parameters:: app_dir (str | Path)

SDK Module

App SDK — write-once interface for local + cloud SciTeX apps.

Usage (standalone / local):

from scitex_app.sdk import get_files

files = get_files(“./my_project”) content = files.read(“recipes/my_recipe.yaml”) files.write(“output/result.png”, png_bytes)

Usage (cloud, auto-detected via SCITEX_API_TOKEN):

files = get_files() # routes through cloud REST API

Usage (remote local, via SCITEX_API_URL):

import os os.environ[“SCITEX_API_TOKEN”] = “your-token” os.environ[“SCITEX_API_URL”] = “https://scitex.ai” files = get_files() # routes to remote cloud

scitex_app.sdk.get_files(root=None, *, backend=None, **kwargs)[source]

Get a files backend instance.

Auto-detection logic:

If backend is specified, use that.
If SCITEX_API_TOKEN env var is set and “cloud” backend is registered, use cloud.
Otherwise, use filesystem (default).

Parameters:

root (str or Path, optional) – Root directory for filesystem backend. Defaults to cwd.
backend (str, optional) – Explicit backend name. If None, auto-detected.
kwargs (Any)

Returns:

A backend instance.

Return type:

FilesBackend

Raises:

KeyError – If the requested backend is not registered.

scitex_app.sdk.register_backend(name, factory)[source]

Register a files backend factory.

Parameters:

name (str) – Backend identifier (e.g., “cloud”, “s3”).
factory (callable) – Callable(root, **kwargs) -> FilesBackend instance.

Return type:

None

scitex_app.sdk.build_tree(backend, directory='', *, extensions=None, skip_hidden=True, max_depth=10)[source]

Build a nested tree structure from a FilesBackend.

Parameters:

backend (FilesBackend) – A file storage backend implementing the FilesBackend protocol.
directory (str) – Starting directory (relative to backend root). Default: root.
extensions (list of str, optional) – Filter files by extension (e.g., [“.yaml”, “.png”]). Directories are always included for traversal.
skip_hidden (bool) – Skip files/directories starting with “.”. Default: True.
max_depth (int) – Maximum recursion depth to prevent runaway traversal. Default: 10.

Returns:

Nested tree structure:

[
    {"path": "subdir", "name": "subdir", "type": "directory",
     "children": [...]},
    {"path": "file.yaml", "name": "file.yaml", "type": "file"},
]

Return type:

list of dict

FilesBackend Protocol

class scitex_app.sdk._protocol.FilesBackend(*args, **kwargs)[source]

File storage backend protocol.

Implementations must provide these 7 methods. Uses typing.Protocol for structural subtyping — backends just implement the methods, no inheritance required.

Implementations

FileSystemBackend — local pathlib (ships with scitex-app)
CloudFilesBackend — HTTP via scitex_hub (provided at runtime)

read(path, *, binary=False)[source]

Read file content.

Parameters:

path (str) – Relative path within the backend’s namespace.
binary (bool) – If True, return bytes; otherwise return str.

Raises:

FileNotFoundError – If the file does not exist.

Return type:

Union[str, bytes]

write(path, content)[source]

Write content to a file, creating parent dirs as needed.

Parameters:

path (str) – Relative path within the backend’s namespace.
content (str or bytes) – Text or binary content.

Return type:

None

list(directory='', *, extensions=None)[source]

List file paths in a directory.

Parameters:

directory (str) – Relative directory path (”” = root).
extensions (list of str, optional) – Filter by extension, e.g. [“.yaml”, “.png”].

Returns:

Relative file paths.

Return type:

list of str

exists(path)[source]

Check if a file exists.

Return type:: bool
Parameters:: path (str)

delete(path)[source]

Delete a file.

Raises:: FileNotFoundError – If the file does not exist.
Return type:: None
Parameters:: path (str)

rename(old_path, new_path)[source]

Rename/move a file within the namespace.

Raises:

FileNotFoundError – If old_path does not exist.
FileExistsError – If new_path already exists.

Return type:

None

Parameters:

old_path (str)
new_path (str)

copy(src_path, dest_path)[source]

Copy a file within the namespace.

Raises:

FileNotFoundError – If src_path does not exist.

Return type:

None

Parameters:

src_path (str)
dest_path (str)

FileSystemBackend

class scitex_app.sdk._filesystem.FileSystemBackend(root)[source]

Local filesystem implementation of FilesBackend.

All paths are relative to a root directory. Path traversal outside root is prevented.

Parameters:: root (str or Path) – Root directory for all file operations.

property root: Path: Root directory.

read(path, *, binary=False)[source]

Read file content.

Return type:

Union[str, bytes]

Parameters:

path (str)
binary (bool)

write(path, content)[source]

Write content to a file, creating parent dirs as needed.

Return type:

None

Parameters:

path (str)
content (str | bytes)

list(directory='', *, extensions=None)[source]

List file paths in a directory.

Return type:

List[str]

Parameters:

directory (str)
extensions (List[str] | None)

exists(path)[source]

Check if a file exists.

Return type:: bool
Parameters:: path (str)

delete(path)[source]

Delete a file.

Return type:: None
Parameters:: path (str)

rename(old_path, new_path)[source]

Rename/move a file.

Return type:

None

Parameters:

old_path (str)
new_path (str)

copy(src_path, dest_path)[source]

Copy a file.

Return type:

None

Parameters:

src_path (str)
dest_path (str)