App Module (`stx.app`)

Runtime SDK for SciTeX applications. Provides a unified interface for file storage, configuration, and lifecycle management that works identically in local and cloud environments.

Note

stx.app delegates to the standalone scitex-app package. Install with: pip install scitex-app.

Overview

SciTeX applications are self-contained scientific tools that can run locally or on the SciTeX cloud platform. The stx.app module provides the runtime SDK that each application uses to interact with its environment.

Quick Start

import scitex as stx

# Get current application info
info = stx.app.get_info()

# Access application preferences
prefs = stx.app.get_prefs()

# Check dependencies
stx.app.check_deps()

Key Features

Unified File Storage

Read and write files through a single API that abstracts local filesystem and cloud storage.

# These work identically locally and in the cloud
stx.app.write_file("results/output.csv", data)
content = stx.app.read_file("config/settings.yaml")

Configuration Management

Application preferences are stored in a standard location and accessible via dot-notation.

prefs = stx.app.get_prefs()
print(prefs.theme)
print(prefs.default_format)

stx.app.set_prefs(theme="dark", default_format="pdf")

Application Lifecycle

Query and manage the running application.

info = stx.app.get_info()
print(info.name)
print(info.version)

current = stx.app.get_current()    # Currently active app

Dependency Checking

Verify that all required packages are available.

missing = stx.app.check_deps()
if missing:
    print(f"Missing: {missing}")

Creating an Application

Scaffold a new SciTeX application from a template:

scitex template clone app my_tool

This creates a project with bridge-init configuration, MountPoint definitions, and EventBus integration pre-configured.

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)

class scitex.app.FilesBackend(*args, **kwargs)[source]

Bases: Protocol

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_cloud (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

delete(path)[source]

Delete a file.

Raises:: FileNotFoundError – If the file does not exist.
Return type:: None

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

copy(src_path, dest_path)[source]

Copy a file within the namespace.

Raises:: FileNotFoundError – If src_path does not exist.
Return type:: None

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.

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.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]

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

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]

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

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

Delete path in the resolved backend.

Mirrors the app_delete_file MCP tool.

Return type:: None

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

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

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]

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]

App Module (stx.app)

Overview

Quick Start

Key Features

Creating an Application

API Reference

Implementations

App Module (`stx.app`)