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:

from cto_ai import ux, prompt

def main():
    opinion = prompt.input(
        name="opinion",
        message="What do you think of Typescript?",
        flag="o",
        default="I don't know"
    )
    ux.print("You think {} about Typescript".format(opinion))

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:

from cto_ai import ux, prompt

def main():
    count = prompt.number(
        name="count",
        message="How many hoorays do you want?",
        flag="c",
        default=3,
        minimum=0,
        maximum=20
    )
    for i in range(0, count):
        ux.print("Hooray")

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:

from cto_ai import ux, prompt

def main():
    sshKey = prompt.secret(
        name="sshKey",
        message="What SSH private key do you want to use?"
    )
    ux.print("Your private key has {} characters.  Isn't that interesting?".format(
        len(sshKey)))

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:

from cto_ai import ux, prompt

def main():
    password = prompt.password(
        name="password",
        message="What new password would you like to use?",
        confirm=True
    )
    if (len(password) < 6):
        ux.print("I don't think you want a password as short as {}".format(password))
    else:
        ux.print("Password length acceptable")

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:

from cto_ai import ux, prompt

def main():
    verbose = prompt.confirm(
        name="verbose",
        message="Do you want to run in verbose mode?",
        flag="V"
    )
    if verbose:
        ux.print(
            "You have reached the end of this example demonstrating the confirm prompt type in the CTO.ai SDK.")
    else:
        ux.print("Done.")

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:

from cto_ai import ux, prompt

def main():
    platform = prompt.list(
        name="platform",
        message="What cloud platform would you like to deploy to?",
        choices=["AWS", "Google Cloud", "Azure"],
        default="AWS"
    )
    ux.print("Preparing to deploy to {}".format(platform))

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:

from cto_ai import ux, prompt

def main():
    province = prompt.autocomplete(
        name="province",
        message="To which province do you want to send your letter?",
        choices=["Alberta", "British Columbia", "Manitoba", "New Brunswick", "Newfoundland and Labrador", "Nova Scotia", "Ontario", "Prince Edward Island", "Quebec", "Saskatchewan"],
        default=1
    )
    ux.print("Preparind address label for {}".format(province))

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:

from cto_ai import ux, prompt

def main():
    tools = prompt.checkbox(
        name="tools",
        message="Which interpreters would you like to have included in your OS image?",
        choices=["Lua", "Node.js", "Perl", "Python 2", "Python 3", "Raku", "Ruby"],
        default=[1]
    )
    for tool in tools:
        ux.print("Adding {}".format(tool))

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:

from cto_ai import ux, prompt

def main():
    template = "Features:\\n\\nFixes:\\n\\nChores:"

    notes = prompt.editor(
        name="notes",
        message="Please enter your release notes",
        default=template
    )
    ux.print("Your release notes are {}".format(notes))

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:

from datetime import datetime

from cto_ai import ux, prompt

def main():
    now = datetime.utcnow().isoformat() + "Z"

    next_run = prompt.datetime(
        name="next_run",
        message="When do you want to run the code next?",
        variant="datetime",
        minimum=now
    )
    ux.print("Your code will next run at {}".format(next_run))