LabRequestOptions

pydantic model controller.models.v1.lab.LabRequestOptions

User-provided lab configuration options.

This model represents the form submission to the spawner HTML form presented to the user by JupyterHub.

All values to this model can instead be given as lists of length one, with boolean values converted to the strings true or false. This is the form in which the values are received by the JupyterHub spawner form processing code, and allows JupyterHub to pass its form submission directly to the lab controller without modifications.

Parameters:

data (Any)

Show JSON schema
{
   "title": "LabRequestOptions",
   "description": "User-provided lab configuration options.\n\nThis model represents the form submission to the spawner HTML form\npresented to the user by JupyterHub.\n\nAll values to this model can instead be given as lists of length one, with\nboolean values converted to the strings ``true`` or ``false``. This is the\nform in which the values are received by the JupyterHub spawner form\nprocessing code, and allows JupyterHub to pass its form submission\ndirectly to the lab controller without modifications.",
   "type": "object",
   "properties": {
      "size": {
         "allOf": [
            {
               "$ref": "#/$defs/LabSize"
            }
         ],
         "description": "Size of image, chosen from sizes specified in the controller configuration",
         "examples": [
            "medium"
         ],
         "title": "Image size"
      },
      "enable_debug": {
         "default": false,
         "description": "If true, set the ``DEBUG`` environment variable when spawning the lab, which enables additional debug logging",
         "examples": [
            true
         ],
         "title": "Enable debugging in spawned Lab",
         "type": "boolean"
      },
      "reset_user_env": {
         "default": false,
         "description": "If true, set the ``RESET_USER_ENV`` environment variable when spawning the lab, which tells the lab to move aside the user environment directories (``.cache``, ``.conda``, ``.jupyter``, ``.local``) and files (``.user_setups``). This can be used to recover from user configuration errors that break lab startup.",
         "examples": [
            true
         ],
         "title": "Move aside user environment",
         "type": "boolean"
      },
      "image_list": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Selected image from the radio button part of the image menu, or the special value ``use_image_from_dropdown``. If this is set, to a value other than ``use_image_from_dropdown``, ``image_dropdown`` should not be set.",
         "examples": [
            "lighthouse.ceres/library/sketchbook:w_2023_07@sha256:abcd"
         ],
         "title": "Image from selection radio button"
      },
      "image_dropdown": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Selected image from the dropdown part of the image menu. If this is set, ``image_list`` should be omitted or set to ``use_image_from_dropdown``.",
         "examples": [
            "lighthouse.ceres/library/sketchbook:w_2022_40"
         ],
         "title": "Image from dropdown list"
      },
      "image_class": {
         "anyOf": [
            {
               "$ref": "#/$defs/ImageClass"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Spawn a class of image determined by the lab controller. Not used by the user form, but may be used by bots creating labs. Only one of ``image_class`` or ``image_tag`` may be given, and neither ``image_list`` nor ``image_dropdown`` should be set when using these options.",
         "examples": [
            "recommended"
         ],
         "title": "Class of image to spawn"
      },
      "image_tag": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Spawn the image with the given tag. Not used by the user form, but may be used by bots creating labs. Only one of ``image_class`` or ``image_tag`` may be given, and neither ``image_list`` nor ``image_dropdown`` should be set when using these options.",
         "examples": [
            "w_2023_07"
         ],
         "title": "Tag of image to spawn"
      }
   },
   "$defs": {
      "ImageClass": {
         "description": "Supported classes of images.\n\nThese keywords can be passed into the spawn form to spawn whatever image\nmatches this class, as determined by the lab controller. This is primarily\nused when spawning notebooks for bot users.",
         "enum": [
            "recommended",
            "latest-release",
            "latest-weekly",
            "latest-daily"
         ],
         "title": "ImageClass",
         "type": "string"
      },
      "LabSize": {
         "description": "Allowable names for pod sizes.\n\nTaken from `d20 creature sizes`_.",
         "enum": [
            "fine",
            "diminutive",
            "tiny",
            "small",
            "medium",
            "large",
            "huge",
            "gargantuan",
            "colossal",
            "custom"
         ],
         "title": "LabSize",
         "type": "string"
      }
   },
   "required": [
      "size"
   ]
}

Fields:
Validators:

  • _validate_booleans » enable_debug

  • _validate_booleans » reset_user_env

  • _validate_lists » all fields

  • _validate_one_image » all fields

  • _validate_size » size

field enable_debug: bool = False

If true, set the DEBUG environment variable when spawning the lab, which enables additional debug logging

Validated by:

  • _validate_booleans

  • _validate_lists

  • _validate_one_image

field image_class: ImageClass | None = None

Spawn a class of image determined by the lab controller. Not used by the user form, but may be used by bots creating labs. Only one of image_class or image_tag may be given, and neither image_list nor image_dropdown should be set when using these options.

Validated by:

  • _validate_lists

  • _validate_one_image

field image_dropdown: str | None = None

Selected image from the dropdown part of the image menu. If this is set, image_list should be omitted or set to use_image_from_dropdown.

Validated by:

  • _validate_lists

  • _validate_one_image

field image_list: str | None = None

Selected image from the radio button part of the image menu, or the special value use_image_from_dropdown. If this is set, to a value other than use_image_from_dropdown, image_dropdown should not be set.

Validated by:

  • _validate_lists

  • _validate_one_image

field image_tag: str | None = None

Spawn the image with the given tag. Not used by the user form, but may be used by bots creating labs. Only one of image_class or image_tag may be given, and neither image_list nor image_dropdown should be set when using these options.

Validated by:

  • _validate_lists

  • _validate_one_image

field reset_user_env: bool = False

If true, set the RESET_USER_ENV environment variable when spawning the lab, which tells the lab to move aside the user environment directories (.cache, .conda, .jupyter, .local) and files (.user_setups). This can be used to recover from user configuration errors that break lab startup.

Validated by:

  • _validate_booleans

  • _validate_lists

  • _validate_one_image

field size: LabSize [Required]

Size of image, chosen from sizes specified in the controller configuration

Validated by:

  • _validate_lists

  • _validate_one_image

  • _validate_size

property image_attribute: str

The name of the image attribute that was set.

Used for error reporting to know what input attribute to report when the image specification was invalid.