auto-app-panel 0.1.1

Automatically generate a valid `app-panel.json` from an argument parser defined in code in a Code Ocean capsule.

auto-app-panel

Automatically generate a valid app-panel.json from an argument parser defined in code in a Code Ocean capsule.

Status

• Initial release supporting extraction from pydantic_settings.BaseSettings and argparse.ArgumentParser classes at top-level of a specified Python file.

TODO

• support classes defined inside functions or conditionals
• preserve groups and other formatting in existing app panel
• create explicit string/number/integer Parameter classes to support additional constraints (e.g. min/max length for strings, regex validators etc.) - see codeocean sdk for full schema

Installation

Add auto-app-panel as a Python dependency in your Code Ocean capsule.

Usage

auto-app-panel SOURCE [OUTPUT] [OPTIONS]

Arguments:

• SOURCE - Path to Python file containing argument parsing class (required)
• OUTPUT - Output path for app-panel.json (default: /root/capsule/.codeocean/app-panel.json)

Options:

• --strategy [overwrite|preserve] - Merge strategy (default: preserve)
  • overwrite: Updates parameter values from code, preserves existing descriptions
  • preserve: Keeps all existing values, only adds new parameters
• --no-backup - Skip creating timestamped backup of existing file

Example

Input Python file (run.py):

import time

import pydantic
import pydantic_settings

class Params(pydantic_settings.BaseSettings):
    max_workers: int | None = pydantic.Field(6, description="Number of parallel workers. Leave empty or set to 0 to use max available.")
    threshold: float = 0.5    
    output_dir: str = pydantic.Field("/root/capsule/results/dryrun", description="Output path for results, posix format.")
    save_intermediate: bool = False
    
    # other attributes that are not parsed from command-line inputs (e.g. PrivateAttr or @computed_field) are ignored
    _start_time: float = pydantic.PrivateAttr(time.time())

    # Ensure class parses arguments from command line (and set priority of other sources):
    @classmethod  
    def settings_customise_sources(
        cls,
        settings_cls,
        init_settings,
        *args,
        **kwargs,
    ):
        # instantiating the class will use arguments passed directly, or provided via the command line/app panel
        # - the order of the sources below defines the priority (highest to lowest):
        # - for each field in the class, the first source that contains a value will be used
        return (
            init_settings,
            pydantic_settings.sources.JsonConfigSettingsSource(settings_cls, json_file='parameters.json'),
            pydantic_settings.CliSettingsSource(settings_cls, cli_parse_args=True),
        )

Generate file at standard path:

auto-app-panel /root/capsule/code/run.py --strategy overwrite --no-backup

Generated app-panel.json:

{
    "version": 1,
    "named_parameters": true,
    "parameters": [
        {
            "id": "a1b2c3d4e5f6g7h8",
            "name": "max_workers",
            "param_name": "max_workers",
            "description": "Number of parallel workers",
            "help_text": "Number of parallel workers",
            "type": "text",
            "value_type": "integer",
            "default_value": "6"
        },
        {
            "id": "i9j0k1l2m3n4o5p6",
            "name": "threshold",
            "param_name": "threshold",
            "type": "text",
            "value_type": "number",
            "default_value": "0.5"
        },
        {
            "id": "q7r8s9t0u1v2w3x4",
            "name": "output_dir",
            "param_name": "output_dir",
            "description": "Output path for results, posix format.",
            "help_text": "Output path for results, posix format.",
            "type": "text",
            "value_type": "string",
            "default_value": "/root/capsule/results/dryrun"
        },
        {
            "id": "y5z6a7b8c9d0e1f2",
            "name": "save_intermediate",
            "param_name": "save_intermediate",
            "type": "text",
            "value_type": "integer",
            "default_value": "0",
            "minimum": 0,
            "maximum": 1
        }
    ]
}

Typical Workflow

1. Develop your code with a class for parsing capsule parameters at the top-level of the file (not inside a function or conditional)
2. Run the tool in a Code Ocean cloud workstation terminal:

   auto-app-panel /root/capsule/code/run.py
   

3. Manually customize descriptions or add constraints as needed
4. Re-run the tool when you add/modify parameters (use --strategy preserve to keep customizations)
5. Verify that the App Panel is visible and has all expected fields when you exit the cloud workstation