pixeltable 0.2.12__py3-none-any.whl → 0.2.14__py3-none-any.whl

pixeltable/functions/timestamp.py

@@ -0,0 +1,210 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs) for `TimestampType`.
+
+Usage example:
+```python
+import pixeltable as pxt
+
+t = pxt.get_table(...)
+t.select(t.timestamp_col.year, t.timestamp_col.weekday()).collect()
+```
+"""
+
+from datetime import datetime
+from typing import Optional
+
+import pixeltable.func as func
+from pixeltable.utils.code import local_public_names
+
+
+@func.udf(is_method=True)
+def year(self: datetime) -> int:
+    """
+    Between [`MINYEAR`](https://docs.python.org/3/library/datetime.html#datetime.MINYEAR) and
+    [`MAXYEAR`](https://docs.python.org/3/library/datetime.html#datetime.MAXYEAR) inclusive.
+
+    Equivalent to [`datetime.year`](https://docs.python.org/3/library/datetime.html#datetime.datetime.year).
+    """
+    return self.year
+
+
+@func.udf(is_method=True)
+def month(self: datetime) -> int:
+    """
+    Between 1 and 12 inclusive.
+
+    Equivalent to [`datetime.month`](https://docs.python.org/3/library/datetime.html#datetime.datetime.month).
+    """
+    return self.month
+
+
+@func.udf(is_method=True)
+def day(self: datetime) -> int:
+    """
+    Between 1 and the number of days in the given month of the given year.
+
+    Equivalent to [`datetime.day`](https://docs.python.org/3/library/datetime.html#datetime.datetime.day).
+    """
+    return self.day
+
+
+@func.udf(is_method=True)
+def hour(self: datetime) -> int:
+    """
+    Between 0 and 23 inclusive.
+
+    Equivalent to [`datetime.hour`](https://docs.python.org/3/library/datetime.html#datetime.datetime.hour).
+    """
+    return self.hour
+
+
+@func.udf(is_method=True)
+def minute(self: datetime) -> int:
+    """
+    Between 0 and 59 inclusive.
+
+    Equivalent to [`datetime.minute`](https://docs.python.org/3/library/datetime.html#datetime.datetime.minute).
+    """
+    return self.minute
+
+
+@func.udf(is_method=True)
+def second(self: datetime) -> int:
+    """
+    Between 0 and 59 inclusive.
+
+    Equivalent to [`datetime.second`](https://docs.python.org/3/library/datetime.html#datetime.datetime.second).
+    """
+    return self.second
+
+
+@func.udf(is_method=True)
+def microsecond(self: datetime) -> int:
+    """
+    Between 0 and 999999 inclusive.
+
+    Equivalent to [`datetime.microsecond`](https://docs.python.org/3/library/datetime.html#datetime.datetime.microsecond).
+    """
+    return self.microsecond
+
+
+@func.udf(is_method=True)
+def weekday(self: datetime) -> int:
+    """
+    Between 0 (Monday) and 6 (Sunday) inclusive.
+
+    Equivalent to [`datetime.weekday()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.weekday).
+    """
+    return self.weekday()
+
+@func.udf(is_method=True)
+def isoweekday(self: datetime) -> int:
+    """
+    Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
+
+    Equivalent to [`datetime.isoweekday()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoweekday).
+    """
+    return self.isoweekday()
+
+
+@func.udf(is_method=True)
+def isocalendar(self: datetime) -> dict:
+    """
+    Return a dictionary with three entries: `'year'`, `'week'`, and `'weekday'`.
+
+    Equivalent to
+    [`datetime.isocalendar()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isocalendar).
+    """
+    iso_year, iso_week, iso_weekday = self.isocalendar()
+    return {'year': iso_year, 'week': iso_week, 'weekday': iso_weekday}
+
+
+@func.udf(is_method=True)
+def isoformat(self: datetime, sep: str = 'T', timespec: str = 'auto') -> str:
+    """
+    Return a string representing the date and time in ISO 8601 format.
+
+    Equivalent to [`datetime.isoformat()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat).
+
+    Args:
+        sep: Separator between date and time.
+        timespec: The number of additional terms in the output. See the [`datetime.isoformat()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat) documentation for more details.
+    """
+    return self.isoformat(sep=sep, timespec=timespec)
+
+
+@func.udf(is_method=True)
+def strftime(self: datetime, format: str) -> str:
+    """
+    Return a string representing the date and time, controlled by an explicit format string.
+
+    Equivalent to [`datetime.strftime()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.strftime).
+
+    Args:
+        format: The format string to control the output. For a complete list of formatting directives, see [`strftime()` and `strptime()` Behavior](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior).
+    """
+    return self.strftime(format)
+
+
+# @func.udf
+# def date(self: datetime) -> datetime:
+#     """
+#     Return the date part of the datetime.
+#
+#     Equivalent to [`datetime.date()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.date).
+#     """
+#     d = self.date()
+#     return datetime(d.year, d.month, d.day)
+#
+#
+# @func.udf
+# def time(self: datetime) -> datetime:
+#     """
+#     Return the time part of the datetime, with microseconds set to 0.
+#
+#     Equivalent to [`datetime.time()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.time).
+#     """
+#     t = self.time()
+#     return datetime(1, 1, 1, t.hour, t.minute, t.second, t.microsecond)
+
+
+@func.udf(is_method=True)
+def replace(
+        self: datetime, year: Optional[int] = None, month: Optional[int] = None, day: Optional[int] = None,
+        hour: Optional[int] = None, minute: Optional[int] = None, second: Optional[int] = None,
+        microsecond: Optional[int] = None) -> datetime:
+    """
+    Return a datetime with the same attributes, except for those attributes given new values by whichever keyword
+    arguments are specified.
+
+    Equivalent to [`datetime.replace()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.replace).
+    """
+    kwargs = {k: v for k, v in locals().items() if k != 'self' and v is not None}
+    return self.replace(**kwargs)
+
+
+@func.udf(is_method=True)
+def toordinal(self: datetime) -> int:
+    """
+    Return the proleptic Gregorian ordinal of the date, where January 1 of year 1 has ordinal 1.
+
+    Equivalent to [`datetime.toordinal()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.toordinal).
+    """
+    return self.toordinal()
+
+
+@func.udf(is_method=True)
+def posix_timestamp(self: datetime) -> float:
+    """
+    Return POSIX timestamp corresponding to the datetime instance.
+
+    Equivalent to [`datetime.timestamp()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.timestamp).
+    """
+    return self.timestamp()
+
+
+__all__ = local_public_names(__name__)
+
+
+def __dir__():
+    return __all__

pixeltable/functions/together.py

@@ -1,3 +1,10 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs)
+that wrap various endpoints from the Together AI API. In order to use them, you must
+first `pip install together` and configure your Together AI credentials, as described in
+the [Working with Together AI](https://pixeltable.readme.io/docs/together-ai) tutorial.
+"""
+
 import base64
 from typing import Optional, TYPE_CHECKING
 
@@ -41,6 +48,31 @@ def completions(
     n: Optional[int] = None,
     safety_model: Optional[str] = None,
 ) -> dict:
+    """
+    Generate completions based on a given prompt using a specified model.
+
+    Equivalent to the Together AI `completions` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/completions-1](https://docs.together.ai/reference/completions-1)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        prompt: A string providing context for the model to complete.
+        model: The name of the model to query.
+
+    For details on the other parameters, see: [https://docs.together.ai/reference/completions-1](https://docs.together.ai/reference/completions-1)
+
+    Returns:
+        A dictionary containing the response and other metadata.
+
+    Examples:
+        Add a computed column that applies the model `mistralai/Mixtral-8x7B-v0.1` to an existing Pixeltable column `tbl.prompt`
+        of the table `tbl`:
+
+        >>> tbl['response'] = completions(tbl.prompt, model='mistralai/Mixtral-8x7B-v0.1')
+    """
     return (
         _together_client()
         .completions.create(
@@ -80,6 +112,32 @@ def chat_completions(
     tools: Optional[dict] = None,
     tool_choice: Optional[dict] = None,
 ) -> dict:
+    """
+    Generate chat completions based on a given prompt using a specified model.
+
+    Equivalent to the Together AI `chat/completions` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/chat-completions-1](https://docs.together.ai/reference/chat-completions-1)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        messages: A list of messages comprising the conversation so far.
+        model: The name of the model to query.
+
+    For details on the other parameters, see: [https://docs.together.ai/reference/chat-completions-1](https://docs.together.ai/reference/chat-completions-1)
+
+    Returns:
+        A dictionary containing the response and other metadata.
+
+    Examples:
+        Add a computed column that applies the model `mistralai/Mixtral-8x7B-v0.1` to an existing Pixeltable column `tbl.prompt`
+        of the table `tbl`:
+
+        >>> messages = [{'role': 'user', 'content': tbl.prompt}]
+        ... tbl['response'] = chat_completions(tbl.prompt, model='mistralai/Mixtral-8x7B-v0.1')
+    """
     return (
         _together_client()
         .chat.completions.create(
@@ -117,6 +175,29 @@ _embedding_dimensions_cache = {
 
 @pxt.udf(batch_size=32, return_type=pxt.ArrayType((None,), dtype=pxt.FloatType()))
 def embeddings(input: Batch[str], *, model: str) -> Batch[np.ndarray]:
+    """
+    Query an embedding model for a given string of text.
+
+    Equivalent to the Together AI `embeddings` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/embeddings-2](https://docs.together.ai/reference/embeddings-2)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        input: A string providing the text for the model to embed.
+        model: The name of the embedding model to use.
+
+    Returns:
+        An array representing the application of the given embedding to `input`.
+
+    Examples:
+        Add a computed column that applies the model `togethercomputer/m2-bert-80M-8k-retrieval`
+        to an existing Pixeltable column `tbl.text` of the table `tbl`:
+
+        >>> tbl['response'] = embeddings(tbl.text, model='togethercomputer/m2-bert-80M-8k-retrieval')
+    """
     result = _together_client().embeddings.create(input=input, model=model)
     return [np.array(data.embedding, dtype=np.float64) for data in result.data]
 
@@ -141,6 +222,31 @@ def image_generations(
     width: Optional[int] = None,
     negative_prompt: Optional[str] = None,
 ) -> PIL.Image.Image:
+    """
+    Generate images based on a given prompt using a specified model.
+
+    Equivalent to the Together AI `images/generations` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/post_images-generations](https://docs.together.ai/reference/post_images-generations)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        prompt: A description of the desired images.
+        model: The model to use for image generation.
+
+    For details on the other parameters, see: [https://docs.together.ai/reference/post_images-generations](https://docs.together.ai/reference/post_images-generations)
+
+    Returns:
+        The generated image.
+
+    Examples:
+        Add a computed column that applies the model `runwayml/stable-diffusion-v1-5`
+        to an existing Pixeltable column `tbl.prompt` of the table `tbl`:
+
+        >>> tbl['response'] = image_generations(tbl.prompt, model='runwayml/stable-diffusion-v1-5')
+    """
     # TODO(aaron-siegel): Decompose CPU/GPU ops into separate functions
     result = _together_client().images.generate(
         prompt=prompt, model=model, steps=steps, seed=seed, height=height, width=width, negative_prompt=negative_prompt

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
@@ -80,11 +96,18 @@ _extract_audio_param_types = [
 ]
 
 
-@func.udf(return_type=ts.AudioType(nullable=True), param_types=_extract_audio_param_types)
+@func.udf(return_type=ts.AudioType(nullable=True), param_types=_extract_audio_param_types, is_method=True)
 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]
@@ -105,15 +128,10 @@ def extract_audio(
         return output_filename
 
 
-@func.udf(return_type=ts.JsonType(nullable=False), param_types=[ts.VideoType(nullable=False)])
+@func.udf(return_type=ts.JsonType(nullable=False), param_types=[ts.VideoType(nullable=False)], is_method=True)
 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)

pixeltable/functions/whisper.py

@@ -1,3 +1,11 @@
+"""
+Pixeltable [UDF](https://pixeltable.readme.io/docs/user-defined-functions-udfs)
+that wraps the OpenAI Whisper library.
+
+This UDF will cause Pixeltable to invoke the relevant model locally. In order to use it, you must
+first `pip install openai-whisper`.
+"""
+
 from typing import TYPE_CHECKING, Optional
 
 import pixeltable as pxt
@@ -39,6 +47,30 @@ def transcribe(
     append_punctuations: str = '"\'.。,，!！?？:：”)]}、',
     decode_options: Optional[dict] = None,
 ) -> dict:
+    """
+    Transcribe an audio file using Whisper.
+
+    This UDF runs a transcription model _locally_ using the Whisper library,
+    equivalent to the Whisper `transcribe` function, as described in the
+    [Whisper library documentation](https://github.com/openai/whisper).
+
+    __Requirements:__
+
+    - `pip install openai-whisper`
+
+    Args:
+        audio: The audio file to transcribe.
+        model: The name of the model to use for transcription.
+
+    Returns:
+        A dictionary containing the transcription and various other metadata.
+
+    Examples:
+        Add a computed column that applies the model `base.en` to an existing Pixeltable column `tbl.audio`
+        of the table `tbl`:
+
+        >>> tbl['result'] = transcribe(tbl.audio, model='base.en')
+    """
     import torch
 
     if decode_options is None:

pixeltable/globals.py

@@ -7,10 +7,10 @@ import sqlalchemy as sql
 from sqlalchemy.util.preloaded import orm
 
 import pixeltable.exceptions as excs
+import pixeltable.exprs as exprs
 from pixeltable import catalog, func, DataFrame
 from pixeltable.catalog import Catalog
 from pixeltable.env import Env
-from pixeltable.exprs import Predicate
 from pixeltable.iterators import ComponentIterator
 from pixeltable.metadata import schema
 
@@ -81,7 +81,7 @@ def create_view(
     base: Union[catalog.Table, DataFrame],
     *,
     schema: Optional[dict[str, Any]] = None,
-    filter: Optional[Predicate] = None,
+    filter: Optional[exprs.Expr] = None,
     is_snapshot: bool = False,
     iterator: Optional[tuple[type[ComponentIterator], dict[str, Any]]] = None,
     num_retained_versions: int = 10,
@@ -94,7 +94,7 @@ def create_view(
         path_str: Path to the view.
         base: Table (i.e., table or view or snapshot) or DataFrame to base the view on.
         schema: dictionary mapping column names to column types, value expressions, or to column specifications.
-        filter: Predicate to filter rows of the base table.
+        filter: predicate to filter rows of the base table.
         is_snapshot: Whether the view is a snapshot.
         iterator: The iterator to use for this view. If specified, then this view will be a one-to-many view of
             the base table.

pixeltable/io/__init__.py

@@ -1,5 +1,5 @@
 from .external_store import ExternalStore, SyncStatus
-from .globals import create_label_studio_project
+from .globals import create_label_studio_project, import_rows, import_json
 from .hf_datasets import import_huggingface_dataset
 from .pandas import import_csv, import_excel, import_pandas
 from .parquet import import_parquet