Skip to content

Shell Completions

Warning

Shell completions are currently an experimental feature. There is no guarantee that they will work or if the API for using them will be stable. As such, the feature is disabled by default To enable shell completions, add the following to your script:

import arc
arc.configure(autocomplete=True)

The autocompletions will be generated with the following commands. foo is used as an example command entry point / name

Add to ~/.bashrc

eval "$(foo --autocomplete bash)"

Add to ~/.zshrc

eval "$(foo --autocomplete zsh)"

Add to ~/.config/fish/completions/foo.fish

foo --autocomplete fish | source

Type Completions

Argument types can provide shell completions for the argument.

For example, arc's builtin support for enum.Enum provides completions for it's possible options

examples/paint.py
from enum import Enum
import arc


class Color(Enum):
    RED = "red"
    YELLOW = "yellow"
    GREEN = "green"


@arc.command()
def paint(color: Color):
    if color is Color.RED:
        arc.print("You painted the walls the bloodiest of reds")
    elif color is Color.YELLOW:
        arc.print("You painted the walls the most fabulous yellow")
    else:
        arc.print("You painted the walls the deepest of greens")


paint()

$ paint <tab>
red yellow green

The following types have builtin completion support:

  • enum.Enum
  • typing.Literal
  • arc.types.ValidPath
  • arc.types.FilePath
  • arc.types.DirectoryPath

Custom Types

When implenting your own types, you can provide completions for them implementing the __completions__() method on your class.

This method recieves an info object that contains information about the current state of the command line, and param which is the parameter that is being completed (in the below example, that parameter would be foo). The method should return a list of arc.autocompletions.Completion() objects that are the possible completions for the parameter.

examples/custom_type_completions.py
import arc
from arc import autocompletions as ac


class CustomType:
    def __init__(self, val: int):
        self.val = val

    def __str__(self):
        return f"CustomType(val={self.val})"

    @classmethod
    def __convert__(cls, value: str):
        if value.isnumeric():
            return cls(int(value))
        else:
            raise arc.ConversionError(value, "must be an integer")

    @classmethod
    def __completions__(self, info: ac.CompletionInfo, param):
        return [
            ac.Completion("1"),
            ac.Completion("2"),
        ]


@arc.command()
def main(foo: CustomType):
    arc.print(foo)


main()
$ custom_type_example <tab>
1 2

Custom Completions