Miscellaneous¶
We will cover the parameter types that don't fit in other thematics in this tutorial. For all the examples, we assume that the file is called cli.py and has a section like the following at the end.
if __name__ == '__main__':
cli()
Note
For windows users, instead of using simple quotes for the following examples related to list parameters, you should use double quotes.
JSON¶
Validates that a string is a valid JSON statement and returns a dict.
import click
from click_params import JSON
@click.command()
@click.option('-j', '--json', 'value', type=JSON)
def cli(value):
click.echo(f'Your fruits and vegetables: {value}')
$ python cli.py -j '{"fruits": ["apples", "strawberries"], "vegetables": ["tomatoes", "cucumbers"]}'
Your fruits and vegetables: {'fruits': ['apples', 'strawberries'], 'vegetables': ['tomatoes', 'cucumbers']}
$ python cli.py -j a
Error: 'a' is not a valid json string
MAC_ADDRESS¶
Validates that a string is a valid mac address.
import click
from click_params import MAC_ADDRESS
@click.command()
@click.option('-m', '--mac-address', 'value', type=MAC_ADDRESS)
def cli(mac_address):
click.echo(f'Your mac address is: {mac_address}')
$ python cli.py -m 01:23:45:67:AB:CD
Your mac address is 01:23:45:67:AB:CD
$ python cli.py -m 00:00:00:00:00
Error: 00:00:00:00:00 is not a valid mac address
MacAddressListParamType¶
Signature: MacAddressListParamType(separator: str = ',')
Validates and returns a list of mac addresses
import click
from click_params import MacAddressListParamType
@click.command()
@click.option('-m', '--mac-addresses', type=MacAddressListParamType(' '),
help='list of mac addresses separated by a white space')
def cli(mac_addresses):
click.echo('Your list of mac addresses:')
for mac_address in mac_addresses:
click.echo(f'- {mac_address}')
$ python cli.py --mac-addresses='00:00:00:00:00:00 01:23:45:67:AB:CD'
Your list of domain names:
- 00:00:00:00:00:00
- 01:23:45:67:AB:CD
$ python cli.py --mac-addresses='foo 01:23:45:67:AB:CD'
Error: These items are not mac addresses: ['foo']
StringListParamType¶
Signature: StringListParamType(separator: str = ',')
Converts given string to a list of strings.
import click
from click_params import StringListParamType
@click.command()
@click.option('-f', '--fruits', type=StringListParamType(' '),
help='list of fruits separated by a white space')
def cli(fruits):
click.echo('Your list of preferred fruits:')
for fruit in fruits:
click.echo(f'- {fruit}')
$ python cli.py --fruits='apples pineaples strawberries'
Your list of preferred fruits:
- apples
- pineapples
- strawberries
UUIDListParamType¶
Signature: UUIDListParamType(separator: str = ',')
Converts string to a list of uuid.UUID
objects.
import click
from click_params import UUIDListParamType
@click.command()
@click.option('-u', '--uuid-list', type=UUIDListParamType(' '))
def cli(uuid_list):
click.echo('Your list of uuid is:')
for uuid in uuid_list:
click.echo(f'- {uuid}')
$ python cli.py --uuid-list='a7309d0b-c858-4d54-b6e1-1c20f8c22047 bfa65f3c-e6ac-4844-8e09-e84535f8cdc5'
Your list of uuid is:
- a7309d0b-c858-4d54-b6e1-1c20f8c22047
- bfa65f3c-e6ac-4844-8e09-e84535f8cdc5
$ python cli.py --uuid-list='452-45 bfa65f3c-e6ac-4844-8e09-e84535f8cdc5 410'
Error: These items are not uuid: ['452-45', '410']
DateTimeParamListType¶
Signature: DateTimeParamListType(separator: str = ',', formats: List[str] = None)
Converts string to a list of datetime.datetime
objects. Unlike other classes, this class has a formats
parameter
that is exactly the same as the one passed to the constructor of click.DateTime
class.
import click
from click_params import DateTimeListParamType
@click.command()
@click.option('-d', '--datetimes', type=DateTimeListParamType(', '))
def cli(datetimes):
click.echo('The dates your entered are:')
for datetime in datetimes:
click.echo(f'- {datetime}')
$ python cli.py --datetimes='2018-04-05, 2019-01-01 01:00:00'
The dates your entered are:
- 2018-04-05 00:00:00
- 2019-01-01 01:00:00
$ python cli.py --datetimes='2019/01/01, 2019-01-01'
Error: These items are not datetimes: ['2019/01/01']
Two remarks compared to the last script.
- The separator used for the previous command is
', '
. This come in handy because one of the datetime passed as option has a whitespace, therefore the separator helps to split properly. - In the last example the datetime
2019/01/01
fails because the format%Y/%m/%d
is not one of the defaults used byclick.DateTime
. If you want this datetime to be accepted, you need to provide aformats
argument with the appropriate formats.
UnionParamType¶
Signature: UnionParamType(param_types: Sequence[click.ParamType], name: str = None)
Allows an option or an argument to accept at least two kinds of types.
import click
from click_params import UnionParamType
@click.command()
@click.option('-j', '--jobs', type=UnionParamType([click.Choice(['half', 'all']), click.INT], name="cores number"))
def cli(jobs):
click.echo('Running on {jobs} cores!'.format(jobs=jobs))
...
$ python cli.py -j 5
Running on 5 cores
$ python cli.py -j all
Running on all cores
$ python cli.py -j 2.5
Error: 2.5 is not a valid cores number
$ python cli.py -j third
Error: third is not a valid cores number
Two remarks compared to the last script.
- The order of parameter types in the union is the order click will try to parse the value.
- In the last two examples click was unable to parse because they were neither an integer nor a string from allowed choices.