pixeltable 0.2.13__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

@@ -96,7 +96,7 @@ _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]:
@@ -128,7 +128,7 @@ 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 and returns it as a dictionary.

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/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

pixeltable/io/globals.py

@@ -1,5 +1,7 @@
-from typing import Any, Optional, Literal
+from typing import Any, Literal, Optional, Union
+import urllib.request
 
+import pixeltable as pxt
 import pixeltable.exceptions as excs
 from pixeltable import Table
 from pixeltable.io.external_store import SyncStatus
@@ -134,3 +136,133 @@ def create_label_studio_project(
         return t.sync()
     else:
         return SyncStatus.empty()
+
+
+def import_rows(
+    tbl_path: str,
+    rows: list[dict[str, Any]],
+    *,
+    schema_overrides: Optional[dict[str, pxt.ColumnType]] = None,
+    primary_key: Optional[Union[str, list[str]]] = None,
+    num_retained_versions: int = 10,
+    comment: str = ''
+    ) -> Table:
+    """
+    Creates a new `Table` from a list of dictionaries. The dictionaries must be of the form
+    `{column_name: value, ...}`. Pixeltable will attempt to infer the schema of the table from the
+    supplied data, using the most specific type that can represent all the values in a column.
+
+    If `schema_overrides` is specified, then for each entry `(column_name, type)` in `schema_overrides`,
+    Pixeltable will force the specified column to the specified type (and will not attempt any type inference
+    for that column).
+
+    All column types of the new `Table` will be nullable unless explicitly specified as non-nullable in
+    `schema_overrides`.
+
+    Args:
+        tbl_path: The qualified name of the table to create.
+        rows: The list of dictionaries to import.
+        schema_overrides: If specified, then columns in `schema_overrides` will be given the specified types
+            as described above.
+        primary_key: The primary key of the table (see [`create_table()`][pixeltable.create_table]).
+        num_retained_versions: The number of retained versions of the table (see [`create_table()`][pixeltable.create_table]).
+        comment: A comment to attach to the table (see [`create_table()`][pixeltable.create_table]).
+
+    Returns:
+        The newly created `Table`.
+    """
+    if schema_overrides is None:
+        schema_overrides = {}
+    schema: dict[str, pxt.ColumnType] = {}
+    cols_with_nones: set[str] = set()
+
+    for n, row in enumerate(rows):
+        for col_name, value in row.items():
+            if col_name in schema_overrides:
+                # We do the insertion here; this will ensure that the column order matches the order
+                # in which the column names are encountered in the input data, even if `schema_overrides`
+                # is specified.
+                if col_name not in schema:
+                    schema[col_name] = schema_overrides[col_name]
+            elif value is not None:
+                # If `key` is not in `schema_overrides`, then we infer its type from the data.
+                # The column type will always be nullable by default.
+                col_type = pxt.ColumnType.infer_literal_type(value).copy(nullable=True)
+                if col_name not in schema:
+                    schema[col_name] = col_type
+                else:
+                    supertype = pxt.ColumnType.supertype(schema[col_name], col_type)
+                    if supertype is None:
+                        raise excs.Error(
+                            f'Could not infer type of column `{col_name}`; the value in row {n} does not match preceding type {schema[col_name]}: {value!r}\n'
+                            'Consider specifying the type explicitly in `schema_overrides`.'
+                        )
+                    schema[col_name] = supertype
+            else:
+                cols_with_nones.add(col_name)
+
+    extraneous_keys = schema_overrides.keys() - schema.keys()
+    if len(extraneous_keys) > 0:
+        raise excs.Error(f'The following columns specified in `schema_overrides` are not present in the data: {", ".join(extraneous_keys)}')
+
+    entirely_none_cols = cols_with_nones - schema.keys()
+    if len(entirely_none_cols) > 0:
+        # A column can only end up in `entirely_null_cols` if it was not in `schema_overrides` and
+        # was not encountered in any row with a non-None value.
+        raise excs.Error(
+            f'The following columns have no non-null values: {", ".join(entirely_none_cols)}\n'
+            'Consider specifying the type(s) explicitly in `schema_overrides`.'
+        )
+
+    t = pxt.create_table(tbl_path, schema, primary_key=primary_key, num_retained_versions=num_retained_versions, comment=comment)
+    t.insert(rows)
+    return t
+
+
+def import_json(
+    tbl_path: str,
+    filepath_or_url: str,
+    *,
+    schema_overrides: Optional[dict[str, pxt.ColumnType]] = None,
+    primary_key: Optional[Union[str, list[str]]] = None,
+    num_retained_versions: int = 10,
+    comment: str = '',
+    **kwargs: Any
+) -> Table:
+    """
+    Creates a new `Table` from a JSON file. This is a convenience method and is equivalent
+    to calling `import_data(table_path, json.loads(file_contents, **kwargs), ...)`, where `file_contents`
+    is the contents of the specified `filepath_or_url`.
+
+    Args:
+        tbl_path: The name of the table to create.
+        filepath_or_url: The path or URL of the JSON file.
+        schema_overrides: If specified, then columns in `schema_overrides` will be given the specified types
+            (see [`import_rows()`][pixeltable.io.import_rows]).
+        primary_key: The primary key of the table (see [`create_table()`][pixeltable.create_table]).
+        num_retained_versions: The number of retained versions of the table (see [`create_table()`][pixeltable.create_table]).
+        comment: A comment to attach to the table (see [`create_table()`][pixeltable.create_table]).
+        kwargs: Additional keyword arguments to pass to `json.loads`.
+
+    Returns:
+        The newly created `Table`.
+    """
+    import json
+    import urllib.parse
+    import urllib.request
+
+    # TODO Consolidate this logic with other places where files/URLs are parsed
+    parsed = urllib.parse.urlparse(filepath_or_url)
+    if len(parsed.scheme) <= 1 or parsed.scheme == 'file':
+        # local file path
+        if len(parsed.scheme) <= 1:
+            filepath = filepath_or_url
+        else:
+            filepath = urllib.parse.unquote(urllib.request.url2pathname(parsed.path))
+        with open(filepath) as fp:
+            contents = fp.read()
+    else:
+        # URL
+        contents = urllib.request.urlopen(filepath_or_url).read()
+    data = json.loads(contents, **kwargs)
+    return import_rows(tbl_path, data, schema_overrides=schema_overrides, primary_key=primary_key, num_retained_versions=num_retained_versions, comment=comment)