Python Prompts

Prompt interface overview

User input will be accepted by a variety of means depending on the environment where the code is running. Locally, terminal input is used by default, with command line arguments seamlessly substituted where appropriate. In a remote environment, this will be a remote interface such as a Slack channel.

Unlike the Node.js SDK, ux.prompt is not a single function in Python, it is the prompt module. Each prompt type is its own function named after the prompt type (e.g., prompt.text,prompt.list, prompt.secret).The name and message can be passed as positional parameters but all others are keyword-only. We recommend always using keyword parameters.

Every prompt must have the same basic fields:

  • type (string): the prompt type, as described below. Currently
    valid types are
    • input
    • number
    • secret
    • password
    • confirm
    • list
    • autocomplete
    • checkbox
    • editor
    • datetime
  • name (string): The name of the prompt, which should be unique within the program. The kebab-case version of this name is used as the command line argument name, for example, the prompt with name baseBranch can have its value specified as --base-branch master. The return value of ux.prompt will use this name as the key for the returned value for this prompt.
  • message (string): The prompt for the user to be displayed when input is necessary

There is also one optional parameter that is common to all prompt types:

  • flag (string): an alias for the name that can be used as a command line argument. Can be a single character, which can then be used as in -b master.

input prompt

The input prompt type requests a single-line string from the user. Along with the common parameters above, it can accept the following optional parameters:

  • default (string): a default value to be provided on the terminal and accepted if the user just presses return.
  • allowEmpty (boolean): Set to true to accept empty input to this prompt. Defaults to requiring non-empty input.

number prompt

The number prompt requests an integer from the user. Along with the common parameters above, it can accept the following optional parameters:

  • default (number): a default value to be provided on the terminal and accepted if the user just presses return.
  • minimum (number): a minimum value for the input number
  • maximum (number): a maximum value for the input number

secret prompt

The secret prompt type will request a secret from the user. The user can respond to this prompt by entering a value, or, if they have a secrets provider configured, with a value from their team secret store. Secrets will be entered in the clear on the terminal.

password prompt

The password prompt type will request a password from the user. The user can respond to this prompt by entering a value, or, if they have a secrets provider configured, with a value from their team password store. Passwords will be hidden in the terminal.

Along with the common parameters above, the password prompt takes the following optional parameter:

  • confirm (boolean): Set to true to require the user to confirm the choice of password. Defaults to false.

confirm prompt

The confirm prompt type requests a yes/no answer to the user. Confirm prompts can be matched with bare command line arguments, such as "--verbose" or "-V". Along with the common parameters above, the confirm prompt takes the following optional parameter:

  • default (boolean): The value selected if the user presses return at the prompt. Defaults to false.

list prompt

The list prompt type asks the user to select a single item from a list of choices. Along with the common parameters above, the list prompt takes the following parameters:

  • choices (string[]) required: The list of choices to be presented to the user.
  • default (string|number) optional: The default selection from the list. Can be passed as either the default value or the index of the default value.

autocomplete prompt

The autocomplete prompt type asks the user to select a single item from a list of choices. On a terminal, it allows the user to select the item by typing with fuzzy autocomplete. Along with the common parameters above, the autocomplete prompt takes the following parameters:

  • choices (string[]) required: The list of choices to be presented to the user.
  • default (string|number) optional: The default selection from the list. Can be passed as either the default value or the index of the default value.

checkbox prompt

The checkbox prompt type asks the user to select multiple item from a list of choices. Along with the common parameters above, the checkbox prompt takes the following parameters:

  • choices (string[]) required: The list of choices to be presented to the user.

editor prompt

The editor prompt type asks the user for a multi-line text input. In a local environment, it will start the nano editor inside the container. Along with the common parameters above, the list prompt takes the following optional parameter:

  • default (string|number): The default text to appear in the editor when it opens. Can be a template.

datetime prompt

The datetime prompt type asks the user for a date and/or time. Along with the common parameters above, the list prompt takes the following optional parameters:

  • variant ("date"|"time"|"datetime") - specifies which time information to prompt for, either a date (day/month/year) or a time (hour/minute/second), or both. Default is "datetime".
  • default (string|Date) - The time to initialize the prompt with. If not specified, will default to the current time.
  • minimum (string|Date) - The minimum time to permit in the prompt.
  • maximum (string|Date) - The maximum time to permit in the prompt.

If specified as strings, the default, minimum and maximum must be in RFC 3339 format.