0.9.3

docs/source/examples/basics.rst

@@ -652,7 +652,9 @@ Configuration via typing.Annotated[]
 
 The :mod:`tyro.conf` module contains utilities that can be used in conjunction
 with :py:data:`typing.Annotated` to configure command-line interfaces beyond
-what is expressible via static type annotations.
+what is expressible via static type annotations. To apply options globally,
+these same flags can also be passed via the ``config`` argument of
+:func:`tyro.cli`.
 
 Features here are supported, but generally unnecessary and should be used sparingly.
 
@@ -672,8 +674,8 @@ Features here are supported, but generally unnecessary and should be used sparin
         # A numeric field parsed as a positional argument.
         positional: tyro.conf.Positional[int]
 
-        # A boolean field with flag conversion turned off.
-        boolean: tyro.conf.FlagConversionOff[bool] = False
+        # A boolean field.
+        boolean: bool = False
 
         # A numeric field that can't be changed via the CLI.
         fixed: tyro.conf.Fixed[int] = 5
@@ -689,7 +691,7 @@ Features here are supported, but generally unnecessary and should be used sparin
         ] = "Hello"
 
     if __name__ == "__main__":
-        print(tyro.cli(Args))
+        print(tyro.cli(Args, config=(tyro.conf.FlagConversionOff,)))
 
 
 
@@ -706,8 +708,7 @@ Features here are supported, but generally unnecessary and should be used sparin
     <span style="font-weight: lighter">╰────────────────────────────────────────────────────────────────────────────╯</span>
     <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> options </span><span style="font-weight: lighter">─────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
     <span style="font-weight: lighter">│</span> -h, --help              <span style="font-weight: lighter">show this help message and exit</span>                    <span style="font-weight: lighter">│</span>
-    <span style="font-weight: lighter">│</span> --boolean <span style="font-weight: bold">{True,False}</span>  <span style="font-weight: lighter">A boolean field with flag conversion turned off.</span>   <span style="font-weight: lighter">│</span>
-    <span style="font-weight: lighter">│</span>                         <span style="color: #008080">(default: False)</span>                                   <span style="font-weight: lighter">│</span>
+    <span style="font-weight: lighter">│</span> --boolean <span style="font-weight: bold">{True,False}</span>  <span style="font-weight: lighter">A boolean field.</span> <span style="color: #008080">(default: False)</span>                  <span style="font-weight: lighter">│</span>
     <span style="font-weight: lighter">│</span> --fixed <span style="font-weight: bold; color: #800000">{fixed}</span>         <span style="font-weight: lighter">A numeric field that can't be changed via the CLI.</span> <span style="font-weight: lighter">│</span>
     <span style="font-weight: lighter">│</span>                         <span style="color: #008080">(fixed to: 5)</span>                                      <span style="font-weight: lighter">│</span>
     <span style="font-weight: lighter">│</span> --renamed <span style="font-weight: bold">STRING</span>        <span style="font-weight: lighter">A field with manually overridden properties!</span>       <span style="font-weight: lighter">│</span>

examples/01_basics/09_conf.py

@@ -2,7 +2,9 @@
 
 The :mod:`tyro.conf` module contains utilities that can be used in conjunction
 with :py:data:`typing.Annotated` to configure command-line interfaces beyond
-what is expressible via static type annotations.
+what is expressible via static type annotations. To apply options globally,
+these same flags can also be passed via the ``config`` argument of
+:func:`tyro.cli`.
 
 Features here are supported, but generally unnecessary and should be used sparingly.
 
@@ -24,8 +26,8 @@ class Args:
     # A numeric field parsed as a positional argument.
     positional: tyro.conf.Positional[int]
 
-    # A boolean field with flag conversion turned off.
-    boolean: tyro.conf.FlagConversionOff[bool] = False
+    # A boolean field.
+    boolean: bool = False
 
     # A numeric field that can't be changed via the CLI.
     fixed: tyro.conf.Fixed[int] = 5
@@ -42,4 +44,4 @@ class Args:
 
 
 if __name__ == "__main__":
-    print(tyro.cli(Args))
+    print(tyro.cli(Args, config=(tyro.conf.FlagConversionOff,)))

src/tyro/__init__.py

@@ -1,6 +1,6 @@
 from typing import TYPE_CHECKING
 
-__version__ = "0.9.2"
+__version__ = "0.9.3"
 
 
 from . import conf as conf

src/tyro/_cli.py

@@ -149,7 +149,7 @@ def cli(
             main one.
         config: Sequence of config marker objects, from :mod:`tyro.conf`. As an
             alternative to using them locally in annotations
-            (:class:`tyro.conf.FlagConversionOff`[bool]), we can also pass in a sequence of
+            (``FlagConversionOff[bool]``), we can also pass in a sequence of
             them here to apply globally.
 
     Returns:
@@ -162,9 +162,6 @@ def cli(
     # memory address conflicts.
     _unsafe_cache.clear_cache()
 
-    if config is not None:
-        f = Annotated[(f, *config)]  # type: ignore
-
     with _strings.delimeter_context("_" if use_underscores else "-"):
         output = _cli_impl(
             f,
@@ -176,6 +173,7 @@ def cli(
             return_unknown_args=return_unknown_args,
             use_underscores=use_underscores,
             console_outputs=console_outputs,
+            config=config,
             **deprecated_kwargs,
         )
 
@@ -200,6 +198,7 @@ def get_parser(
     default: None | OutT = None,
     use_underscores: bool = False,
     console_outputs: bool = True,
+    config: None | Sequence[conf._markers.Marker] = None,
 ) -> argparse.ArgumentParser: ...
 
 
@@ -212,6 +211,7 @@ def get_parser(
     default: None | OutT = None,
     use_underscores: bool = False,
     console_outputs: bool = True,
+    config: None | Sequence[conf._markers.Marker] = None,
 ) -> argparse.ArgumentParser: ...
 
 
@@ -225,6 +225,7 @@ def get_parser(
     default: None | OutT = None,
     use_underscores: bool = False,
     console_outputs: bool = True,
+    config: None | Sequence[conf._markers.Marker] = None,
 ) -> argparse.ArgumentParser:
     """Get the ``argparse.ArgumentParser`` object generated under-the-hood by
     :func:`tyro.cli()`. Useful for tools like ``sphinx-argparse``, ``argcomplete``, etc.
@@ -244,6 +245,7 @@ def get_parser(
                 return_unknown_args=False,
                 use_underscores=use_underscores,
                 console_outputs=console_outputs,
+                config=config,
             ),
         )
 
@@ -258,6 +260,7 @@ def _cli_impl(
     return_parser: bool,
     return_unknown_args: bool,
     console_outputs: bool,
+    config: None | Sequence[conf._markers.Marker],
     **deprecated_kwargs,
 ) -> (
     OutT
@@ -268,6 +271,10 @@ def _cli_impl(
     ]
 ):
     """Helper for stitching the `tyro` pipeline together."""
+
+    if config is not None:
+        f = Annotated[(f, *config)]  # type: ignore
+
     if "default_instance" in deprecated_kwargs:
         warnings.warn(
             "`default_instance=` is deprecated! use `default=` instead.", stacklevel=2

src/tyro/conf/__init__.py

@@ -1,9 +1,12 @@
 """The :mod:`tyro.conf` submodule contains helpers for attaching parsing-specific
-configuration metadata to types via [PEP 593](https://peps.python.org/pep-0593/) runtime
+configuration metadata to types via `PEP 593 <https://peps.python.org/pep-0593/>`_ runtime
 annotations.
 
-Configuration flags are applied recursively, and should generally be subscripted:
-``Fixed[T]``, ``Suppress[T]``, etc.
+Flags will be applied recursively, and can be used one of multiple ways:
+
+1. They can be subscripted: ``tyro.conf.FlagConversionoff[bool]``.
+2. They can be passed into :py:data:`typing.Annotated`: ``Annotated[str, tyro.conf.FlagConversionOff]``.
+3. They can be passed into :func:`tyro.cli`: ``tyro.cli(Args, config=(tyro.conf.FlagConversionOff,))``.
 
 Features here are supported, but generally unnecessary and should be used sparingly.
 """

src/tyro/conf/_markers.py

@@ -130,7 +130,7 @@
 """
 
 UseCounterAction = Annotated[T, None]
-"""Use "counter" actions for integer arguments. Example usage: ``verbose: UseCounterAction[int]``."""
+"""Use "counter" actions for integer arguments. Should be used with integers, ``UseCounterAction[int]``."""
 
 EnumChoicesFromValues = Annotated[T, None]
 """Populate choices from enum values rather than enum names.