relationalai 1.0.0a3__py3-none-any.whl → 1.0.0a5__py3-none-any.whl

relationalai/semantics/std/decimals.py

@@ -1,23 +1,96 @@
+"""
+Decimal manipulation functions.
+
+.. deprecated:: 0.13.0
+   This module is deprecated. Use `std.numbers` instead.
+
+This module provides functions for working with decimal numbers including
+type construction, parsing from strings, and querying decimal properties.
+"""
 from __future__ import annotations
 
 from ..frontend.base import Concept, NumberConcept, Expression, Variable
+from relationalai.util.docutils import include_in_docs
 
 from . import NumberValue, numbers, _deprecated_library
 
+__include_in_docs__ = True
+
 
 #--------------------------------------------------
 # Constructors
 #--------------------------------------------------
 
-def decimal(value: NumberValue, precision=38, scale=14) -> Variable:
+@include_in_docs
+def decimal(value: NumberValue, precision:int=38, scale:int=14) -> Variable:
+    """
+    Create a decimal with specified precision and scale.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.number(value, precision, scale) <std.numbers.number>` instead.
+
+    Parameters
+    ----------
+    value: NumberValue
+        The numeric value.
+    precision: int
+        The precision (total number of digits).
+    scale: int
+        The scale (number of decimal places).
+
+    Returns
+    -------
+    Variable
+        A Variable representing the decimal value.
+    """
     _warning(f"numbers.number({value}, {precision}, {scale})")
     return numbers.number(value, precision, scale)
 
-def parse_decimal(value: str, precision=38, scale=14) -> Expression:
+@include_in_docs
+def parse_decimal(value: str, precision:int=38, scale:int=14) -> Expression:
+    """
+    Parse a string into a decimal with specified precision and scale.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.parse_number(value, precision, scale) <std.numbers.parse_number>` instead.
+
+    Parameters
+    ----------
+    value: str
+        The string value to parse.
+    precision: int
+        The precision (total number of digits).
+    scale: int
+        The scale (number of decimal places).
+
+    Returns
+    -------
+    Expression
+        An Expression computing the parsed decimal.
+    """
     _warning(f"numbers.parse_number({value}, {precision}, {scale})")
     return numbers.parse_number(value, precision, scale)
 
+@include_in_docs
 def parse(value: str, decimal: Concept) -> Expression:
+    """
+    Parse a string into a decimal with the type specified by decimal concept.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.parse(value, decimal) <std.numbers.parse>` instead.
+
+    Parameters
+    ----------
+    value: str
+        The string value to parse.
+    decimal: Concept
+        The NumberConcept specifying the decimal type.
+
+    Returns
+    -------
+    Expression
+        An Expression computing the parsed decimal.
+    """
     assert isinstance(decimal, NumberConcept)
     _warning(f"numbers.parse({value}, {decimal})")
     return numbers.parse(value, decimal)
@@ -26,22 +99,90 @@ def parse(value: str, decimal: Concept) -> Expression:
 # Decimal information
 #--------------------------------------------------
 
+@include_in_docs
 def is_decimal(decimal: Concept) -> bool:
+    """
+    Check if a concept represents a decimal number.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.is_number(decimal) <std.numbers.is_number>` instead.
+
+    Parameters
+    ----------
+    decimal: Concept
+        The NumberConcept to check.
+
+    Returns
+    -------
+    bool
+        True if the concept is a decimal number.
+    """
     assert isinstance(decimal, NumberConcept)
     _warning(f"numbers.is_number({decimal})")
     return numbers.is_number(decimal)
 
+@include_in_docs
 def precision(decimal: Concept) -> int:
+    """
+    Get the precision (total number of digits) of a decimal concept.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.precision(decimal) <std.numbers.precision>` instead.
+
+    Parameters
+    ----------
+    decimal: Concept
+        The NumberConcept to query.
+
+    Returns
+    -------
+    int
+        The precision of the decimal.
+    """
     assert isinstance(decimal, NumberConcept)
     _warning(f"numbers.precision({decimal})")
     return numbers.precision(decimal)
 
+@include_in_docs
 def scale(decimal: Concept) -> int:
+    """
+    Get the scale (number of decimal places) of a decimal concept.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.scale(decimal) <std.numbers.scale>` instead.
+
+    Parameters
+    ----------
+    decimal: Concept
+        The NumberConcept to query.
+
+    Returns
+    -------
+    int
+        The scale of the decimal.
+    """
     assert isinstance(decimal, NumberConcept)
     _warning(f"numbers.scale({decimal})")
     return numbers.scale(decimal)
 
+@include_in_docs
 def size(decimal: Concept) -> int:
+    """
+    Get the size (in bytes) of a decimal concept.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.size(decimal) <std.numbers.size>` instead.
+
+    Parameters
+    ----------
+    decimal: Concept
+        The NumberConcept to query.
+
+    Returns
+    -------
+    int
+        The size in bytes of the decimal.
+    """
     assert isinstance(decimal, NumberConcept)
     _warning(f"numbers.size({decimal})")
     return numbers.size(decimal)

relationalai/semantics/std/floats.py

@@ -1,15 +1,68 @@
+"""
+Float manipulation functions.
+
+This module provides functions for working with floating-point numbers including
+type conversion and parsing from strings.
+"""
+from __future__ import annotations
+
 from . import StringValue
 from ..frontend.base import Library, Expression, Field, Value
-from ..frontend.core import Float, String, Number
-from decimal import Decimal as PyDecimal
+from ..frontend.core import Float, String
+from relationalai.util.docutils import include_in_docs
+
+__include_in_docs__ = True
 
 # the front-end library object
 library = Library("floats")
 
-_parse_float = library.Relation("parse_float", [Field.input("value", String), Field("result", Float)])
-
+@include_in_docs
 def float(value: Value) -> Expression:
+    """
+    Convert a value to a Float.
+
+    Parameters
+    ----------
+    value: Value
+        The value to convert to a `Float`.
+
+    Returns
+    -------
+    Expression
+        An `Expression` computing the `Float` conversion. Returns `Float`.
+
+    Examples
+    --------
+    Convert various types to floats:
+
+    >>> floats.float(42)
+    >>> floats.float(Product.price)
+    """
     return Float(value)
 
+_parse_float = library.Relation("parse_float", [Field.input("value", String), Field("result", Float)])
+
+@include_in_docs
 def parse_float(value: StringValue) -> Expression:
+    """
+    Parse a string into a Float.
+
+    Parameters
+    ----------
+    value: StringValue
+        The string value to parse.
+
+    Returns
+    -------
+    Expression
+        An `Expression` computing the parsed `Float`. Returns `Float`.
+
+    Examples
+    --------
+    Parse strings into floats:
+
+    >>> floats.parse_float("3.14159")
+    >>> floats.parse_float("2.3E40")
+    >>> floats.parse_float(Measurement.value_str)
+    """
     return _parse_float(value)

relationalai/semantics/std/integers.py

@@ -1,31 +1,125 @@
+"""
+Integer manipulation functions.
+
+.. deprecated:: 0.13.0
+   This module is deprecated. Use `std.numbers` instead.
+
+This module provides functions for working with integers including type coercion
+and parsing from strings.
+"""
 from __future__ import annotations
 
 from ..frontend.base import Expression, Variable
 from ..frontend.core import Integer
+from relationalai.util.docutils import include_in_docs
 
 from . import StringValue, IntegerValue, numbers, _deprecated_library
 
+__include_in_docs__ = True
+
 
-# Coerce a number to Int64.
+@include_in_docs
 def int64(value: IntegerValue) -> Variable:
+    """
+    Coerce a number to Int64.
+
+    .. deprecated:: 0.13.0
+       Use `std.numbers` functions instead.
+
+    Parameters
+    ----------
+    value: IntegerValue
+        The integer value to coerce.
+
+    Returns
+    -------
+    Variable
+        A Variable representing the Int64 value.
+    """
     _warning()
     return Integer(value)
 
-# Coerce a number to Int128.
+@include_in_docs
 def int128(value: IntegerValue) -> Variable:
+    """
+    Coerce a number to Int128.
+
+    .. deprecated:: 0.13.0
+       Use `std.numbers` functions instead.
+
+    Parameters
+    ----------
+    value: IntegerValue
+        The integer value to coerce.
+
+    Returns
+    -------
+    Variable
+        A Variable representing the Int128 value.
+    """
     _warning()
     return Integer(value)
 
+@include_in_docs
 def parse_int64(value: StringValue) -> Expression:
-    _warning(f"numbers.parse_number({value}, , 0)")
+    """
+    Parse a string into an Int64.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.parse_number(value, 19, 0) <std.numbers.parse_number>` instead.
+
+    Parameters
+    ----------
+    value: StringValue
+        The string value to parse.
+
+    Returns
+    -------
+    Expression
+        An Expression computing the parsed Int64.
+    """
+    _warning(f"numbers.parse_number({value}, 19, 0)")
     return numbers.parse_number(value, 19, 0)
 
+@include_in_docs
 def parse_int128(value: StringValue) -> Expression:
+    """
+    Parse a string into an Int128.
+
+    .. deprecated:: 0.13.0
+       Use `numbers.parse_number(value, 38, 0) <std.numbers.parse_number>` instead.
+
+    Parameters
+    ----------
+    value: StringValue
+        The string value to parse.
+
+    Returns
+    -------
+    Expression
+        An Expression computing the parsed Int128.
+    """
     _warning(f"numbers.parse_number({value}, 38, 0)")
     return numbers.parse_number(value, 38, 0)
 
-# Alias parse_int128 to parse
+@include_in_docs
 def parse(value: StringValue) -> Expression:
+    """
+    Parse a string into an Int128 (alias for parse_int128).
+
+    .. deprecated:: 0.13.0
+       Use `numbers.parse_number(value, 38, 0) <std.numbers.parse_number>` instead.
+
+    Parameters
+    ----------
+    value: StringValue
+        The string value to parse.
+
+    Returns
+    -------
+    Expression
+        An Expression computing the parsed Int128.
+    """
     return parse_int128(value)