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

relationalai/semantics/std/numbers.py

@@ -1,11 +1,21 @@
+"""
+Number manipulation functions.
+
+This module provides functions for working with numbers including:
+- Number construction with precision and scale
+- Integer operations
+- Parsing numbers from strings
+- Querying number properties (precision, scale, size)
+"""
 from __future__ import annotations
 
 from . import NumberValue, StringValue
-from .. import literal
 from ..frontend.base import Library, Concept, MetaRef, NumberConcept, Expression, Field, Variable
-from ..frontend.core import Number, String, cast as core_cast
+from ..frontend.core import Number, String, Integer, cast as core_cast
 from decimal import Decimal as PyDecimal
+from relationalai.util.docutils import include_in_docs
 
+__include_in_docs__ = True
 
 # the front-end library object
 library = Library("numbers")
@@ -15,32 +25,119 @@ library = Library("numbers")
 #--------------------------------------------------
 _parse_number = library.Relation("parse_number", [Field.input("value", String), Field("result", Number)])
 
-def number(value: NumberValue, precision=38, scale=14) -> Variable:
+@include_in_docs
+def number(value: NumberValue, precision:int=38, scale:int=14) -> Variable:
     """
-    Create an expression that represents a number with this value, precision and scale.
+    Create an expression that represents a number with specified value, precision and scale.
+
+    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 number with the specified properties. Returns `Number`.
+
+    Examples
+    --------
+    Create a number with custom precision and scale:
+
+    >>> numbers.number(123.456, precision=10, scale=3)
+    >>> numbers.number(Product.price, precision=12, scale=2)
     """
     if isinstance(value, Variable):
         cast_type = Number.size(precision, scale)
         return core_cast(MetaRef(cast_type), value, cast_type.ref())
 
     # literals
-    if isinstance(value, int):
+    if isinstance(value, int) and scale != 0:
         value = PyDecimal(str(value))
     if isinstance(value, float):
         value = PyDecimal(str(value))
-    return literal(value, Number.size(precision, scale))
+    return Number.size(precision, scale)(value)
 
-def parse_number(value: StringValue, precision=38, scale=14) -> Expression:
+@include_in_docs
+def integer(value: NumberValue) -> Variable:
     """
-    Create an expression that represents parsing this string value as a number with this
-    precision and scale.
+    Create an expression that represents an integer with this value.
+
+    Parameters
+    ----------
+    value: NumberValue
+        The integer value.
+
+    Returns
+    -------
+    Variable
+        A `Variable` representing the integer value. Returns `Integer`.
+
+    Examples
+    --------
+    Create integer expressions:
+
+    >>> numbers.integer(42)
+    >>> numbers.integer(Employee.age)
+    """
+    if isinstance(value, Variable):
+        return core_cast(MetaRef(Integer), value, Integer.ref())
+    return Integer(value)
+
+@include_in_docs
+def parse_number(value: StringValue, precision:int=38, scale:int=14) -> Expression:
+    """
+    Parse a string value as a number with specified precision and scale.
+
+    Parameters
+    ----------
+    value: StringValue
+        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 number. Returns `Number`.
+
+    Examples
+    --------
+    Parse string to number:
+
+    >>> numbers.parse_number("123.456")
+    >>> numbers.parse_number(Product.price_str, precision=10, scale=2)
     """
     return _parse_number(value, Number.size(precision, scale).ref())
 
+@include_in_docs
 def parse(value: str, number: NumberConcept) -> Expression:
     """
-    Create an expression that represents parsing this string value as a number with the
-    precision and scale of the number argument.
+    Parse a string value as a number with the precision and scale of the number argument.
+
+    Parameters
+    ----------
+    value: str
+        The string value to parse.
+    number: NumberConcept
+        The NumberConcept specifying the target precision and scale.
+
+    Returns
+    -------
+    Expression
+        An `Expression` computing the parsed number. Returns `Number`.
+
+    Examples
+    --------
+    Parse string using another number's format:
+
+    >>> numbers.parse("999.99", Product.price)
     """
     return parse_number(value, precision(number), scale(number))
 
@@ -48,30 +145,129 @@ def parse(value: str, number: NumberConcept) -> Expression:
 # Number information.
 #--------------------------------------------------
 
+@include_in_docs
 def is_number(number: Concept) -> bool:
+    """
+    Check if a concept represents a number.
+
+    Parameters
+    ----------
+    number: Concept
+        The Concept to check.
+
+    Returns
+    -------
+    bool
+        True if the concept is a NumberConcept.
+
+    Examples
+    --------
+    Check if a concept is a number:
+
+    >>> numbers.is_number(Product.price)
+    """
     return isinstance(number, NumberConcept)
 
+@include_in_docs
 def precision(number: NumberConcept) -> int:
-    """ Assuming the concept represents a number, return its precision. """
+    """
+    Get the precision (total number of digits) of a number concept.
+
+    Parameters
+    ----------
+    number: NumberConcept
+        The NumberConcept to query.
+
+    Returns
+    -------
+    int
+        The precision of the number.
+
+    Examples
+    --------
+    Get the precision of a number concept:
+
+    >>> numbers.precision(Product.price)
+    """
     return number._precision
 
+@include_in_docs
 def scale(number: NumberConcept) -> int:
-    """ Assuming the concept represents a number, return its scale. """
+    """
+    Get the scale (number of decimal places) of a number concept.
+
+    Parameters
+    ----------
+    number: NumberConcept
+        The NumberConcept to query.
+
+    Returns
+    -------
+    int
+        The scale of the number.
+
+    Examples
+    --------
+    Get the scale of a number concept:
+
+    >>> numbers.scale(Product.price)
+    """
     return number._scale
 
+@include_in_docs
 def size(number: NumberConcept) -> int:
     """
-    Assuming the concept represents a number, return its size, i.e. the number of bits
-    needed to represent the number.
+    Get the size (number of bits) needed to represent a number concept.
+
+    Parameters
+    ----------
+    number: NumberConcept
+        The NumberConcept to query.
+
+    Returns
+    -------
+    int
+        The size in bits needed to represent the number.
+
+    Examples
+    --------
+    Get the bit size of a number concept:
+
+    >>> numbers.size(Product.price)
     """
-    return digits_to_bits(number.precision)
+    return digits_to_bits(number._precision)
 
-def digits_to_bits(precision)-> int:
+@include_in_docs
+def digits_to_bits(precision: int) -> int:
     """
-    Transform from a number of base 10 digits to the number of bits necessary to represent
-    that. If the precision is larger than 38, return None as that is not supported.
+    Transform from a number of base 10 digits to the number of bits necessary to represent it.
+
+    Parameters
+    ----------
+    precision: int
+        The number of base 10 digits.
+
+    Returns
+    -------
+    int
+        The number of bits required (8, 16, 32, 64, or 128).
+
+    Raises
+    ------
+    ValueError
+        If precision is greater than 38 or invalid.
+
+    Examples
+    --------
+    A number with 38 digits requires 128 bits:
+
+    >>> numbers.digits_to_bits(38)
+    128
+
+    A number with 9 digits requires 32 bits:
 
-    For example, a number with 38 digits requires 128 bits.
+    >>> numbers.digits_to_bits(9)
+    32
     """
     if precision <= 2:
         return 8

relationalai/semantics/std/re.py

@@ -1,11 +1,23 @@
+"""
+Regular expression function.
+
+This module provides regex pattern matching and manipulation functions including:
+- Pattern matching
+- Finding all matches
+- String substitution
+- Match object with position and grouping support
+"""
 from __future__ import annotations
 
 
 from . import StringValue, IntegerValue, strings, _function_not_implemented
 from ..frontend.base import Library, Expression, Field, Variable
-from ..frontend.core import Number, String, Integer
+from ..frontend.core import String, Integer
+from relationalai.util.docutils import include_in_docs
 from enum import Enum
 
+__include_in_docs__ = True
+
 # the front-end library object
 library = Library("re")
 
@@ -27,21 +39,106 @@ _regex_match_all = library.Relation("regex_match_all", [Field.input("regex", Str
 
 #  match is ^{REGEX} , search is {REGEX}, and fullmatch is ^{REGEX}$
 
+@include_in_docs
 def match(regex: StringValue, value: StringValue) -> RegexMatch:
-    """ Check if the regex matches the value from the start. """
+    """
+    Check if the regex matches the value from the start.
+
+    Parameters
+    ----------
+    regex: StringValue
+        The regular expression pattern.
+    value: StringValue
+        The string value to match against.
+
+    Returns
+    -------
+    RegexMatch
+        A `RegexMatch` object representing the match result.
+
+    Examples
+    --------
+    Match a pattern from the start of a string:
+
+    >>> re.match(r"S.*", Person.name)
+    >>> select(Person.name).where(re.match(r"^[A-Z]", Person.name))
+    """
     # REGEXP_LIKE
     return RegexMatch(regex, value, type=RegexMatchType.MATCH)
 
+@include_in_docs
 def search(regex: StringValue, value: StringValue, pos: IntegerValue = 0) -> RegexMatch:
+    """
+    Search for the regex pattern in the value starting at the given position.
+
+    .. note::
+       This function is not yet implemented.
+
+    Parameters
+    ----------
+    regex: StringValue
+        The regular expression pattern.
+    value: StringValue
+        The string value to search in.
+    pos: IntegerValue
+        The starting position for the search (0-based). Default: 0.
+
+    Returns
+    -------
+    RegexMatch
+        A `RegexMatch` object representing the search result.
+    """
     _function_not_implemented("re.search")
     return RegexMatch(regex, value, pos, type=RegexMatchType.SEARCH)
 
+@include_in_docs
 def fullmatch(regex: StringValue, value: StringValue, pos: IntegerValue = 0) -> RegexMatch:
-    """ Check if the regex matches the entire value starting at the given position. """
+    """
+    Check if the regex matches the entire value starting at the given position.
+
+    Parameters
+    ----------
+    regex: StringValue
+        The regular expression pattern.
+    value: StringValue
+        The string value to match against.
+    pos: IntegerValue
+        The starting position for the match (0-based). Default: 0.
+
+    Returns
+    -------
+    RegexMatch
+        A `RegexMatch` object representing the match result.
+
+    Examples
+    --------
+    Match entire string against a pattern:
+
+    >>> re.fullmatch(r"[A-Z][a-z]+", Person.name)
+    >>> select(Email.address).where(re.fullmatch(r"\\w+@\\w+\\.\\w+", Email.address))
+    """
     return RegexMatch(regex, value, pos, type=RegexMatchType.FULLMATCH)
 
+@include_in_docs
 def findall(regex: StringValue, value: StringValue) -> tuple[Variable, Variable]:
-    """ Find all non-overlapping matches of the regex in the value. """
+    """
+    Find all non-overlapping matches of the regex in the value.
+
+    .. note::
+       This function is not yet implemented.
+
+    Parameters
+    ----------
+    regex: StringValue
+        The regular expression pattern.
+    value: StringValue
+        The string value to search in.
+
+    Returns
+    -------
+    tuple[Variable, Variable]
+        A tuple of (position, match) `Variable`s representing all matches. Position is `Integer`, match is `String`.
+    """
     _function_not_implemented("re.findall")
     # exp = _regex_match_all(regex, value)
     # ix, match = exp._arg_ref(2), exp._arg_ref(3)
@@ -49,19 +146,69 @@ def findall(regex: StringValue, value: StringValue) -> tuple[Variable, Variable]
     # return rank, match
     raise
 
+@include_in_docs
 def sub(regex: StringValue, repl: StringValue, value: StringValue):
-    """ Replace occurrences of the regex in the value with the replacement string. """
+    """
+    Replace occurrences of the regex in the value with the replacement string.
+
+    .. note::
+       This function is not yet implemented.
+
+    Parameters
+    ----------
+    regex: StringValue
+        The regular expression pattern.
+    repl: StringValue
+        The replacement string.
+    value: StringValue
+        The string value to perform substitution on.
+
+    Returns
+    -------
+    Expression
+        An `Expression` computing the substituted string. Returns `String`.
+    """
     _function_not_implemented("re.sub")
     # return _regex_replace(regex, repl, value)
 
 class RegexMatchType(Enum):
+    """Enumeration of regex match types."""
     MATCH = "match"
     SEARCH = "search"
     FULLMATCH = "fullmatch"
 
+@include_in_docs
 class RegexMatch(Expression):
+    """
+    Represents a regex match result with position and grouping support.
+
+    Attributes
+    ----------
+    regex: StringValue
+        The regex pattern used for matching.
+    value: StringValue
+        The string value being matched.
+    pos: IntegerValue
+        The starting position of the match (0-based).
+    match: Variable
+        A Variable representing the matched string.
+    """
 
     def __init__(self, regex: StringValue, value: StringValue, pos: IntegerValue = 0, type=RegexMatchType.MATCH):
+        """
+        Initialize a RegexMatch object.
+
+        Parameters
+        ----------
+        regex: StringValue
+            The regular expression pattern.
+        value: StringValue
+            The string value to match against.
+        pos: IntegerValue
+            The starting position for the match (0-based). Default: 0.
+        type: RegexMatchType
+            The type of match (MATCH, SEARCH, or FULLMATCH). Default: MATCH.
+        """
         if type == RegexMatchType.FULLMATCH:
             # fullmatch: ^{REGEX}$
             self.regex = strings.concat(regex, "$")
@@ -74,20 +221,81 @@ class RegexMatch(Expression):
         self.match = String.ref("match")
         super().__init__(_regex_match_all, (self.regex, value, self.pos, self.match))
 
+    @include_in_docs
     def start(self) -> IntegerValue:
+        """
+        Get the starting position of the match.
+
+        Returns
+        -------
+        IntegerValue
+            The 0-based starting position of the match.
+        """
         return self.pos
 
+    @include_in_docs
     def end(self) -> IntegerValue:
+        """
+        Get the ending position of the match.
+
+        Returns
+        -------
+        IntegerValue
+            The 0-based ending position of the match.
+        """
         return strings.len(self.match) + self.pos - 1
 
+    @include_in_docs
     def span(self) -> tuple[IntegerValue, IntegerValue]:
+        """
+        Get the start and end positions of the match.
+
+        Returns
+        -------
+        tuple[IntegerValue, IntegerValue]
+            A tuple of (start, end) positions.
+        """
         return self.start(), self.end()
 
+    @include_in_docs
     def group(self, index: IntegerValue = 0) -> Variable:
+        """
+        Get a capture group by index.
+
+        .. note::
+           This method is not yet implemented.
+
+        Parameters
+        ----------
+        index: IntegerValue
+            The index of the capture group (0 for the entire match). Default: 0.
+
+        Returns
+        -------
+        Variable
+            A Variable representing the capture group content.
+        """
         _function_not_implemented("re.RegexMatch.group")
         raise
 
+    @include_in_docs
     def group_by_name(self, name: StringValue) -> Variable:
+        """
+        Get a named capture group.
+
+        .. note::
+           This method is not yet implemented.
+
+        Parameters
+        ----------
+        name: StringValue
+            The name of the capture group.
+
+        Returns
+        -------
+        Variable
+            A Variable representing the named capture group content.
+        """
         _function_not_implemented("re.RegexMatch.group_by_name")
         raise