Release/0.1.0 alpha

.github/workflows/_zrb.yml

@@ -17,7 +17,7 @@ jobs:
   Run-command:
     runs-on: ubuntu-latest
     container:
-      image: stalchmst/zrb:0.0.122
+      image: stalchmst/zrb:0.1.0-alpha
     steps:
       - name: Check out repository code
         uses: actions/checkout@v3

docs/concepts/README.md

@@ -2,9 +2,9 @@
 
 # Concepts
 
-- [Tasks](tasks/README.md)
+- [Tasks](task/README.md)
 - [Task Group](task-group.md)
-- [Task Input](task-input.md)
+- [Task Inputs](task-input/README.md)
 - [Task Env](task-env.md)
 - [Task EnvFile](task-env-file.md)
 - [Template](template.md)

docs/concepts/task-group.md

@@ -49,7 +49,7 @@ print(group.get_tasks())
 ```
 
 ```
-[<Task name=first-task>, <Task name=second-task>]
+[<Task "group first-task">, <Task "group second-task">]
 ```
 
 
@@ -98,7 +98,7 @@ print(group.get_children())
 ```
 
 ```
-[<Group name=sub-group-1>, <Group name=sub-group-2>]
+[<Group "group sub-group-1">, <Group "group sub-group-2">]
 ```
 
 
@@ -125,6 +125,51 @@ my-system
 ```
 
 
+### `Group.get_description`
+
+Retrieves group description.
+
+__Returns:__
+
+`str`: Description of the group.
+
+__Examples:__
+
+```python
+from zrb import Group
+group = Group(name='group', description='description of the group')
+print(group.get_description())
+```
+
+```
+description of the group
+```
+
+
+### `Group.get_parent`
+
+Retrieves parent of the Group.
+
+__Returns:__
+
+`Optional[Group]`: Parent of the group.
+
+__Examples:__
+
+```python
+from zrb import Group
+system_group = Group(name='my system')
+system_log_group = Group(name='log', parent=system_group)
+print(system_group.get_parent())
+print(system_log_group.get_parent())
+```
+
+```
+None
+<Group "my-system">
+```
+
+
 ### `Group.get_tasks`
 
 Get direct Tasks under this Task Group.
@@ -144,7 +189,7 @@ print(group.get_tasks())
 ```
 
 ```
-[<Task name=first-task>, <Task name=second-task>]
+[<Task "group first-task">, <Task "group second-task">]
 ```
 
 

docs/concepts/task-input.md → docs/concepts/task-input/README.md

@@ -1,13 +1,35 @@
-🔖 [Table of Contents](../README.md)
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md)
 
 # Task Input
 
+Sometimes, you need some user inputs to run your Tasks.
+
+Zrb allows you to set `inputs` for your Task; either by:
+
+- Using `inputs` parameter.
+- Using `add_input` method.
+- Using `insert_input` method.
+
+All Task Input should comply with `AnyInput` interface.
+
+Currently, there are some built-in inputs you can use:
+
+- [Input](./input.md)
+- [BoolInput](./bool-input.md)
+- [ChoiceInput](./choice-input.md)
+- [FloatInput](./float-input.md)
+- [IntInput](./int-input.md)
+- [PasswordInput](./password-input.md)
+- [StrInput](./str-input.md)
+
+Here, you will see the technical specification of `AnyInput`
+
+# Technical Specification
+
 <!--start-doc-->
 ## `Input`
 
-A concrete implementation of the AnyInput abstract base class, representing a specific type of task input.
-This class allows for the creation of interactive and configurable inputs for tasks, with various attributes
-to customize its behavior and appearance.
+Alias for BaseInput
 
 __Attributes:__
 
@@ -95,4 +117,4 @@ __Returns:__
 
 <!--end-doc-->
 
-🔖 [Table of Contents](../README.md)
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md)

docs/concepts/task-input/bool-input.md

@@ -0,0 +1,99 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Task Input](README.md)
+
+# BoolInput
+
+# Technical Specification
+
+<!--start-doc-->
+## `BoolInput`
+
+A specialized input class for handling boolean values in a task input context.
+
+This class extends `BaseInput` and provides specific functionality for boolean type inputs,
+including support for default values, prompts, flags, and various customization options.
+
+__Arguments:__
+
+- `name` (`str`): The name of the input.
+- `shortcut` (`Optional[str]`): A shortcut string for the input.
+- `default` (`Optional[Any]`): The default value for the input. Should be a boolean if set.
+- `description` (`Optional[str]`): A brief description of the input.
+- `show_default` (`Union[bool, str, None]`): Option to display the default value. Can be a boolean or string representation.
+- `prompt` (`Union[bool, str]`): A boolean or string to prompt the user for input. If `True`, uses the default prompt.
+- `confirmation_prompt` (`Union[bool, str]`): If set to `True`, the user is asked to confirm the input.
+- `prompt_required` (`bool`): If `True`, the prompt for input is mandatory.
+- `hide_input` (`bool`): If `True`, the input is hidden (useful for sensitive information).
+- `is_flag` (`Optional[bool]`): Indicates if the input is a flag. If `True`, the input accepts boolean flag values.
+- `flag_value` (`Optional[Any]`): The value associated with the flag if `is_flag` is `True`.
+- `multiple` (`bool`): If `True`, allows multiple values for the input.
+- `count` (`bool`): If `True`, counts the occurrences of the input.
+- `allow_from_autoenv` (`bool`): If `True`, allows the input to be automatically populated from the environment.
+- `hidden` (`bool`): If `True`, the input is not shown in help messages or documentation.
+- `show_choices` (`bool`): If `True`, displays the choices available for the input.
+- `show_envvar` (`bool`): Indicates whether to display the environment variable associated with this input.
+- `nargs` (`int`): The number of arguments that the input can accept.
+- `should_render` (`bool`): If `True`, the input is rendered in the UI or command-line interface.
+
+__Examples:__
+
+```python
+bool_input = BoolInput(name='confirm', prompt='Do you agree?', default=False)
+bool_input.get_default()
+```
+
+```
+False
+```
+
+
+### `BoolInput.get_default`
+
+Obtains the default value of the input.
+
+__Returns:__
+
+`Any`: The default value of the input. The type can be any, depending on the input specification.
+
+### `BoolInput.get_name`
+
+Retrieves the name of the input.
+
+__Returns:__
+
+`str`: The name of the input.
+
+### `BoolInput.get_options`
+
+Provides a mapping (dictionary) representing the input.
+
+__Returns:__
+
+`Mapping[str, Any]`: A dictionary where keys are option names and values are the corresponding details.
+
+### `BoolInput.get_param_decl`
+
+Fetches a list of parameter option associated with the input (i.e., `-f` or `--file`).
+
+__Returns:__
+
+`List[str]`: A list containing strings of parameter options.
+
+### `BoolInput.is_hidden`
+
+Checks whether the input value is meant to be hidden from view or output.
+
+__Returns:__
+
+`bool`: True if the input is hidden, False otherwise.
+
+### `BoolInput.should_render`
+
+Determines whether or not the input should be rendered.
+
+__Returns:__
+
+`bool`: True if the input should be rendered, False otherwise.
+
+<!--end-doc-->
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Task Input](README.md)

docs/concepts/task-input/choice-input.md

@@ -0,0 +1,101 @@
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Task Input](README.md)
+
+# ChoiceInput
+
+# Technical Specification
+
+<!--start-doc-->
+## `ChoiceInput`
+
+A specialized input class for handling choice-based inputs in a task input context.
+
+This class extends `BaseInput` and provides functionality for inputs where the user
+must select from a predefined set of choices. It includes support for default values,
+prompts, flags, and various customization options.
+
+__Arguments:__
+
+- `name` (`str`): The name of the input.
+- `shortcut` (`Optional[str]`): An optional shortcut string for the input.
+- `choices` (`Iterable[Any]`): An iterable of choices from which the user can select.
+- `default` (`Optional[Any]`): The default value for the input. Should be one of the choices if set.
+- `description` (`Optional[str]`): A brief description of the input.
+- `show_default` (`Union[bool, str, None]`): Option to display the default value. Can be a boolean or string representation.
+- `prompt` (`Union[bool, str]`): A boolean or string to prompt the user for input. If `True`, uses the default prompt.
+- `confirmation_prompt` (`Union[bool, str]`): If set to `True`, the user is asked to confirm the input.
+- `prompt_required` (`bool`): If `True`, the prompt for input is mandatory.
+- `hide_input` (`bool`): If `True`, the input is hidden (useful for sensitive information).
+- `is_flag` (`Optional[bool]`): Indicates if the input is a flag. If `True`, the input accepts boolean flag values.
+- `flag_value` (`Optional[Any]`): The value associated with the flag if `is_flag` is `True`.
+- `multiple` (`bool`): If `True`, allows multiple values for the input.
+- `count` (`bool`): If `True`, counts the occurrences of the input.
+- `allow_from_autoenv` (`bool`): If `True`, allows the input to be automatically populated from the environment.
+- `hidden` (`bool`): If `True`, the input is not shown in help messages or documentation.
+- `show_choices` (`bool`): If `True`, displays the available choices to the user.
+- `show_envvar` (`bool`): Indicates whether to display the environment variable associated with this input.
+- `nargs` (`int`): The number of arguments that the input can accept.
+- `should_render` (`bool`): If `True`, the input is rendered in the UI or command-line interface.
+
+__Examples:__
+
+```python
+choice_input = ChoiceInput(name='color', choices=['red', 'green', 'blue'], default='red')
+choice_input.get_default()
+```
+
+```
+'red'
+```
+
+
+### `ChoiceInput.get_default`
+
+Obtains the default value of the input.
+
+__Returns:__
+
+`Any`: The default value of the input. The type can be any, depending on the input specification.
+
+### `ChoiceInput.get_name`
+
+Retrieves the name of the input.
+
+__Returns:__
+
+`str`: The name of the input.
+
+### `ChoiceInput.get_options`
+
+Provides a mapping (dictionary) representing the input.
+
+__Returns:__
+
+`Mapping[str, Any]`: A dictionary where keys are option names and values are the corresponding details.
+
+### `ChoiceInput.get_param_decl`
+
+Fetches a list of parameter option associated with the input (i.e., `-f` or `--file`).
+
+__Returns:__
+
+`List[str]`: A list containing strings of parameter options.
+
+### `ChoiceInput.is_hidden`
+
+Checks whether the input value is meant to be hidden from view or output.
+
+__Returns:__
+
+`bool`: True if the input is hidden, False otherwise.
+
+### `ChoiceInput.should_render`
+
+Determines whether or not the input should be rendered.
+
+__Returns:__
+
+`bool`: True if the input should be rendered, False otherwise.
+
+<!--end-doc-->
+
+🔖 [Table of Contents](../../README.md) / [Concepts](../README.md) / [Task Input](README.md)