hydraclick.core =============== .. py:module:: hydraclick.core Attributes ---------- .. autoapisummary:: hydraclick.core._logger hydraclick.core.FLOGGING_AVAILABLE Functions --------- .. autoapisummary:: hydraclick.core.wrap_kwargs_and_config hydraclick.core.build_hydra_args hydraclick.core.get_default_dir hydraclick.core.run_hydra hydraclick.core.command_api hydraclick.core.hydra_command Module Contents --------------- .. py:data:: _logger .. py:data:: FLOGGING_AVAILABLE :value: True .. py:function:: wrap_kwargs_and_config(function, as_kwargs = False, print_config = True, preprocess_config = None, resolve = True) Wrap a function to run as a hydra command. .. py:function:: build_hydra_args(hydra_help, version, show_config, resolve, package, info, run, multirun, config_path, config_name, config_dir, shell_completion, hydra_args = None) Compose the arguments for the hydra command. .. py:function:: get_default_dir() Get the default directory for the hydra config. .. py:function:: run_hydra(function, hydra_args, config_path = None, config_name = 'config', version_base = None, use_flogging = True, **flogging_kwargs) Run a function as a Hydra app. :param function: The function to be executed as a Hydra command. This function should accept a `DictConfig` object as its argument. :type function: Callable :param hydra_args: The arguments to pass to the Hydra command. :type hydra_args: tuple[str, ...] :param config_path: The path to the configuration directory. If not specified, the default directory is used, which is the current working directory/config. Defaults to None. :type config_path: str | None, optional :param config_name: The name of the configuration file (without the `.yaml` or `.yml` extension). Defaults to "config". :type config_name: str | None, optional :param version_base: The base version of the configuration. Defaults to None. :type version_base: str | None, optional :param use_flogging: Whether to use the `flogging` library for structured logging. Defaults to True. :type use_flogging: bool, optional :param \*\*flogging_kwargs: Additional keyword arguments to pass to the `flogging.setup` function. :type \*\*flogging_kwargs: Any, optional :returns: Then return value of the function. .. py:function:: command_api(function, config_path = None, config_name = 'config', version_base = None, as_kwargs = False, preprocess_config = None, print_config = True, resolve = True, use_flogging = True, terminal_effect = omegaconf.MISSING, **flogging_kwargs) Integrate Hydra's configuration management capabilities with a Click-based CLI. :param function: The function to be executed as a Hydra command. This function should accept a `DictConfig` object as its argument. :type function: Callable[[DictConfig], Any] :param config_path: The path to the configuration directory. If not specified, the default directory is used. :type config_path: str | Path | None, optional :param config_name: The name of the configuration file (without the `.yaml` or `.yml` extension). Defaults to `"config"`. :type config_name: str | None, optional :param version_base: The base version of the configuration. Defaults to `None`. :type version_base: str | None, optional :param as_kwargs: The mode in which to run the function. If `True`, the function is run with the configuration as keyword arguments. In this case the configuration is converted to a dictionary before passing it to the function. Defaults to `False`. :type as_kwargs: bool, optional :param preprocess_config: A function to preprocess the configuration before passing it to the main function. Defaults to `None`. :type preprocess_config: Callable[[DictConfig], DictConfig] | None, optional :param print_config: Whether to print the configuration before running the function. Defaults to `True`. :type print_config: bool, optional :param resolve: Whether to resolve the configuration before running the function. Defaults to `True`. :type resolve: bool, optional :param use_flogging: Whether to use the `flogging` library for structured logging. Defaults to `True`. :type use_flogging: bool, optional :param terminal_effect: The terminal effect function to use when rendering the command help. :type terminal_effect: Callable | None, optional :param \*\*flogging_kwargs: Additional keyword arguments to pass to the `flogging.setup` function. :type \*\*flogging_kwargs: Any, optional :returns: A Click-compatible command function that can be used as a CLI command. :rtype: Callable .. rubric:: Example ```python from omegaconf import DictConfig def my_function(config: DictConfig): print(config.pretty()) click_command = command_api( function=my_function, config_path="path/to/config", config_name="my_config", version_base="1.0", run_mode="config", preprocess_config=None, print_config=True, resolve=True, use_flogging=True, allow_trailing_dot=True ) ``` In this example, `my_function` is wrapped by `command_api` to create a Click-compatible command. The configuration is loaded from the specified `config_path` and `config_name`, and the function is executed with the resolved configuration. .. rubric:: Notes - The `command_api` function uses several Hydra and Click decorators to provide a rich CLI experience. - If `use_flogging` is enabled but the `flogging` library is not available, a warning is logged, and `flogging` is disabled. - The `preprocess_config` function, if provided, allows for custom preprocessing of the configuration before it is passed to the main function. .. py:function:: hydra_command(config_path = None, config_name = 'config', version_base = None, as_kwargs = False, preprocess_config = None, print_config = True, resolve = True, use_flogging = True, terminal_effect = omegaconf.MISSING, **flogging_kwargs) Integrate Hydra's configuration management capabilities with a Click-based CLI. :param config_path: The path to the configuration directory. If not specified, the default directory is used. :type config_path: str | Path | None, optional :param config_name: The name of the configuration file (without the `.yaml` or `.yml` extension). Defaults to `"config"`. :type config_name: str | None, optional :param version_base: The base version of the configuration. Defaults to `None`. :type version_base: str | None, optional :param as_kwargs: The mode in which to run the function. If `True`, the function is run with the configuration as keyword arguments. In this case the configuration is converted to a dictionary before passing it to the function. Defaults to `False`. :type as_kwargs: bool, optional :param preprocess_config: A function to preprocess the configuration before passing it to the main function. Defaults to `None`. :type preprocess_config: Callable[[DictConfig], DictConfig] | None, optional :param print_config: Whether to print the configuration before running the function. Defaults to `True`. :type print_config: bool, optional :param resolve: Whether to resolve the configuration before running the function. Defaults to `True`. :type resolve: bool, optional :param use_flogging: Whether to use the `flogging` library for structured logging. Defaults to `True`. :type use_flogging: bool, optional :param terminal_effect: The terminal effect function to use when rendering the command help. :type terminal_effect: Callable | None, optional :param \*\*flogging_kwargs: Additional keyword arguments to pass to the `flogging.setup` function. :type \*\*flogging_kwargs: Any, optional :returns: A Click-compatible command function that can be used as a CLI command. :rtype: Callable .. rubric:: Notes - The `command_api` function uses several Hydra and Click decorators to provide a rich CLI experience. - If `use_flogging` is enabled but the `flogging` library is not available, a warning is logged, and `flogging` is disabled. - The `preprocess_config` function, if provided, allows for custom preprocessing of the configuration before it is passed to the main function.