Test that type annotations match click parameter types
Project description
click-type-test
Table of Contents
Overview
click-type-test
allows you to test that your
click
options and arguments
match your type annotations.
It is named by the trio of things which it supports:
click
: build a CLItype
: add type annotationstest
: test that the first two match
Installation
click-type-test
only works on Python 3.10+ .
On supported python versions, it should be installed with
pip install click-type-test
Usage
Install the package and then use click_type_test
to extract annotation data
and check it against your commands.
from click_type_test import check_param_annotations
from foopkg import mycommand
def test_mycommand_annotations():
check_param_annotations(mycommand)
check_param_annotations
raises a
click_type_test.BadAnnotationError
if an annotation does not match.
Version Guarding
Just because click-type-test
only works on certain pythons does not mean that
your application, tested with it, is also restricted to those python versions.
You can guard your usage like so (under pytest
):
import pytest
import sys
from foopkg import mycommand
@pytest.mark.skipif(
sys.version_info < (3, 10),
reason="click-type-test requires py3.10+",
)
def test_mycommand_annotations():
from click_type_test import check_param_annotations
check_param_annotations(mycommand)
Extending And Adjusting With AnnotatedParamType and AnnotatedOption
The type deductions made by click-type-test
are not always going to be
correct. But rather than skipping options or parameters, it's better to
pass along the information needed if possible.
Custom parameter types can support usage with click-type-test
by implementing
the AnnotatedParamType
protocol.
Similarly, custom click.Option
subclasses can support specialized usage by
implementing the AnnotatedOption
protocol.
The path you take will depend a bit on the precise needs of your CLI, but it
generally should be possible to tune click-type-test
to correctly understand
your CLI.
AnnotatedParamType
If you have a custom ParamType
, extend it to implement the
AnnotatedParamType
protocol and it will have first-class support in
click-type-test
.
This requires that there be a method, get_type_annotation
, which takes the
click.Parameter
which was used and returns the type which should be expected
as an annotation.
For example, here's a CommaDelimitedList
type which implements
AnnotatedParamType
:
import click
class CommaDelimitedList(click.ParamType):
def get_type_annotation(self, param: click.Parameter) -> type:
return list[str]
def get_metavar(self, param: click.Parameter) -> str:
return "TEXT,TEXT,..."
def convert(
self, value: str, param: click.Parameter | None, ctx: click.Context | None
) -> list[str]:
value = super().convert(value, param, ctx)
return value.split(",") if value else []
You can check that a ParamType
implements AnnotatedParamType
with
a simple isinstance
check:
import click_type_test
isinstance(myparamtype, click_type_test.AnnotatedParamType)
AnnotatedParameter
If you have a subclass of Option
or Argument
which produces specialized
values, it may be necessary to provide type information from that class.
To handle this case, just have your parameter class implement the
AnnotatedParameter
protocol.
This requires a method, has_explicit_annotation
, and a property
type_annotation
.
has_explicit_annotation
takes no arguments and returns a bool.
type_annotation
returns a type
.
See
examples/explicitly_annotation_option.py
for an example.
You can check that a Parameter
implements AnnotatedParameter
with
a simple isinstance
check:
import click_type_test
isinstance(myparam, click_type_test.AnnotatedParameter)
API
The following values are the consumable API for click-type-test
.
No other values are part of the interface.
-
AnnotatedParamType
: a protocol forclick.ParamType
subclasses which provide explicit type information. It is runtime checkable. -
AnnotatedParameter
: a protocol forclick.Parameter
subclasses which provide explicit type information. It is runtime checkable. -
deduce_type_from_parameter
: a function which takes aclick.Parameter
and returns a type. Used internally but useful for unit testing custom classes. -
check_param_annotations
: a function which takes aclick.Command
and checks the type annotations on its callback against its parameter list. -
BadAnnotationError
: the error type raised if checking annotations fails.
License
click-type-test
is distributed under the terms of the MIT license.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for click_type_test-0.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fff69dfc41f9a44222a3438facf4e612dd5f27b80208c034bc35ba8d2a56c04c |
|
MD5 | c04c960f8e5bd33b09a726f038f42e57 |
|
BLAKE2b-256 | af989e8602e0900c38ae34be658ae0e7e4e3e15f09d9093f1cf34948bff0358e |