app-model: Generic Application Schema

Common errors

• pydantic.v1.error_wrappers.ValidationError: ...

  cause You are likely running `app-model` with Pydantic v1.x installed, which is incompatible with recent versions of `app-model` (v0.4.0+).
  fix Upgrade Pydantic to version 2.0 or newer: `pip install 'pydantic>=2'`.

• AttributeError: 'Future' object has no attribute 'my_expected_attribute'

  cause You forgot to call `.result()` on the `Future` object returned by `app.commands.execute()`, attempting to access attributes directly on the Future itself.
  fix Modify your command execution to retrieve the actual result: `result = app.commands.execute('my-app.command_id').result()`.

• app_model.types.CommandNotFoundError: Command 'unknown_id' not found

  cause The command ID provided to `app.commands.execute()` or `app.register_menu_item()` does not correspond to any command that has been registered with the `Application` instance.
  fix Ensure the command ID matches exactly one of your registered commands. Verify the ID in `app.register_command(Command('YOUR_ID', ...))` and `app.commands.execute('YOUR_ID', ...)`.

Warnings

• breaking app-model v0.4.0+ requires Pydantic v2.0 or newer. Using Pydantic v1.x will lead to `ValidationError` or `AttributeError` issues, particularly when models are instantiated or validated.
  Fix: Ensure `pydantic>=2.0` is installed in your environment: `pip install 'pydantic>=2'`.
• gotcha The `app.commands.execute()` method returns a `Future` object, not the direct result of the command. If you need the result immediately in a synchronous context, you must call `.result()` on the returned Future. In an `async` context, `await` the Future.
  Fix: Always append `.result()` for synchronous calls: `app.commands.execute(...).result()`. For async functions, use `await app.commands.execute(...)`.
• gotcha The `Menu` enums were refactored in v0.5.0. If you were previously using patterns like `MenuType.APP`, these have been simplified to `Menu.APP`. Direct `Menu` enum members are now used for registering menu items.
  Fix: Update your menu registration code to use the direct `Menu` enum members, e.g., `Menu.APP` instead of `MenuType.APP` or string literal names.

Install

• pip install app-model Install stable version

Imports

• Application

  from app_model import Application

• Command

  from app_model import Command

• Menu

  from app_model import Menu

• SubMenu

  from app_model import SubMenu

• Action
  wrong:

  from app_model import Action

  correct:

  from app_model.types import Action

  Action is part of the `types` submodule, not directly under `app_model`.

Quickstart

This quickstart demonstrates how to set up a basic `Application`, define and register commands using `Command` objects, associate them with menus via `Menu` enumerations, and execute commands, retrieving their results. Note the use of `.result()` to unwrap the `Future` returned by `execute` for synchronous retrieval.

from app_model import Application, Command, Menu

def say_hello(name: str = "World") -> str:
    "A command that greets the provided name."
    return f"Hello, {name}!"

def say_goodbye() -> str:
    "A simple command to say goodbye."
    return "Goodbye!"

# 1. Initialize the application
app = Application("my-first-app")

# 2. Register commands
app.register_command(Command("my-app.hello", say_hello, title="Say Hello"))
app.register_command(Command("my-app.goodbye", say_goodbye, title="Say Goodbye"))

# 3. Register a menu item for the 'hello' command
app.register_menu_item(
    Menu.APP,  # or Menu.FILE, Menu.EDIT, etc.
    Command("my-app.hello", title="Say Hello from Menu", menu_path="File > Hello"),
)

# 4. Execute a command and get its result
hello_result = app.commands.execute("my-app.hello", {"name": "Registry"}).result()
print(f"Hello Command Result: {hello_result}")

goodbye_result = app.commands.execute("my-app.goodbye").result()
print(f"Goodbye Command Result: {goodbye_result}")