pixeltable 0.2.11__py3-none-any.whl → 0.2.13__py3-none-any.whl

pixeltable/functions/string.py

@@ -1,17 +1,632 @@
-from typing import Any
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs) for `StringType`.
+It closely follows the Pandas `pandas.Series.str` API.
+
+Example:
+```python
+import pixeltable as pxt
+from pixeltable.functions import string as pxt_str
+
+t = pxt.get_table(...)
+t.select(pxt_str.capitalize(t.str_col)).collect()
+```
+"""
+
+from typing import Any, Optional
 
 import pixeltable.func as func
 from pixeltable.type_system import StringType
 from pixeltable.utils.code import local_public_names
 
 
-@func.udf(return_type=StringType(), param_types=[StringType()])
-def str_format(format_str: str, *args: Any, **kwargs: Any) -> str:
-    """Return a formatted version of format_str, using substitutions from args and kwargs:
-    - {<int>} will be replaced by the corresponding element in args
-    - {<key>} will be replaced by the corresponding value in kwargs
+@func.udf
+def capitalize(s: str) -> str:
+    """
+    Return `s` with its first character capitalized and the rest lowercased.
+
+    Equivalent to [`str.capitalize()`](https://docs.python.org/3/library/stdtypes.html#str.capitalize).
+    """
+    return s.capitalize()
+
+@func.udf
+def casefold(s: str) -> str:
+    """
+    Return a casefolded copy of `s`.
+
+    Equivalent to [`str.casefold()`](https://docs.python.org/3/library/stdtypes.html#str.casefold).
+    """
+    return s.casefold()
+
+@func.udf
+def center(s: str, width: int, fillchar: str = ' ') -> str:
+    """
+    Return a centered string of length `width`.
+
+    Equivalent to [`str.center()`](https://docs.python.org/3/library/stdtypes.html#str.center).
+
+    Args:
+        s: String.
+        width: Total width of the resulting string.
+        fillchar: Character used for padding.
+    """
+    return s.center(width, fillchar)
+
+@func.udf
+def contains(s: str, pattern: str, case: bool = True, flags: int = 0, regex: bool = True) -> bool:
+    """
+    Test if pattern or regex is contained within a string.
+
+    Args:
+        s: String.
+        pattern: string literal or regular expression
+        case: if False, ignore case
+        flags: [flags](https://docs.python.org/3/library/re.html#flags) for the `re` module
+        regex: if True, treat pattern as a regular expression
+    """
+    if regex:
+        import re
+        if not case:
+            flags |= re.IGNORECASE
+        return bool(re.search(pattern, s, flags))
+    else:
+        if case:
+            return pattern in s
+        else:
+            return pattern.lower() in s.lower()
+
+@func.udf
+def count(s: str, pattern: str, flags: int = 0) -> int:
+    """
+    Count occurrences of pattern or regex in `s`.
+
+    Args:
+        s: String.
+        pattern: string literal or regular expression
+        flags: [flags](https://docs.python.org/3/library/re.html#flags) for the `re` module
+    """
+    import re
+    from builtins import len
+    return len(re.findall(pattern, s, flags))
+
+@func.udf
+def endswith(s: str, pattern: str) -> bool:
+    """
+    Return `True` if the string ends with the specified suffix, otherwise return `False`.
+
+    Equivalent to [`str.endswith()`](https://docs.python.org/3/library/stdtypes.html#str.endswith).
+
+    Args:
+        s: String.
+        pattern: string literal
+    """
+    return s.endswith(pattern)
+
+@func.udf
+def fill(s: str, width: int, **kwargs: Any) -> str:
+    """
+    Wraps the single paragraph in `s`, and returns a single string containing the wrapped paragraph.
+
+    Equivalent to [`textwrap.fill()`](https://docs.python.org/3/library/textwrap.html#textwrap.fill).
+
+    Args:
+        s: String.
+        width: Maximum line width.
+        kwargs: Additional keyword arguments to pass to `textwrap.fill()`.
+    """
+    import textwrap
+    return textwrap.fill(s, width, **kwargs)
+
+@func.udf
+def find(s: str, substr: str, start: Optional[int] = 0, end: Optional[int] = None) -> int:
+    """
+    Return the lowest index in `s` where `substr` is found within the slice `s[start:end]`.
+
+    Equivalent to [`str.find()`](https://docs.python.org/3/library/stdtypes.html#str.find).
+
+    Args:
+        s: String.
+        substr: substring to search for
+        start: slice start
+        end: slice end
+    """
+    return s.find(substr, start, end)
+
+@func.udf
+def findall(s: str, pattern: str, flags: int = 0) -> list:
+    """
+    Find all occurrences of a regular expression pattern in a string.
+
+    Equivalent to [`re.findall()`](https://docs.python.org/3/library/re.html#re.findall).
+
+    Args:
+        s: String.
+        pattern: regular expression pattern
+        flags: [flags](https://docs.python.org/3/library/re.html#flags) for the `re` module
+    """
+    import re
+    return re.findall(pattern, s, flags)
+
+@func.udf
+def format(s: str, *args: Any, **kwargs: Any) -> str:
+    """
+    Perform string formatting.
+
+    Equivalent to [`str.format()`](https://docs.python.org/3/library/stdtypes.html#str.format).
+    """
+    return s.format(*args, **kwargs)
+
+@func.udf
+def fullmatch(s: str, pattern: str, case: bool = True, flags: int = 0) -> bool:
+    """
+    Determine if `s` fully matches a regular expression.
+
+    Equivalent to [`re.fullmatch()`](https://docs.python.org/3/library/re.html#re.fullmatch).
+
+    Args:
+        s: String.
+        pattern: regular expression pattern
+        case: if False, ignore case
+        flags: [flags](https://docs.python.org/3/library/re.html#flags) for the `re` module
+    """
+    import re
+    if not case:
+        flags |= re.IGNORECASE
+    _ = bool(re.fullmatch(pattern, s, flags))
+    return bool(re.fullmatch(pattern, s, flags))
+
+@func.udf
+def index(s: str, substr: str, start: Optional[int] = 0, end: Optional[int] = None) -> int:
+    """
+    Return the lowest index in `s` where `substr` is found within the slice `s[start:end]`. Raises ValueError if `substr` is not found.
+
+    Equivalent to [`str.index()`](https://docs.python.org/3/library/stdtypes.html#str.index).
+
+    Args:
+        s: String.
+        substr: substring to search for
+        start: slice start
+        end: slice end
+    """
+    return s.index(substr, start, end)
+
+@func.udf
+def isalnum(s: str) -> bool:
+    """
+    Return `True` if all characters in the string are alphanumeric and there is at least one character, `False`
+    otherwise.
+
+    Equivalent to [`str.isalnum()`](https://docs.python.org/3/library/stdtypes.html#str.isalnum
+    """
+    return s.isalnum()
+
+@func.udf
+def isalpha(s: str) -> bool:
+    """
+    Return `True` if all characters in the string are alphabetic and there is at least one character, `False` otherwise.
+
+    Equivalent to [`str.isalpha()`](https://docs.python.org/3/library/stdtypes.html#str.isalpha).
+    """
+    return s.isalpha()
+
+@func.udf
+def isascii(s: str) -> bool:
+    """
+    Return `True` if the string is empty or all characters in the string are ASCII, `False` otherwise.
+
+    Equivalent to [`str.isascii()`](https://docs.python.org/3/library/stdtypes.html#str.isascii).
+    """
+    return s.isascii()
+
+@func.udf
+def isdecimal(s: str) -> bool:
+    """
+    Return `True` if all characters in the string are decimal characters and there is at least one character, `False`
+    otherwise.
+
+    Equivalent to [`str.isdecimal()`](https://docs.python.org/3/library/stdtypes.html#str.isdecimal).
+    """
+    return s.isdecimal()
+
+@func.udf
+def isdigit(s: str) -> bool:
+    """
+    Return `True` if all characters in the string are digits and there is at least one character, `False` otherwise.
+
+    Equivalent to [`str.isdigit()`](https://docs.python.org/3/library/stdtypes.html#str.isdigit).
+    """
+    return s.isdigit()
+
+@func.udf
+def isidentifier(s: str) -> bool:
+    """
+    Return `True` if the string is a valid identifier according to the language definition, `False` otherwise.
+
+    Equivalent to [`str.isidentifier()`](https://docs.python.org/3/library/stdtypes.html#str.isidentifier)
+    """
+    return s.isidentifier()
+
+
+@func.udf
+def islower(s: str) -> bool:
+    """
+    Return `True` if all cased characters in the string are lowercase and there is at least one cased character, `False` otherwise.
+
+    Equivalent to [`str.islower()`](https://docs.python.org/3/library/stdtypes.html#str.islower)
+    """
+    return s.islower()
+
+@func.udf
+def isnumeric(s: str) -> bool:
+    """
+    Return `True` if all characters in the string are numeric characters, `False` otherwise.
+
+    Equivalent to [`str.isnumeric()`](https://docs.python.org/3/library/stdtypes.html#str.isnumeric)
+    """
+    return s.isnumeric()
+
+@func.udf
+def isupper(s: str) -> bool:
+    """
+    Return `True` if all cased characters in the string are uppercase and there is at least one cased character, `False` otherwise.
+
+    Equivalent to [`str.isupper()`](https://docs.python.org/3/library/stdtypes.html#str.isupper)
+    """
+    return s.isupper()
+
+@func.udf
+def istitle(s: str) -> bool:
+    """
+    Return `True` if the string is a titlecased string and there is at least one character, `False` otherwise.
+
+    Equivalent to [`str.istitle()`](https://docs.python.org/3/library/stdtypes.html#str.istitle)
+    """
+    return s.istitle()
+
+@func.udf
+def isspace(s: str) -> bool:
+    """
+    Return `True` if there are only whitespace characters in the string and there is at least one character, `False` otherwise.
+
+    Equivalent to [`str.isspace()`](https://docs.python.org/3/library/stdtypes.html#str.isspace)
+    """
+    return s.isspace()
+
+@func.udf
+def len(s: str) -> int:
+    """
+    Return the number of characters in the string.
+
+    Equivalent to [`len(str)`](https://docs.python.org/3/library/functions.html#len)
+    """
+    return s.__len__()
+
+@func.udf
+def ljust(s: str, width: int, fillchar: str = ' ') -> str:
+    """
+    Return the string left-justified in a string of length `width`. Padding is done using the specified `fillchar` (default is a space).
+
+    Equivalent to [`str.ljust()`](https://docs.python.org/3/library/stdtypes.html#str.ljust)
+
+    Args:
+        s: String.
+        width: Minimum width of resulting string; additional characters will be filled with character defined in `fillchar`.
+        fillchar: Additional character for filling.
+    """
+    return s.ljust(width, fillchar)
+
+@func.udf
+def lower(s: str) -> str:
+    """
+    Return a copy of the string with all the cased characters converted to lowercase.
+
+    Equivalent to [`str.lower()`](https://docs.python.org/3/library/stdtypes.html#str.lower)
+    """
+    return s.lower()
+
+@func.udf
+def lstrip(s: str, chars: Optional[str] = None) -> str:
+    """
+    Return a copy of the string with leading characters removed. The `chars` argument is a string specifying the set of
+    characters to be removed. If omitted or `None`, whitespace characters are removed.
+
+    Equivalent to [`str.lstrip()`](https://docs.python.org/3/library/stdtypes.html#str.lstrip)
+
+    Args:
+        s: String.
+        chars: The set of characters to be removed.
+    """
+    return s.lstrip(chars)
+
+@func.udf
+def match(s: str, pattern: str, case: bool = True, flags: int = 0) -> bool:
+    """
+    Determine if string starts with a match of a regular expression
+
+    Args:
+        s: String.
+        pattern: regular expression pattern
+        case: if False, ignore case
+        flags: [flags](https://docs.python.org/3/library/re.html#flags) for the `re` module
+    """
+    import re
+    if not case:
+        flags |= re.IGNORECASE
+    return bool(re.match(pattern, s, flags))
+
+@func.udf
+def normalize(s: str, form: str) -> str:
+    """
+    Return the Unicode normal form for `s`.
+
+    Equivalent to [`unicodedata.normalize()`](https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize)
+
+    Args:
+        s: String.
+        form: Unicode normal form (`‘NFC’`, `‘NFKC’`, `‘NFD’`, `‘NFKD’`)
+    """
+    import unicodedata
+    return unicodedata.normalize(form, s)
+
+@func.udf
+def pad(s: str, width: int, side: str = 'left', fillchar: str = ' ') -> str:
+    """
+    Pad string up to width
+
+    Args:
+        s: String.
+        width: Minimum width of resulting string; additional characters will be filled with character defined in `fillchar`.
+        side: Side from which to fill resulting string (`‘left’`, `‘right’`, `‘both’`)
+        fillchar: Additional character for filling
+    """
+    if side == 'left':
+        return s.ljust(width, fillchar)
+    elif side == 'right':
+        return s.rjust(width, fillchar)
+    elif side == 'both':
+        return s.center(width, fillchar)
+    else:
+        raise ValueError(f"Invalid side: {side}")
+
+@func.udf
+def partition(s: str, sep: str = ' ') -> list:
+    """
+    Splits `s` at the first occurrence of `sep`, and returns 3 elements containing the part before the
+    separator, the separator itself, and the part after the separator. If the separator is not found, return 3 elements
+    containing `s` itself, followed by two empty strings.
+    """
+    idx = s.find(sep)
+    if idx == -1:
+        return [s, '', '']
+    from builtins import len
+    return [s[:idx], sep, s[idx + len(sep):]]
+
+@func.udf
+def removeprefix(s: str, prefix: str) -> str:
+    """
+    Remove prefix from `s`. If the prefix is not present, returns `s`.
+    """
+    if s.startswith(prefix):
+        # we need to avoid referring to our symbol 'len'
+        from builtins import len
+        return s[len(prefix):]
+    return s
+
+@func.udf
+def removesuffix(s: str, suffix: str) -> str:
+    """
+    Remove suffix from `s`. If the suffix is not present, returns `s`.
+    """
+    if s.endswith(suffix):
+        # we need to avoid referring to our symbol 'len'
+        from builtins import len
+        return s[:-len(suffix)]
+    return s
+
+@func.udf
+def repeat(s: str, n: int) -> str:
+    """
+    Repeat `s` `n` times.
+    """
+    return s * n
+
+@func.udf
+def replace(
+        s: str, pattern: str, repl: str, n: int = -1, case: bool = True, flags: int = 0, regex: bool = False
+) -> str:
+    """
+    Replace occurrences of `pattern` in `s` with `repl`.
+
+    Equivalent to [`str.replace()`](https://docs.python.org/3/library/stdtypes.html#str.replace) or
+    [`re.sub()`](https://docs.python.org/3/library/re.html#re.sub), depending on the value of regex.
+
+    Args:
+        s: String.
+        pattern: string literal or regular expression
+        repl: replacement string
+        n: number of replacements to make (-1 for all)
+        case: if False, ignore case
+        flags: [flags](https://docs.python.org/3/library/re.html#flags) for the `re` module
+        regex: if True, treat pattern as a regular expression
+    """
+    if regex:
+        import re
+        if not case:
+            flags |= re.IGNORECASE
+        return re.sub(pattern, repl, s, 0 if n == -1 else n, flags)
+    else:
+        return s.replace(pattern, repl, n)
+
+@func.udf
+def rfind(s: str, substr: str, start: Optional[int] = 0, end: Optional[int] = None) -> int:
+    """
+    Return the highest index in `s` where `substr` is found, such that `substr` is contained within `s[start:end]`.
+
+    Equivalent to [`str.rfind()`](https://docs.python.org/3/library/stdtypes.html#str.rfind).
+
+    Args:
+        s: String.
+        substr: substring to search for
+        start: slice start
+        end: slice end
+    """
+    return s.rfind(substr, start, end)
+
+@func.udf
+def rindex(s: str, substr: str, start: Optional[int] = 0, end: Optional[int] = None) -> int:
+    """
+    Return the highest index in `s` where `substr` is found, such that `substr` is contained within `s[start:end]`.
+    Raises ValueError if `substr` is not found.
+
+    Equivalent to [`str.rindex()`](https://docs.python.org/3/library/stdtypes.html#str.rindex).
+    """
+    return s.rindex(substr, start, end)
+
+@func.udf
+def rjust(s: str, width: int, fillchar: str = ' ') -> str:
+    """
+    Return `s` right-justified in a string of length `width`.
+
+    Equivalent to [`str.rjust()`](https://docs.python.org/3/library/stdtypes.html#str.rjust).
+
+    Args:
+        s: String.
+        width: Minimum width of resulting string.
+        fillchar: Additional character for filling.
+    """
+    return s.rjust(width, fillchar)
+
+@func.udf
+def rpartition(s: str, sep: str = ' ') -> list:
+    """
+    This method splits `s` at the last occurrence of `sep`, and returns a list containing the part before the
+    separator, the separator itself, and the part after the separator.
+    """
+    idx = s.rfind(sep)
+    if idx == -1:
+        return [s, '', '']
+    from builtins import len
+    return [s[:idx], sep, s[idx + len(sep):]]
+
+@func.udf
+def rstrip(s: str, chars: Optional[str] = None) -> str:
+    """
+    Return a copy of `s` with trailing characters removed.
+
+    Equivalent to [`str.rstrip()`](https://docs.python.org/3/library/stdtypes.html#str.rstrip).
+
+    Args:
+        s: String.
+        chars: The set of characters to be removed. If omitted or `None`, whitespace characters are removed.
+    """
+    return s.rstrip(chars)
+
+@func.udf
+def slice(s: str, start: Optional[int] = None, stop: Optional[int] = None, step: Optional[int] = None) -> str:
+    """
+    Return a slice of `s`.
+
+    Args:
+        s: String.
+        start: slice start
+        stop: slice end
+        step: slice step
+    """
+    return s[start:stop:step]
+
+@func.udf
+def slice_replace(s: str, start: Optional[int] = None, stop: Optional[int] = None, repl: Optional[str] = None) -> str:
+    """
+    Replace a positional slice of a string with another value.
+
+    Args:
+        s: String.
+        start: slice start
+        stop: slice end
+        repl: replacement value
+    """
+    return s[:start] + repl + s[stop:]
+
+@func.udf
+def startswith(s: str, pattern: str) -> int:
+    """
+    Return `True` if `s` starts with `pattern`, otherwise return `False`.
+
+    Equivalent to [`str.startswith()`](https://docs.python.org/3/library/stdtypes.html#str.startswith).
+
+    Args:
+        s: String.
+        pattern: string literal
+    """
+    return s.startswith(pattern)
+
+@func.udf
+def strip(s: str, chars: Optional[str] = None) -> str:
+    """
+    Return a copy of `s` with leading and trailing characters removed.
+
+    Equivalent to [`str.strip()`](https://docs.python.org/3/library/stdtypes.html#str.strip).
+
+    Args:
+        s: String.
+        chars: The set of characters to be removed. If omitted or `None`, whitespace characters are removed.
+    """
+    return s.strip(chars)
+
+@func.udf
+def swapcase(s: str) -> str:
+    """
+    Return a copy of `s` with uppercase characters converted to lowercase and vice versa.
+
+    Equivalent to [`str.swapcase()`](https://docs.python.org/3/library/stdtypes.html#str.swapcase).
+    """
+    return s.swapcase()
+
+@func.udf
+def title(s: str) -> str:
+    """
+    Return a titlecased version of `s`, i.e. words start with uppercase characters, all remaining cased characters are
+    lowercase.
+
+    Equivalent to [`str.title()`](https://docs.python.org/3/library/stdtypes.html#str.title).
+    """
+    return s.title()
+
+@func.udf
+def upper(s: str) -> str:
+    """
+    Return a copy of `s` converted to uppercase.
+    Equivalent to [`str.upper()`](https://docs.python.org/3/library/stdtypes.html#str.upper).
+    """
+    return s.upper()
+
+@func.udf
+def wrap(s: str, width: int, **kwargs: Any) -> dict:
+    """
+    Wraps the single paragraph in `s` so every line is at most `width` characters long.
+    Returns a list of output lines, without final newlines.
+
+    Equivalent to [`textwrap.fill()`](https://docs.python.org/3/library/textwrap.html#textwrap.fill).
+
+    Args:
+        s: String.
+        width: Maximum line width.
+        kwargs: Additional keyword arguments to pass to `textwrap.fill()`.
+    """
+    import textwrap
+    return textwrap.wrap(s, width, **kwargs)
+
+@func.udf
+def zfill(s: str, width: int) -> str:
+    """
+    Pad a numeric string `s` with ASCII `0` on the left to a total length of `width`.
+
+    Equivalent to [`str.zfill()`](https://docs.python.org/3/library/stdtypes.html#str.zfill).
+
+    Args:
+        s: String.
+        width: Minimum width of resulting string.
     """
-    return format_str.format(*args, **kwargs)
+    return s.zfill(width)
 
 
 __all__ = local_public_names(__name__)

pixeltable/functions/video.py

@@ -1,3 +1,16 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs) for `VideoType`.
+
+Example:
+```python
+import pixeltable as pxt
+from pixeltable.functions import video as pxt_video
+
+t = pxt.get_table(...)
+t.select(pxt_video.extract_audio(t.video_col)).collect()
+```
+"""
+
 import tempfile
 import uuid
 from pathlib import Path
@@ -43,6 +56,9 @@ _format_defaults = {  # format -> (codec, ext)
     allows_window=False,
 )
 class make_video(func.Aggregator):
+    """
+    Aggregator that creates a video from a sequence of images.
+    """
     def __init__(self, fps: int = 25):
         """follows https://pyav.org/docs/develop/cookbook/numpy.html#generating-video"""
         self.container: Optional[av.container.OutputContainer] = None
@@ -84,7 +100,14 @@ _extract_audio_param_types = [
 def extract_audio(
     video_path: str, stream_idx: int = 0, format: str = 'wav', codec: Optional[str] = None
 ) -> Optional[str]:
-    """Extract an audio stream from a video file, save it as a media file and return its path"""
+    """
+    Extract an audio stream from a video file, save it as a media file and return its path.
+
+    Args:
+        stream_idx: Index of the audio stream to extract.
+        format: The target audio format. (`'wav'`, `'mp3'`, `'flac'`).
+        codec: The codec to use for the audio stream. If not provided, a default codec will be used.
+    """
     if format not in _format_defaults:
         raise ValueError(f'extract_audio(): unsupported audio format: {format}')
     default_codec, ext = _format_defaults[format]
@@ -107,13 +130,8 @@ def extract_audio(
 
 @func.udf(return_type=ts.JsonType(nullable=False), param_types=[ts.VideoType(nullable=False)])
 def get_metadata(video: str) -> dict:
-    """Gets various metadata associated with a video file.
-
-    Args:
-        video (str): Path to the video file.
-
-    Returns:
-        A dictionary containing the associated metadata.
+    """
+    Gets various metadata associated with a video file and returns it as a dictionary.
     """
     with av.open(video) as container:
         assert isinstance(container, av.container.InputContainer)