Hydraclick

Hydraclick is an open-source Python package that seamlessly integrates Hydra and Click to create production-grade command-line interfaces (CLIs). It leverages Hydra's powerful configuration management with Click's user-friendly CLI creation to provide a robust foundation for building complex CLI applications.

Features

• Configuration Management: Utilize Hydra's dynamic configuration capabilities for flexible CLI options.
• Structured Logging: Integrate with flogging for structured and efficient logging.
• Easy Decorators: Simple decorators to convert functions into CLI commands.
• Extensible: Easily extend and customize to fit your project's needs.
• Shell Completion: Support for generating shell completion scripts.

Installation

Install Hydraclick via pip:

pip install hydraclick

Supported Python Versions

Hydraclick supports the following Python versions:

• Python 3.9
• Python 3.10
• Python 3.11
• Python 3.12

Supported Operating Systems

Hydraclick is compatible with the following operating systems:

• Ubuntu (latest)
• macOS (latest)

Getting Started

Basic Usage

Define your function and decorate it with @hydra_command to create a CLI command.

from omegaconf import DictConfig
from hydraclick import hydra_command

@hydra_command(config_path="config_folder", config_name="file_without_extension")
def my_function(config: DictConfig):
    print(f"Running with config: {config.pretty()}")

Running the CLI

After defining your function, you can run it from the command line:

python my_script.py --config-path path/to/config --config-name my_config

Example

Here's a complete example of creating a CLI with Hydraclick:

import sys
from omegaconf import DictConfig
from hydraclick import hydra_command

@hydra_command(config_path="configs", config_name="app_config", as_kwargs=True)
def main(**kwargs):
    print(f"Running with config: {kwargs}")

if __name__ == "__main__":
    main()

API Reference

hydra_command

Decorator to create CLI commands.

import omegaconf

def hydra_command(
        config_path: str | Path | None = None,
        config_name: str | None = "config",
        version_base: str | None = None,
        as_kwargs: bool = False,
        preprocess_config: Callable[[DictConfig], DictConfig] | None = None,
        print_config: bool = True,
        resolve: bool = True,
        use_flogging: bool = True,
        terminal_effect: Callable | None = omegaconf.MISSING,
        **flogging_kwargs: Any,
) -> Callable:

Configuration Options

Hydraclick provides several configuration options to customize your CLI:

• config_path: Path to the configuration directory. Passed to hydra.main()
• config_name: Name of the configuration file. Passed to hydra.main()
• version_base: Base version of the configuration. Passed to hydra.main()
• 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. If False, pass the configuration as a single OmegaConf.DictConfig object. Defaults to False.
• preprocess_config: Function to preprocess the configuration. It takes a DictConfig object and returns a DictConfig object.
• print_config: Whether to print the configuration before execution.
• resolve: Whether to resolve the configuration.
• use_flogging: Whether to use flogging for structured logging.
• **flogging_kwargs: Additional keyword arguments for flogging.
• terminal_effect: The terminal effect function to use when rendering the command help.

Logging with Flogging

Hydraclick integrates with flogging for structured logging. To enable flogging, ensure it's installed:

pip install hydraclick[flogging]

pip install flogging

If flogging is not available, Hydraclick will log a warning and disable structured logging.

Terminal Text Effects

Hydraclick supports terminal text effects using the Terminal Text Effects library to enhance the user experience with animated and styled text outputs in the terminal. Install the library with:

pip install hydraclick[terminaltexteffects]

pip install terminaltexteffects

Installing all the extras

To install all the extras, use the following command:

pip install hydraclick[all]

Shell Completion

Hydraclick supports generating shell completion scripts. Use the --shell-completion option to generate scripts for your preferred shell.

cli_app command --shell-completion install=bash > my_script_completion.sh
source my_script_completion.sh

Contribution

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Commit your changes with clear messages.
4. Submit a pull request detailing your changes.

For major changes, please open an issue first to discuss your ideas.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

If you encounter any issues or have questions, feel free to open an issue on the GitHub repository.

Acknowledgements

• Hydra for powerful configuration management.
• Click for creating beautiful CLIs.
• Flogging for structured logging.
• Terminal Text Effects for enhancing terminal help text output.