Intro

This intro serves as a quick starting off point to see some of arc's most useful features.

Hello World

The simplest arc program would look like this

hello_world.py

import arc


@arc.command
def main():
    arc.print("Hello World!")


main()

Which we can then execute directly!

$ python hello_world.py 
Hello World!

Let's break this down to better understand what exactly is going on.

1. @arc.command is a Python decorator that transforms a function into an arc command.
2. def main() is just a simple Python function
3. main() while this make look like we're calling the main function, because the function has been transformed into a command, we're actualy executing the command.

Parameters

We can add parameters to the previous example by defining an argument. For example, instead of saying hello to the world, we can have the command say hello to a specific person that we can input:

examples/hello.py

import arc


@arc.command
def hello(name: str):
    """Greets someone by name"""
    arc.print(f"Hello {name}!")


hello()

$ python hello.py Joseph
Hello Joseph!

Documentation

Our argument and docstring get added automatcially to the --help output

$ python hello.py --help
USAGE
    hello.py [-h] name

DESCRIPTION
    Greets someone by name

ARGUMENTS
    name

OPTIONS
    --help (-h)  Displays this help message

Type Hints

arc uses argument type hints for data validation / conversion. For example, say we want to write a command that can sum two numbers together:

examples/add.py

import arc


@arc.command
def add(val1: int, val2: int):
    arc.print(f"The answer is: {val1 + val2}")


add()

$ python add.py 5 10
The answer is: 15

if the input fails to validate, arc will report a user-friendly error for the type

$ python add.py 5 not-a-number
USAGE
    add.py [-h] val1 val2

invalid value for val2: must be an integer (invalid literal for int() with base 10: 'not-a-number')

Some note about types:

• if a parameter does not specify a type, arc implicitly types it as str.
• All builtin types are supported by arc, and many stdlib types
• Parameter Types contains a comprehensive list of all supported types.

Configuration

arc is easily configurable via the arc.configure() function.

For example, you can set a version string for you application. This will add a --version flag to your application.

examples/hello_configuration.py

import arc

arc.configure(version="1.0.0")


@arc.command
def hello(name: str):
    """My first arc program!"""
    arc.print(f"Hello {name}!")


hello()

$ python hello_configuration.py --help
USAGE
    hello_configuration.py [-h] [-v] name

DESCRIPTION
    My first arc program!

ARGUMENTS
    name

OPTIONS
    --help (-h)     Displays this help message
    --version (-v)  Displays the app's version number

$ python hello_configuration.py --version
1.0.0

View the reference for details on all the configuration options