Python SDK: prompts

What are Prompts?

User input will be accepted by a variety of means depending on the environment where the code is running. Locally, command-line inputs are 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. The return value of ux.prompt is simply the user input for the prompt.

Common parameters

Every prompt must have the same common parameters:

  • 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.
  • 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 to the command-line 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.

As Slack does not allow users to send blank messages, the default and allowEmpty arguments will not register in Slack.

Example:

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 to the command-line 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

Example:

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 in the command-line.

Example:

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.

Example:

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.

Example:

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.

In Slack, the list prompt will produce a drop down menu to select from. Users can also enter their desired choice in the text box to make a selection.

Example:

autocomplete prompt

The autocomplete prompt type asks the user to select a single item from a list of choices. In the command-line, 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.

The autocomplete prompt type will function identical to the list prompt type in Slack.

Example:

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

Example:

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.

Currently, the default argument will not appear in Slack.

Example:

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.

Example: