datachain 0.18.4__py3-none-any.whl → 0.18.5__py3-none-any.whl

datachain/func/conditional.py

@@ -9,38 +9,39 @@ from datachain.lib.utils import DataChainParamsError
 from datachain.query.schema import Column
 from datachain.sql.functions import conditional
 
-from .func import ColT, Func
+from .func import Func
 
 CaseT = Union[int, float, complex, bool, str, Func, ColumnElement]
 
 
-def greatest(*args: Union[ColT, float]) -> Func:
+def greatest(*args: Union[str, Column, Func, float]) -> Func:
     """
     Returns the greatest (largest) value from the given input values.
 
     Args:
-        args (ColT | str | int | float | Sequence): The values to compare.
+        args (str | Column | Func | int | float): The values to compare.
             If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column in the dataset.
             If a Func is provided, it is assumed to be a function returning a value.
-            If an int, float, or Sequence is provided, it is assumed to be a literal.
+            If an int or float is provided, it is assumed to be a literal.
 
     Returns:
-        Func: A Func object that represents the greatest function.
+        Func: A `Func` object that represents the greatest function.
 
     Example:
         ```py
         dc.mutate(
-            greatest=func.greatest("signal.value", 0),
+            greatest=func.greatest(dc.C("signal.value"), "signal.value2", 0.5, 1.0),
         )
         ```
 
-    Note:
-        - Result column will always be of the same type as the input columns.
+    Notes:
+        - The result column will always be of the same type as the input columns.
     """
     cols, func_args = [], []
 
     for arg in args:
-        if isinstance(arg, (str, Func)):
+        if isinstance(arg, (str, Column, Func)):
             cols.append(arg)
         else:
             func_args.append(arg)
@@ -54,33 +55,34 @@ def greatest(*args: Union[ColT, float]) -> Func:
     )
 
 
-def least(*args: Union[ColT, float]) -> Func:
+def least(*args: Union[str, Column, Func, float]) -> Func:
     """
     Returns the least (smallest) value from the given input values.
 
     Args:
-        args (ColT | str | int | float | Sequence): The values to compare.
+        args (str | Column | Func | int | float): The values to compare.
             If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column in the dataset.
             If a Func is provided, it is assumed to be a function returning a value.
-            If an int, float, or Sequence is provided, it is assumed to be a literal.
+            If an int or float is provided, it is assumed to be a literal.
 
     Returns:
-        Func: A Func object that represents the least function.
+        Func: A `Func` object that represents the least function.
 
     Example:
         ```py
         dc.mutate(
-            least=func.least("signal.value", 0),
+            least=func.least(dc.C("signal.value"), "signal.value2", -1.0, 0),
         )
         ```
 
-    Note:
-        - Result column will always be of the same type as the input columns.
+    Notes:
+        - The result column will always be of the same type as the input columns.
     """
     cols, func_args = [], []
 
     for arg in args:
-        if isinstance(arg, (str, Func)):
+        if isinstance(arg, (str, Column, Func)):
             cols.append(arg)
         else:
             func_args.append(arg)
@@ -94,29 +96,31 @@ def case(
     *args: tuple[Union[ColumnElement, Func, bool], CaseT], else_: Optional[CaseT] = None
 ) -> Func:
     """
-    Returns the case function that produces case expression which has a list of
-    conditions and corresponding results. Results can be python primitives like string,
-    numbers or booleans but can also be other nested functions (including case function)
-    or columns.
-    Result type is inferred from condition results.
+    Returns a case expression that evaluates a list of conditions and returns
+    corresponding results. Results can be Python primitives (string, numbers, booleans),
+    nested functions (including case function), or columns.
 
     Args:
-        args tuple((ColumnElement | Func | bool),(str | int | float | complex | bool, Func, ColumnElement)):
-            Tuple of condition and values pair.
-        else_ (str | int | float | complex | bool, Func): optional else value in case
-            expression. If omitted, and no case conditions are satisfied, the result
-            will be None (NULL in DB).
+        args (tuple[ColumnElement | Func | bool, CaseT]): Tuples of (condition, value)
+            pairs. Each condition is evaluated in order, and the corresponding value
+            is returned for the first condition that evaluates to True.
+        else_ (CaseT, optional): Value to return if no conditions are satisfied.
+            If omitted and no conditions are satisfied, the result will be None
+            (NULL in DB).
 
     Returns:
-        Func: A Func object that represents the case function.
+        Func: A `Func` object that represents the case function.
 
     Example:
         ```py
         dc.mutate(
-            res=func.case((C("num") > 0, "P"), (C("num") < 0, "N"), else_="Z"),
+            res=func.case((dc.C("num") > 0, "P"), (dc.C("num") < 0, "N"), else_="Z"),
         )
         ```
-    """  # noqa: E501
+
+    Notes:
+        - The result type is inferred from the values provided in the case statements.
+    """
     supported_types = [int, float, complex, str, bool]
 
     def _get_type(val):
@@ -162,20 +166,18 @@ def ifelse(
     condition: Union[ColumnElement, Func], if_val: CaseT, else_val: CaseT
 ) -> Func:
     """
-    Returns the ifelse function that produces if expression which has a condition
-    and values for true and false outcome. Results can be one of python primitives
-    like string, numbers or booleans, but can also be nested functions or columns.
-    Result type is inferred from the values.
+    Returns an if-else expression that evaluates a condition and returns one
+    of two values based on the result. Values can be Python primitives
+    (string, numbers, booleans), nested functions, or columns.
 
     Args:
-        condition (ColumnElement, Func):  Condition which is evaluated.
-        if_val (str | int | float | complex | bool, Func, ColumnElement): Value for true
-            condition outcome.
-        else_val (str | int | float | complex | bool, Func, ColumnElement): Value for
-            false condition outcome.
+        condition (ColumnElement | Func): Condition to evaluate.
+        if_val (ColumnElement | Func | literal): Value to return if condition is True.
+        else_val (ColumnElement | Func | literal): Value to return if condition
+            is False.
 
     Returns:
-        Func: A Func object that represents the ifelse function.
+        Func: A `Func` object that represents the ifelse function.
 
     Example:
         ```py
@@ -183,31 +185,37 @@ def ifelse(
             res=func.ifelse(isnone("col"), "EMPTY", "NOT_EMPTY")
         )
         ```
+
+    Notes:
+        - The result type is inferred from the values provided in the ifelse statement.
     """
     return case((condition, if_val), else_=else_val)
 
 
-def isnone(col: Union[str, Column]) -> Func:
+def isnone(col: Union[str, ColumnElement]) -> Func:
     """
-    Returns True if column value is None, otherwise False.
+    Returns a function that checks if the column value is `None` (NULL in DB).
 
     Args:
         col (str | Column): Column to check if it's None or not.
             If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column in the dataset.
 
     Returns:
-        Func: A Func object that represents the conditional to check if column is None.
+        Func: A `Func` object that represents the isnone function.
+            Returns True if column value is None, otherwise False.
 
     Example:
         ```py
         dc.mutate(test=ifelse(isnone("col"), "EMPTY", "NOT_EMPTY"))
         ```
-    """
-    from datachain import C
 
+    Notes:
+        - The result column will always be of type bool.
+    """
     if isinstance(col, str):
-        # if string, it is assumed to be the name of the column
-        col = C(col)
+        # if string is provided, it is assumed to be the name of the column
+        col = Column(col)
 
     return case((col.is_(None) if col is not None else True, True), else_=False)
 
@@ -219,21 +227,27 @@ def or_(*args: Union[ColumnElement, Func]) -> Func:
 
     Args:
         args (ColumnElement | Func): The expressions for OR statement.
+            If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column in the dataset.
+            If a Func is provided, it is assumed to be a function returning a value.
 
     Returns:
-        Func: A Func object that represents the or function.
+        Func: A `Func` object that represents the OR function.
 
     Example:
         ```py
         dc.mutate(
-            test=ifelse(or_(isnone("name"), C("name") == ''), "Empty", "Not Empty")
+            test=ifelse(or_(isnone("name"), dc.C("name") == ''), "Empty", "Not Empty")
         )
         ```
+
+    Notes:
+        - The result column will always be of type bool.
     """
     cols, func_args = [], []
 
     for arg in args:
-        if isinstance(arg, (str, Func)):
+        if isinstance(arg, (str, Column, Func)):
             cols.append(arg)
         else:
             func_args.append(arg)
@@ -248,9 +262,12 @@ def and_(*args: Union[ColumnElement, Func]) -> Func:
 
     Args:
         args (ColumnElement | Func): The expressions for AND statement.
+            If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column in the dataset.
+            If a Func is provided, it is assumed to be a function returning a value.
 
     Returns:
-        Func: A Func object that represents the and function.
+        Func: A `Func` object that represents the AND function.
 
     Example:
         ```py
@@ -258,6 +275,9 @@ def and_(*args: Union[ColumnElement, Func]) -> Func:
             test=ifelse(and_(isnone("name"), isnone("surname")), "Empty", "Not Empty")
         )
         ```
+
+    Notes:
+        - The result column will always be of type bool.
     """
     cols, func_args = [], []
 

datachain/func/func.py

@@ -22,7 +22,7 @@ if TYPE_CHECKING:
     from .window import Window
 
 
-ColT = Union[str, ColumnElement, "Func", tuple]
+ColT = Union[str, Column, ColumnElement, "Func", tuple]
 
 
 class Func(Function):

datachain/func/numeric.py

@@ -1,31 +1,36 @@
 from typing import Union
 
+from datachain.query.schema import Column
 from datachain.sql.functions import numeric
 
-from .func import ColT, Func
+from .func import Func
 
 
-def bit_and(*args: Union[ColT, int]) -> Func:
+def bit_and(*args: Union[str, Column, Func, int]) -> Func:
     """
-    Computes the bitwise AND operation between two values.
+    Returns a function that computes the bitwise AND operation between two values.
 
     Args:
-        args (str | int): Two values to compute the bitwise AND operation between.
-            If a string is provided, it is assumed to be the name of the column vector.
+        args (str | Column | Func | int): Two values to compute
+            the bitwise AND operation between.
+            If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column.
+            If a Func is provided, it is assumed to be a function returning an int.
             If an integer is provided, it is assumed to be a constant value.
 
     Returns:
-        Func: A Func object that represents the bitwise AND function.
+        Func: A `Func` object that represents the bitwise AND function.
 
     Example:
         ```py
         dc.mutate(
-            xor1=func.bit_and("signal.values", 0x0F),
+            and1=func.bit_and("signal.value", 0x0F),
+            and2=func.bit_and(dc.C("signal.value1"), "signal.value2"),
         )
         ```
 
     Notes:
-        - Result column will always be of type int.
+        - The result column will always be of type int.
     """
     cols, func_args = [], []
     for arg in args:
@@ -46,27 +51,31 @@ def bit_and(*args: Union[ColT, int]) -> Func:
     )
 
 
-def bit_or(*args: Union[ColT, int]) -> Func:
+def bit_or(*args: Union[str, Column, Func, int]) -> Func:
     """
-    Computes the bitwise AND operation between two values.
+    Returns a function that computes the bitwise OR operation between two values.
 
     Args:
-        args (str | int): Two values to compute the bitwise OR operation between.
-            If a string is provided, it is assumed to be the name of the column vector.
+        args (str | Column | Func | int): Two values to compute
+            the bitwise OR operation between.
+            If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column.
+            If a Func is provided, it is assumed to be a function returning an int.
             If an integer is provided, it is assumed to be a constant value.
 
     Returns:
-        Func: A Func object that represents the bitwise OR function.
+        Func: A `Func` object that represents the bitwise OR function.
 
     Example:
         ```py
         dc.mutate(
-            xor1=func.bit_or("signal.values", 0x0F),
+            or1=func.bit_or("signal.value", 0x0F),
+            or2=func.bit_or(dc.C("signal.value1"), "signal.value2"),
         )
         ```
 
     Notes:
-        - Result column will always be of type int.
+        - The result column will always be of type int.
     """
     cols, func_args = [], []
     for arg in args:
@@ -87,27 +96,31 @@ def bit_or(*args: Union[ColT, int]) -> Func:
     )
 
 
-def bit_xor(*args: Union[ColT, int]) -> Func:
+def bit_xor(*args: Union[str, Column, Func, int]) -> Func:
     """
-    Computes the bitwise XOR operation between two values.
+    Returns a function that computes the bitwise XOR operation between two values.
 
     Args:
-        args (str | int): Two values to compute the bitwise XOR operation between.
-            If a string is provided, it is assumed to be the name of the column vector.
+        args (str | Column | Func | int): Two values to compute
+            the bitwise XOR operation between.
+            If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column.
+            If a Func is provided, it is assumed to be a function returning an int.
             If an integer is provided, it is assumed to be a constant value.
 
     Returns:
-        Func: A Func object that represents the bitwise XOR function.
+        Func: A `Func` object that represents the bitwise XOR function.
 
     Example:
         ```py
         dc.mutate(
-            xor1=func.bit_xor("signal.values", 0x0F),
+            xor1=func.bit_xor("signal.value", 0x0F),
+            xor2=func.bit_xor(dc.C("signal.value1"), "signal.value2"),
         )
         ```
 
     Notes:
-        - Result column will always be of type int.
+        - The result column will always be of type int.
     """
     cols, func_args = [], []
     for arg in args:
@@ -128,28 +141,30 @@ def bit_xor(*args: Union[ColT, int]) -> Func:
     )
 
 
-def int_hash_64(col: Union[ColT, int]) -> Func:
+def int_hash_64(col: Union[str, Column, Func, int]) -> Func:
     """
-    Returns the 64-bit hash of an integer.
+    Returns a function that computes the 64-bit hash of an integer.
 
     Args:
-        col (str | int): String to compute the hash of.
+        col (str | Column | Func | int): Integer to compute the hash of.
             If a string is provided, it is assumed to be the name of the column.
-            If a int is provided, it is assumed to be an int literal.
+            If a Column is provided, it is assumed to be a column.
             If a Func is provided, it is assumed to be a function returning an int.
+            If an int is provided, it is assumed to be an int literal.
 
     Returns:
-        Func: A Func object that represents the 64-bit hash function.
+        Func: A `Func` object that represents the 64-bit hash function.
 
     Example:
         ```py
         dc.mutate(
             val_hash=func.int_hash_64("val"),
+            val_hash2=func.int_hash_64(dc.C("val2")),
         )
         ```
 
-    Note:
-        - Result column will always be of type int.
+    Notes:
+        - The result column will always be of type int.
     """
     cols, args = [], []
     if isinstance(col, int):
@@ -162,9 +177,9 @@ def int_hash_64(col: Union[ColT, int]) -> Func:
     )
 
 
-def bit_hamming_distance(*args: Union[ColT, int]) -> Func:
+def bit_hamming_distance(*args: Union[str, Column, Func, int]) -> Func:
     """
-    Computes the Hamming distance between the bit representations of two integer values.
+    Returns a function that computes the Hamming distance between two integers.
 
     The Hamming distance is the number of positions at which the corresponding bits
     are different. This function returns the dissimilarity between the integers,
@@ -172,22 +187,26 @@ def bit_hamming_distance(*args: Union[ColT, int]) -> Func:
     in the integer indicate higher dissimilarity.
 
     Args:
-        args (str | int): Two integers to compute the Hamming distance between.
-            If a str is provided, it is assumed to be the name of the column.
+        args (str | Column | Func | int): Two integers to compute
+            the Hamming distance between.
+            If a string is provided, it is assumed to be the name of the column.
+            If a Column is provided, it is assumed to be a column.
+            If a Func is provided, it is assumed to be a function returning an int.
             If an int is provided, it is assumed to be an integer literal.
 
     Returns:
-        Func: A Func object that represents the Hamming distance function.
+        Func: A `Func` object that represents the Hamming distance function.
 
     Example:
         ```py
         dc.mutate(
-            ham_dist=func.bit_hamming_distance("embed1", 123456),
+            hd1=func.bit_hamming_distance("signal.value1", "signal.value2"),
+            hd2=func.bit_hamming_distance(dc.C("signal.value1"), 0x0F),
         )
         ```
 
     Notes:
-        - Result column will always be of type int.
+        - The result column will always be of type int.
     """
     cols, func_args = [], []
     for arg in args:

datachain/func/path.py

@@ -8,23 +8,26 @@ def parent(col: ColT) -> Func:
     Returns the directory component of a posix-style path.
 
     Args:
-        col (str | literal | Func): String to compute the path parent of.
+        col (str | Column | Func | literal): String to compute the path parent of.
             If a string is provided, it is assumed to be the name of the column.
-            If a literal is provided, it is assumed to be a string literal.
+            If a Column is provided, it is assumed to be a column object.
             If a Func is provided, it is assumed to be a function returning a string.
+            If a literal is provided, it is assumed to be a string literal.
 
     Returns:
-        Func: A Func object that represents the path parent function.
+        Func: A `Func` object that represents the path parent function.
 
     Example:
         ```py
         dc.mutate(
-            parent=func.path.parent("file.path"),
+            parent1=func.path.parent("file.path"),
+            parent2=func.path.parent(dc.C("file.path")),
+            parent3=func.path.parent(dc.func.literal("/path/to/file.txt")),
         )
         ```
 
     Note:
-        - Result column will always be of type string.
+        - The result column will always be of type string.
     """
     return Func("parent", inner=path.parent, cols=[col], result_type=str)
 
@@ -34,23 +37,26 @@ def name(col: ColT) -> Func:
     Returns the final component of a posix-style path.
 
     Args:
-        col (str | literal): String to compute the path name of.
+        col (str | Column | Func | literal): String to compute the path name of.
             If a string is provided, it is assumed to be the name of the column.
-            If a literal is provided, it is assumed to be a string literal.
+            If a Column is provided, it is assumed to be a column object.
             If a Func is provided, it is assumed to be a function returning a string.
+            If a literal is provided, it is assumed to be a string literal.
 
     Returns:
-        Func: A Func object that represents the path name function.
+        Func: A `Func` object that represents the path name function.
 
     Example:
         ```py
         dc.mutate(
-            file_name=func.path.name("file.path"),
+            filename1=func.path.name("file.path"),
+            filename2=func.path.name(dc.C("file.path")),
+            filename3=func.path.name(dc.func.literal("/path/to/file.txt")
         )
         ```
 
     Note:
-        - Result column will always be of type string.
+        - The result column will always be of type string.
     """
 
     return Func("name", inner=path.name, cols=[col], result_type=str)
@@ -61,23 +67,26 @@ def file_stem(col: ColT) -> Func:
     Returns the path without the extension.
 
     Args:
-        col (str | literal): String to compute the file stem of.
+        col (str | Column | Func | literal): String to compute the file stem of.
             If a string is provided, it is assumed to be the name of the column.
-            If a literal is provided, it is assumed to be a string literal.
+            If a Column is provided, it is assumed to be a column object.
             If a Func is provided, it is assumed to be a function returning a string.
+            If a literal is provided, it is assumed to be a string literal.
 
     Returns:
-        Func: A Func object that represents the file stem function.
+        Func: A `Func` object that represents the file stem function.
 
     Example:
         ```py
         dc.mutate(
-            file_stem=func.path.file_stem("file.path"),
+            filestem1=func.path.file_stem("file.path"),
+            filestem2=func.path.file_stem(dc.C("file.path")),
+            filestem3=func.path.file_stem(dc.func.literal("/path/to/file.txt")
         )
         ```
 
     Note:
-        - Result column will always be of type string.
+        - The result column will always be of type string.
     """
 
     return Func("file_stem", inner=path.file_stem, cols=[col], result_type=str)
@@ -88,23 +97,26 @@ def file_ext(col: ColT) -> Func:
     Returns the extension of the given path.
 
     Args:
-        col (str | literal): String to compute the file extension of.
+        col (str | Column | Func | literal): String to compute the file extension of.
             If a string is provided, it is assumed to be the name of the column.
-            If a literal is provided, it is assumed to be a string literal.
+            If a Column is provided, it is assumed to be a column object.
             If a Func is provided, it is assumed to be a function returning a string.
+            If a literal is provided, it is assumed to be a string literal.
 
     Returns:
-        Func: A Func object that represents the file extension function.
+        Func: A `Func` object that represents the file extension function.
 
     Example:
         ```py
         dc.mutate(
-            file_stem=func.path.file_ext("file.path"),
+            filestem1=func.path.file_ext("file.path"),
+            filestem2=func.path.file_ext(dc.C("file.path")),
+            filestem3=func.path.file_ext(dc.func.literal("/path/to/file.txt")
         )
         ```
 
     Note:
-        - Result column will always be of type string.
+        - The result column will always be of type string.
     """
 
     return Func("file_ext", inner=path.file_ext, cols=[col], result_type=str)

datachain/func/random.py

@@ -8,7 +8,7 @@ def rand() -> Func:
     Returns the random integer value.
 
     Returns:
-        Func: A Func object that represents the rand function.
+        Func: A `Func` object that represents the rand function.
 
     Example:
         ```py
@@ -18,6 +18,6 @@ def rand() -> Func:
         ```
 
     Note:
-        - Result column will always be of type integer.
+        - The result column will always be of type integer.
     """
     return Func("rand", inner=random.rand, result_type=int)