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.
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(v) to convert the value. Note that decimal input (
1.4) will result in an error, not a narrowing operation.
Likewise, arc uses
float(v). Ingeter values will be converted to a float (
2 -> 2.0)
Used to denote a
Collection types are used by arc to collect multiple values into a single argument. Check the next page for information on how that works
Allows a list of comma-seperated key-value pairs. Can be typed generically on both keys and values.
Standard Libary Types¶
Allows the input to be multiple different types.
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.
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
Python 3.10's union syntax is also valid:
int | str
Enforces that the input must be a specific sub-set of values
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.
Constrains a dictionary input to a specific subset of keys and specific value types.
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
typing.Literal, restricts the input to a specific sub-set of values
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()
ipaddress.IPv4Address(v) for conversion, so anything valid there is valid here.
Same as above
Support for regular expression patterns
arc provides a variety of additional types exported from the
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:
Gives you access to the current execution context instance which serves as a central data and functionality object
Reference State for details
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¶
Get access to an open IO object. Handles opening and closing the file descriptor for you. See reference for full usage
pathlib.Path but asserts that the provided path actually exists
ValidPath but asserts that the path both exists and is a file
ValidPath but asserts that the path both exists and is a directory
Union type for
Parses the strings input using
Url that asserts the scheme to be
Url that asserts the scheme to be
For any types that simply change the base of the input (like
Hex), it is essentially equivelant to
Accepts integers as binary stings (
Accepts integers in base 8
Accepts integers in base 16
Enforces that the integer must be greater than 0
Enforces that the integer must be less than 0
Enforces that the float must be greater than 0
Enforces that the float must be less than 0
Accepts floats, and integers in any base.
Enforces that the string can only be a single character long
When prompted for input, the user's input will not be echoed to the screen.