Hello, World

Basics of CLI apps and printing things to output.

Your first Yuio app

Let’s begin by setting up a very simple CLI app:

import yuio.app

@yuio.app.app()  # [1]_
def main(
    greeting: str = "world",  # [2]_
):
    print(f"Hello, {greeting}!")

if __name__ == "__main__":
    main.run()  # [3]_

  1. app() accepts useful settings in its constructor.

  2. Function arguments become CLI flags.

  3. run() parses CLI arguments and invokes main.

This is it! You now have a CLI app that greets you. Let’s run it:

Printing something colorful

We want colors, so it’s time to switch from bare print() to yuio.io:

import yuio.app
import yuio.io  # [1]_

@yuio.app.app()
def main(greeting: str = "world"):
    yuio.io.info("Hello, <c bold green>%s</c>!", greeting)  # [2]_
    yuio.io.info("You're running `Yuio %r`", yuio.version)  # [3]_

  1. yuio.io has everything for interacting with users.

  2. <c ...> is a color tag. Read about its syntax in yuio.io, see full list of tags in yuio.theme.

  3. Backticks work like in Markdown.

Tada, now our greeting is ✨colorful✨!

Flags and positional arguments

Let’s add a shorter flag for --greeting, and add an option to output the greeting to a file:

import pathlib  # [1]_
import yuio.app
import yuio.io

@yuio.app.app()
def main(
    output: pathlib.Path | None = None,  # [2]_
    /,  # [3]_
    *,
    greeting: str = yuio.app.field(default="world", flags=["-g", "--greeting"]),  # [4]_
):
    if output:
        output.write_text(f"Hello, {greeting}!\n")
    else:
        yuio.io.info(f"Hello, `%s`!", greeting)

  1. We use pathlib.Path instead of str. This tells Yuio that you expect a file path, which affects autocompletion.

  2. Positional-only arguments become positional CLI options.

  3. This syntax separates positional-only arguments from normal arguments. See PEP 570 for details.

  4. yuio.app.field() allows customizing settings for app arguments and config fields.

Adding help for CLI arguments

Finally, let’s add some help messages to document our CLI options:

@yuio.app.app(doc_format="md")  # [1]_
def main(
    #: Output file, defaults to printing to `stdout`.  [2]_
    output: pathlib.Path | None = None,
    /,
    *,
    #: Who do we want to greet?
    greeting: str = yuio.app.field(default="world", flags=["-g", "--greeting"]),
):
    """
    This is a program for greeting guests.  [3]_

    """

  1. Default format is RST, but you can use Markdown instead.

  2. Help for individual parameters can be added with documentation comments.

  3. Function’s docstring becomes the main help message.

Yuio parses comments of your python files, so help messages can be just RST or Markdown docstrings!