Skip to content

Paramater Types

arc uses Python type hints for data conversion / validation.

When Possible, arc uses builtin and standard library data types for arguments. But if no type is available, or the builtin types don't provide the neccessary functionality, arc may implement a custom type.

Builtin Types

str

This is considered the default type is no type is specified. str(v) is used which, in most cases, will be comparable to no change

int

arc uses int(v) to convert the value. Note that decimal input (1.4) will result in an error, not a narrowing operation.

float

Likewise, arc uses float(v). Ingeter values will be converted to a float (2 -> 2.0)

bool

Used to denote a Flag

examples/parameter_flag.py
import arc


@arc.command()
def hello(firstname: str, reverse: bool):
    if reverse:
        firstname = firstname[::-1]

    arc.print(f"Hello, {firstname}! Hope you have a wonderful day!")


hello()
$ python parameter_flag.py Joseph
Hello, Joseph! Hope you have a wonderful day!
$ python parameter_flag.py Joseph --reverse
Hello, hpesoJ! Hope you have a wonderful day!

bytes

Converted using v.encode()

Collection Types

Collection types are used by arc to collect multiple values into a single argument. Check the next page for information on how that works

dict

Allows a list of comma-seperated key-value pairs. Can be typed generically on both keys and values.

dict_argument.py
import arc


@arc.command()
def command(numbers: dict[str, int]):
    arc.print(numbers)


command()
$ python dict_argument.py one=1,two=2,three=3
{'one': 1, 'two': 2, 'three': 3}

Standard Libary Types

typing.Union

Allows the input to be multiple different types.

examples/union_argument.py
from typing import Union
import arc


@arc.command()
def main(number: Union[int, str]):
    arc.print(type(number))


main()
$ python union_argument.py 5
<class 'int'>
$ python union_argument.py hello
<class 'str'>

arc will attempt to coerce the input into each type, from left to right. The first to succeed will be passed along to the command.

Warning

Currently arc's behavior with collections in union types is not defined. As such, it is not reccomended that you give an argument a type similar to typing.Union[list, ...]

Python 3.10's union syntax is also valid: int | str

typing.Literal

Enforces that the input must be a specific sub-set of values

examples/literal_argument.py
from typing import Literal
import arc


@arc.command()
def main(word: Literal["foo", "bar", 1]):
    arc.print(word, type(word))


main()
$ python literal_argument.py foo
foo <class 'str'>
$ python literal_argument.py 1
1 <class 'int'>
$ python literal_argument.py other
USAGE
    literal_argument.py [-h] [--] word

invalid value for word: must be foo, bar or 1

Note

arc compares the input to the string-ified version of each value in the Literal. So for the second example above, the comparison that succedded was "1" == "1" not 1 == 1.

typing.TypedDict

Constrains a dictionary input to a specific subset of keys and specific value types.

pathlib.Path

Path won't perform any validation checks to assert that the input is a valid path, but it just offers the convenience of working with path objects rather than strings. Check the ValidPath custom type for additional validations

enum.Enum

Similar to typing.Literal, restricts the input to a specific sub-set of values

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()
$ python paint.py red
You painted the walls the bloodiest of reds
$ python paint.py blue
USAGE
    paint.py [-h] [--] color

invalid value for color: must be red, yellow or green

ipaddress.IPv4Address

Uses ipaddress.IPv4Address(v) for conversion, so anything valid there is valid here.

ipaddress.IPv6Address

Same as above

re.Pattern

Support for regular expression patterns

arc Types

arc provides a variety of additional types exported from the arc.types module:

Warning

arc types are sort of weird in the general Python sense. While it will become more aparent later as to why this is the case, know that you cannot usually create the types on your own and have the expected behavior. If you do need / want to do this, you can use: arc.convert(<value>, <type>)

Context

Gives you access to the current execution context instance which serves as a central data and functionality object

State

Reference State for details

SemVer

A type to support semantically-versioned strings based on the spec found here

User (UNIX ONLY)

A representation of a unix user.

Group (UNIX ONLY)

A representation of a unix group.

File System Types

File

Get access to an open IO object. Handles opening and closing the file descriptor for you. See reference for full usage

ValidPath

Subclass of pathlib.Path but asserts that the provided path actually exists

FilePath

Subclass of ValidPath but asserts that the path both exists and is a file

DirectoryPath

Subclass of ValidPath but asserts that the path both exists and is a directory

Networking Types

IpAddress

Union type for IPv4Address and IPv6Address

Url

Parses the strings input using urllib.parse.urlparse

HttpUrl

Url that asserts the scheme to be http or https

PostgresUrl

Url that asserts the scheme to be postgresql or postgres

Number Types

Note

For any types that simply change the base of the input (like Binary or Hex), it is essentially equivelant to int(v, base=<base>).

Binary

Accepts integers as binary stings (0101010110).

Oct

Accepts integers in base 8

Hex

Accepts integers in base 16

PositveInt

Enforces that the integer must be greater than 0

NegativeInt

Enforces that the integer must be less than 0

PositveFloat

Enforces that the float must be greater than 0

NegativeFloat

Enforces that the float must be less than 0

AnyNumber

Accepts floats, and integers in any base.

String Types

Char

Enforces that the string can only be a single character long

Password

When prompted for input, the user's input will not be echoed to the screen.