src.API.yaml_wrapper

  1from typing import  List, Union
  2from ..modules.modification_handlers.modification_handler import ModificationHandler
  3from ..modules.yaml_structures.yaml_dictionary import YamlDictionary
  4from ..modules.yaml_structures.yaml_list import YamlList
  5
  6
  7class YamlWrapper:
  8    """**YamlWrapper** creates an abstraction over the `.yaml` file.    
  9    
 10    **Main data types:**
 11    - `YamlDictionary`: Dictionary with the format accepted by the Yaml Wrap library.
 12    - `YamlList`: List with the format accepted by the Yaml Wrap library.
 13    
 14    **IMPORTANT NOTES:**
 15    The main purpose of this class is to create an abstraction layer over the PyYaml library. It's important to remember that the format of file contenten used in PyYaml library is
 16    not compatible.
 17    *Example:*
 18    For example if in PyYaml library a dictionary is rappresented ad `{"key", "value"}`, in YamlWrapper is rappresented by YamlDictionary("key", "value").
 19    
 20    """
 21    def __init__(self, file_path: str, safe_initialization: bool = True) -> None:
 22        """Constructor of the class.
 23
 24        ***Args:***
 25        - `file_path (str)`: File path in the format `path/format/accepted_by_the_library.yaml`.
 26        - `safe_initialization (bool, optional)`: If `true` and the file at the specified path not exist, this will be created, otherwise it will be
 27        raised the exception `FileNotDFoundError`. Defaults to True.
 28        """
 29        self._file_name: str = file_path
 30        self._safe_initialization: bool = safe_initialization
 31        self._modification_handler: ModificationHandler = ModificationHandler(file_path, safe_initialization)
 32        
 33        self._modification_handler.load()
 34    
 35    def get_file_name(self) -> str:
 36        """Returns the name of the file.
 37
 38        ***Returns:*** File name.
 39        """
 40        return self._file_name
 41    
 42    def get_file_content(self) -> list:
 43        """Returns the content of the file in a list that contains it in the format accepted by the Yaml Wrap library.
 44
 45        ***Returns:***
 46            `list`: Content of the file.
 47        """
 48        return self._modification_handler.get()
 49    
 50    def update(self, filter: str, value: Union[int, str, List[YamlDictionary], YamlList]) -> list:
 51        """Updates the value of the file, using a filter to determine the position of the value. After the update the file is synchronised automatically.
 52
 53        ***Args:***
 54        - `filter (str)`: Filter used to determine the position of the value.
 55        - `value (Union[int, str, List[YamlDictionary], YamlList])`: Value to be updated.
 56
 57        ***Returns:***
 58            `list`: Content of the file updates.
 59        
 60        *Filter format:*
 61        - File content: `[YamlDictionary("key",[YamlDictionary("sub_key", "value")])` -> filter: `"key.sub_key"`
 62        - File content: `[YamlDictionary("key",YamlList([1, 2, 3]))` -> `filter: "key.[]"`
 63        - File content: `[YamlDictionary("key",YamlList([[YamlDictionary("sub_key_1", "value_1"), YamlDictionary("sub_key_2", "value_2")]])]` -> filter: `"key.[].sub_key_1"`
 64        
 65        *Note:*  <br /> 
 66        The filter it must be in the following format:  <br /> 
 67        Supposte che file content is a dictionary with another dictionary as value, so the situation is
 68        
 69        ```python
 70        [ YamlDictionary("key", 
 71                            [YamlDictionary("sub_key", "value")
 72                            ]
 73                        )
 74        ]
 75        ``` 
 76        in order to change the value the filter must be in the following format: `"key.sub_key"`.
 77        
 78        """
 79        return self._modification_handler.update(filter, value)
 80    
 81    def add(self, key: str, data_to_add: Union[int, str, List[YamlDictionary], YamlList]) -> list:
 82        """Adds an item under the specified `key`.
 83
 84        ***Args:***
 85        - `key (str)`: Key to add.
 86        - `data_to_add (Union[int, str, List[YamlDictionary], YamlList])`: Data to add.
 87        
 88        ***Raises:***
 89        -  `KeyAlreadyUsedException`: If the key already exists.
 90        
 91        ***Returns:***
 92            `list`: Content of the file updated, after the add.
 93       
 94        
 95        ***Note***: This method doesn't check the `data_to_add parameter`, it this is not in right format, the file `.yaml` can be corrupted.
 96        """
 97        return self._modification_handler.add(key, data_to_add)
 98    
 99    def remove(self, filter: str) -> list:
100        """Remove a value from the file, using a filter to determine the position. After the remove the file is synchronised automatically.
101
102        ***Args:***
103        - `filter (str)`: Filter used to determine the position of the value.
104
105        ***Returns:***
106            `list`: Content of the file updated, after the remove.
107        
108        ***Filter format:***
109        - File content: `[YamlDictionary("key",YamlDictionary("sub_key", "value"))` -> filter: `"key.sub_key"`
110        For the remotion the filter must not contain `[]`. This because the list is completely removed, using the value of its key.
111    
112        *Example:* 
113        - List remotion:
114            - File content: `[YamlDictionary("key",YamlList([1, 2, 3]))`
115                - Filter: `"key"`
116                - After remove: `[]`
117            - File content: `[YamlDictionary("key",[YamlDictionary("sub_key_1", "value_1"), YamlDictionary("sub_key_2", "value_2") ]]`
118                - Filter: `"key.sub_key_1"`
119                - After remove: `[YamlDictionary("key",[YamlDictionary("sub_key_2", "value_2")])]`
120        """
121        return self._modification_handler.remove(filter)   
122    
123    def clean_file(self) -> bool:
124        """Delete all data in the file. ATTENTION: this operation is not reversible.
125
126        ***Returns:***
127            `bool`: True if the file is cleaned, False otherwise.
128        """
129        pass