| Name | hydraclick JSON |
| Version |
0.0.8
JSON |
| download |
| home_page | None |
| Summary | Develop CLI tools with top-notch config management like a boss. |
| upload_time | 2024-09-23 16:18:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2024 Fragile Tech Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
cli
config
hydra
omegaconf
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Hydraclick
Hydraclick is an open-source Python package that seamlessly integrates [Hydra](https://hydra.cc/) and [Click](https://click.palletsprojects.com/) 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:
```bash
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.
```python
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:
```bash
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:
```python
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.
```python
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()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)
- `config_name`: Name of the configuration file. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)
- `version_base`: Base version of the configuration. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)
- `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](https://github.com/FragileTech/flogging) for structured logging.
To enable flogging, ensure it's installed:
```bash
pip install hydraclick[flogging]
```
```bash
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](https://chrisbuilds.github.io/terminaltexteffects/) library to enhance the user experience with animated and styled text outputs in the terminal.
Install the library with:
```bash
pip install hydraclick[terminaltexteffects]
```
```bash
pip install terminaltexteffects
```
## Installing all the extras
To install all the extras, use the following command:
```bash
pip install hydraclick[all]
```
## Shell Completion
Hydraclick supports generating shell completion scripts. Use the `--shell-completion` option to generate scripts for your preferred shell.
```bash
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](LICENSE) file for details.
## Support
If you encounter any issues or have questions, feel free to open an issue on the [GitHub repository](https://github.com/yourusername/hydraclick).
## Acknowledgements
- [Hydra](https://hydra.cc/) for powerful configuration management.
- [Click](https://click.palletsprojects.com/) for creating beautiful CLIs.
- [Flogging](https://github.com/FragileTech/flogging) for structured logging.
- [Terminal Text Effects](https://chrisbuilds.github.io/terminaltexteffects) for enhancing terminal help text output.
Raw data
{
"_id": null,
"home_page": null,
"name": "hydraclick",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Guillem Duran Ballester <guillem@fragile.tech>",
"keywords": "CLI, config, hydra, omegaconf",
"author": null,
"author_email": "Guillem Duran Ballester <guillem@fragile.tech>",
"download_url": "https://files.pythonhosted.org/packages/1a/70/2d9fe446e229f601eacfb5425d3a0b8f126e57d8941e50971fbf8d0ddfce/hydraclick-0.0.8.tar.gz",
"platform": null,
"description": "# Hydraclick\n\nHydraclick is an open-source Python package that seamlessly integrates [Hydra](https://hydra.cc/) and [Click](https://click.palletsprojects.com/) 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.\n\n## Features\n\n- **Configuration Management**: Utilize Hydra's dynamic configuration capabilities for flexible CLI options.\n- **Structured Logging**: Integrate with flogging for structured and efficient logging.\n- **Easy Decorators**: Simple decorators to convert functions into CLI commands.\n- **Extensible**: Easily extend and customize to fit your project's needs.\n- **Shell Completion**: Support for generating shell completion scripts.\n\n## Installation\n\nInstall Hydraclick via pip:\n\n```bash\npip install hydraclick\n```\n\n### Supported Python Versions\n\nHydraclick supports the following Python versions:\n\n- Python 3.9\n- Python 3.10\n- Python 3.11\n- Python 3.12\n\n### Supported Operating Systems\n\nHydraclick is compatible with the following operating systems:\n\n- Ubuntu (latest)\n- macOS (latest)\n\n## Getting Started\n\n### Basic Usage\n\nDefine your function and decorate it with `@hydra_command` to create a CLI command.\n\n```python\nfrom omegaconf import DictConfig\nfrom hydraclick import hydra_command\n\n@hydra_command(config_path=\"config_folder\", config_name=\"file_without_extension\")\ndef my_function(config: DictConfig):\n print(f\"Running with config: {config.pretty()}\")\n```\n\n### Running the CLI\n\nAfter defining your function, you can run it from the command line:\n\n```bash\npython my_script.py --config-path path/to/config --config-name my_config\n```\n\n### Example\n\nHere's a complete example of creating a CLI with Hydraclick:\n\n```python\nimport sys\nfrom omegaconf import DictConfig\nfrom hydraclick import hydra_command\n\n@hydra_command(config_path=\"configs\", config_name=\"app_config\", as_kwargs=True)\ndef main(**kwargs):\n print(f\"Running with config: {kwargs}\")\n\nif __name__ == \"__main__\":\n main()\n```\n\n## API Reference\n\n### `hydra_command`\n\nDecorator to create CLI commands.\n\n```python\nimport omegaconf\n\ndef hydra_command(\n config_path: str | Path | None = None,\n config_name: str | None = \"config\",\n version_base: str | None = None,\n as_kwargs: bool = False,\n preprocess_config: Callable[[DictConfig], DictConfig] | None = None,\n print_config: bool = True,\n resolve: bool = True,\n use_flogging: bool = True,\n terminal_effect: Callable | None = omegaconf.MISSING,\n **flogging_kwargs: Any,\n) -> Callable:\n```\n\n## Configuration Options\n\nHydraclick provides several configuration options to customize your CLI:\n\n- `config_path`: Path to the configuration directory. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)\n- `config_name`: Name of the configuration file. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)\n- `version_base`: Base version of the configuration. Passed to [`hydra.main()`](https://hydra.cc/docs/tutorials/basic/your_first_app/config_file/)\n- `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`.\n- `preprocess_config`: Function to preprocess the configuration. It takes a `DictConfig` object and returns a `DictConfig` object.\n- `print_config`: Whether to print the configuration before execution.\n- `resolve`: Whether to resolve the configuration.\n- `use_flogging`: Whether to use flogging for structured logging.\n- `**flogging_kwargs`: Additional keyword arguments for flogging.\n- `terminal_effect`: The terminal effect function to use when rendering the command help.\n\n## Logging with Flogging\n\nHydraclick integrates with [flogging](https://github.com/FragileTech/flogging) for structured logging.\nTo enable flogging, ensure it's installed:\n\n```bash\npip install hydraclick[flogging]\n```\n\n```bash\npip install flogging\n```\n\nIf `flogging` is not available, Hydraclick will log a warning and disable structured logging.\n\n## Terminal Text Effects\n\nHydraclick supports terminal text effects using the [Terminal Text Effects](https://chrisbuilds.github.io/terminaltexteffects/) library to enhance the user experience with animated and styled text outputs in the terminal.\nInstall the library with:\n```bash\npip install hydraclick[terminaltexteffects]\n```\n\n```bash\npip install terminaltexteffects\n```\n\n## Installing all the extras\n\nTo install all the extras, use the following command:\n\n```bash\npip install hydraclick[all]\n```\n\n## Shell Completion\n\nHydraclick supports generating shell completion scripts. Use the `--shell-completion` option to generate scripts for your preferred shell.\n\n```bash\ncli_app command --shell-completion install=bash > my_script_completion.sh\nsource my_script_completion.sh\n```\n\n## Contribution\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch for your feature or bugfix.\n3. Commit your changes with clear messages.\n4. Submit a pull request detailing your changes.\n\nFor major changes, please open an issue first to discuss your ideas.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Support\n\nIf you encounter any issues or have questions, feel free to open an issue on the [GitHub repository](https://github.com/yourusername/hydraclick).\n\n## Acknowledgements\n\n- [Hydra](https://hydra.cc/) for powerful configuration management.\n- [Click](https://click.palletsprojects.com/) for creating beautiful CLIs.\n- [Flogging](https://github.com/FragileTech/flogging) for structured logging.\n- [Terminal Text Effects](https://chrisbuilds.github.io/terminaltexteffects) for enhancing terminal help text output.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Fragile Tech Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Develop CLI tools with top-notch config management like a boss.",
"version": "0.0.8",
"project_urls": null,
"split_keywords": [
"cli",
" config",
" hydra",
" omegaconf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "354abb8012067d372b474ea6d651b687aa7413a272745ccaab512e05d8c1852d",
"md5": "701e5089001c6739d825c4624868539c",
"sha256": "af384b0d2a3d30a274db095d72ad1ba97be920dba4441762dd9d1e5f25e7ce67"
},
"downloads": -1,
"filename": "hydraclick-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "701e5089001c6739d825c4624868539c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15163,
"upload_time": "2024-09-23T16:18:54",
"upload_time_iso_8601": "2024-09-23T16:18:54.776729Z",
"url": "https://files.pythonhosted.org/packages/35/4a/bb8012067d372b474ea6d651b687aa7413a272745ccaab512e05d8c1852d/hydraclick-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1a702d9fe446e229f601eacfb5425d3a0b8f126e57d8941e50971fbf8d0ddfce",
"md5": "248bdf9ed09766668c0fff59b25ac474",
"sha256": "a7bce76a0bca4940f8b4583a6462c0456e3809bf7643633bbf18236b4b62696a"
},
"downloads": -1,
"filename": "hydraclick-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "248bdf9ed09766668c0fff59b25ac474",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 23368,
"upload_time": "2024-09-23T16:18:55",
"upload_time_iso_8601": "2024-09-23T16:18:55.879352Z",
"url": "https://files.pythonhosted.org/packages/1a/70/2d9fe446e229f601eacfb5425d3a0b8f126e57d8941e50971fbf8d0ddfce/hydraclick-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 16:18:55",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hydraclick"
}
