utils.py docu update

gooddata-pandas/gooddata_pandas/utils.py

@@ -24,15 +24,39 @@
 
 
 def _unique_local_id() -> str:
+    """
+    Generate unique local ID of a DataItem without dashes.
+
+    Returns:
+        str: Unique local ID.
+    """
     return uuid.uuid4().hex.replace("-", "")
 
 
 def _val_to_hash(val: str) -> str:
+    """
+    Convert a value to its MD5 hexdigest.
+
+    Args:
+        val (str): Value to convert to a hash.
+
+    Returns:
+        str: Hexdigest of the value.
+    """
     hash_object = hashlib.md5(val.encode())
     return hash_object.hexdigest()
 
 
 def _str_to_obj_id(val: DataItemDef) -> Optional[ObjId]:
+    """
+    Convert a value to ObjId if it is in one of ["label", "metric", "fact"] types.
+
+    Args:
+        val (DataItemDef): Value to convert to ObjId.
+
+    Returns:
+        Optional[ObjId]: ObjId if the value can be converted, otherwise None.
+    """
     if isinstance(val, str):
         split = val.split("/")
         _type = split[0]
@@ -43,6 +67,15 @@ def _str_to_obj_id(val: DataItemDef) -> Optional[ObjId]:
 
 
 def _try_obj_id(val: DataItemDef) -> DataItemDef:
+    """
+    Convert a value to its ObjId if it can be converted.
+
+    Args:
+        val (DataItemDef): Value to convert to ObjId.
+
+    Returns:
+        DataItemDef: The ObjId for the given value, otherwise the value itself.
+    """
     _obj_id = _str_to_obj_id(val)
     if _obj_id:
         return _obj_id
@@ -51,6 +84,16 @@ def _try_obj_id(val: DataItemDef) -> DataItemDef:
 
 
 def _to_item(val: DataItemDef, local_id: Optional[str] = None) -> Union[Attribute, Metric]:
+    """
+    Convert a DataItemDef value to either an Attribute or a Metric based on its type.
+
+    Args:
+        val (DataItemDef): Value to convert.
+        local_id (Optional[str], optional): Local ID of the input value. Defaults to None.
+
+    Returns:
+        Union[Attribute, Metric]: The resulting Attribute or Metric.
+    """
     _val = _try_obj_id(val)
     if isinstance(_val, (Attribute, Metric)):
         return _val
@@ -67,6 +110,16 @@ def _to_item(val: DataItemDef, local_id: Optional[str] = None) -> Union[Attribut
 
 
 def _to_attribute(val: LabelItemDef, local_id: Optional[str] = None) -> Attribute:
+    """
+    Convert a LabelItemDef value to an Attribute.
+
+    Args:
+        val (LabelItemDef): Value to convert.
+        local_id (Optional[str], optional): Local ID of the input value. Defaults to None.
+
+    Returns:
+        Attribute: The resulting Attribute.
+    """
     _val = _to_item(val, local_id)
     if isinstance(_val, Attribute):
         return _val
@@ -75,11 +128,30 @@ def _to_attribute(val: LabelItemDef, local_id: Optional[str] = None) -> Attribut
 
 
 def _typed_attribute_value(ct_attr: CatalogAttribute, value: Any) -> Any:
+    """
+    Convert an attribute value to its external type based on the CatalogAttribute.
+
+    Args:
+        ct_attr (CatalogAttribute): The catalog attribute.
+        value (Any): The value to convert.
+
+    Returns:
+        Any: The converted value.
+    """
     converter = AttributeConverterStore.find_converter(ct_attr.dataset.dataset_type, ct_attr.granularity)
     return converter.to_external_type(value)
 
 
 def make_pandas_index(index: dict) -> Optional[Union[Index, MultiIndex]]:
+    """
+    Create a pandas index or multi-index based on the input index dictionary.
+
+    Args:
+        index (dict): The input index dictionary.
+
+    Returns:
+        Optional[Union[Index, MultiIndex]]: The resulting pandas index or multi-index, or None if empty index.
+    """
     if len(index) == 1:
         index_key = list(index.keys())[0]
         _idx = pandas.Index(index[index_key], name=index_key)
@@ -92,9 +164,21 @@ def make_pandas_index(index: dict) -> Optional[Union[Index, MultiIndex]]:
 
 class DefaultInsightColumnNaming:
     def __init__(self) -> None:
+        """
+        Initialize a DefaultInsightColumnNaming instance with an empty dictionary for unique names.
+        """
         self._uniques: dict[str, int] = dict()
 
     def _get_unique_candidate(self, candidate: str) -> str:
+        """
+        Find a unique candidate for a given column name.
+
+        Args:
+            candidate (str): Column name candidate.
+
+        Returns:
+            str: Unique candidate for the column name.
+        """
         # ensure column name uniqueness - in a dumb way by appending some number
         if candidate in self._uniques:
             i = 1
@@ -109,14 +193,41 @@ def _get_unique_candidate(self, candidate: str) -> str:
         return candidate
 
     def _ensure_unique(self, candidate: str) -> str:
+        """
+        Ensure a given candidate is unique in the current namespace.
+
+        Args:
+            candidate (str): Column name candidate.
+
+        Returns:
+            str: Unique column name.
+        """
         unique_candidate = self._get_unique_candidate(candidate)
         self._uniques[unique_candidate] = 1
         return unique_candidate
 
     def col_name_for_attribute(self, attr: InsightAttribute) -> str:
+        """
+        Generate a unique column name for the given attribute.
+
+        Args:
+            attr (InsightAttribute): The attribute.
+
+        Returns:
+            str: The unique column name.
+        """
         return self._ensure_unique(attr.label_id)
 
     def col_name_for_metric(self, measure: InsightMetric) -> str:
+        """
+        Generate a unique column name for the given metric.
+
+        Args:
+          measure (InsightMetric): The metric.
+
+        Returns:
+            str: The unique column name.
+        """
         # if simple measure, use the item identifier (nice, readable)
         # otherwise try alias
         # otherwise try title