diff --git a/docs/api/functions.md b/docs/api/functions.md index 7e31012..91dfcfd 100644 --- a/docs/api/functions.md +++ b/docs/api/functions.md @@ -26,6 +26,40 @@ Given a function, or a container of functions `obj`, parse its arguments from th | Type | Description | |------|-------------| | `Any` | The return value of the function `obj`, or the subcommand of `obj` if it is a list or dict. | + + + +## `parse()` + +```python +def parse( + cls: type[~T], + args: list[str] | None = None, + brief: str = '', + caught: bool = True, +) -> ~T +``` + +Given a class `cls`, parse arguments from the command-line according to the class definition and construct an instance. + +### Parameters: + +| Name | Type | Description | Default | +|------|------|-------------|---------| +| `cls` | type[~T] | The class to parse the arguments for and construct an instance of. | _required_ | +| `args` | list[str] \| None | The arguments to parse. If None, uses the arguments from the command-line (i.e. sys.argv). | `None` | +| `brief` | str | The brief description of the parser. This is used to display a brief when --help is invoked. | `''` | +| `caught` | bool | Whether to catch and print errors instead of raising. This is used to display a more presentable output when a parse error occurs instead of the default traceback. | `True` | + + +### Returns: + +| Type | Description | +|------|-------------| +| `~T` | An instance of the class `cls`. | + + + ## `register()` ```python diff --git a/docs/make_api.py b/docs/make_api.py index 5e4ca42..e50a25d 100644 --- a/docs/make_api.py +++ b/docs/make_api.py @@ -3,7 +3,7 @@ from collections import abc from typing import Any, Callable, TextIO, Union, get_args, get_origin -from startle import register, start +from startle import parse, register, start from startle.inspect import _parse_func_docstring @@ -76,7 +76,7 @@ def func_api(func: Callable, file: TextIO): for param in sig.parameters.values(): maybe_default = "" if param.default is not inspect.Parameter.empty: - maybe_default = f" = {param.default}" + maybe_default = f" = {repr(param.default)}" print( f" {param.name}: {_shorten_type_annotation(param.annotation)}{maybe_default},", file=file, @@ -101,7 +101,7 @@ def func_api(func: Callable, file: TextIO): if default is inspect.Parameter.empty: default = "_required_" else: - default = f"`{default}`" + default = f"`{repr(default)}`" print(f"| {name} | {typ} | {desc} | {default} |", file=file) print("\n", file=file) @@ -117,10 +117,12 @@ def func_api(func: Callable, file: TextIO): rt = f"`{rt}`" desc = _parse_return_description(func) print(f"| {rt} | {desc} |", file=file) + print("\n\n", file=file) if __name__ == "__main__": with open("docs/api/functions.md", "w") as f: print("# Functions\n", file=f) func_api(start, f) + func_api(parse, f) func_api(register, f)