pixeltable 0.2.22__py3-none-any.whl → 0.2.23__py3-none-any.whl

pixeltable/globals.py

@@ -123,7 +123,8 @@ def create_view(
         additional_columns: If specified, will add these columns to the view once it is created. The format
             of the `additional_columns` parameter is identical to the format of the `schema_or_df` parameter in
             [`create_table`][pixeltable.create_table].
-        is_snapshot: Whether the view is a snapshot.
+        is_snapshot: Whether the view is a snapshot. Setting this to `True` is equivalent to calling
+            [`create_snapshot`][pixeltable.create_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.
         num_retained_versions: Number of versions of the view to retain.
@@ -142,11 +143,6 @@ def create_view(
 
         >>> tbl = pxt.get_table('my_table')
         ... view = pxt.create_view('my_view', tbl.where(tbl.col1 > 10))
-
-        Create a snapshot of `my_table`:
-
-        >>> tbl = pxt.get_table('my_table')
-        ... snapshot_view = pxt.create_view('my_snapshot_view', tbl, is_snapshot=True)
     """
     where: Optional[exprs.Expr] = None
     if isinstance(base, catalog.Table):
@@ -186,6 +182,59 @@ def create_view(
     return view
 
 
+def create_snapshot(
+    path_str: str,
+    base: Union[catalog.Table, DataFrame],
+    *,
+    additional_columns: Optional[dict[str, Any]] = None,
+    iterator: Optional[tuple[type[ComponentIterator], dict[str, Any]]] = None,
+    num_retained_versions: int = 10,
+    comment: str = '',
+    media_validation: Literal['on_read', 'on_write'] = 'on_write',
+    ignore_errors: bool = False,
+) -> Optional[catalog.Table]:
+    """Create a snapshot of an existing table object (which itself can be a view or a snapshot or a base table).
+
+    Args:
+        path_str: A name for the snapshot; can be either a simple name such as `my_snapshot`, or a pathname such as
+            `dir1.my_snapshot`.
+        base: [`Table`][pixeltable.Table] (i.e., table or view or snapshot) or [`DataFrame`][pixeltable.DataFrame] to
+            base the snapshot on.
+        additional_columns: If specified, will add these columns to the snapshot once it is created. The format
+            of the `additional_columns` parameter is identical to the format of the `schema_or_df` parameter in
+            [`create_table`][pixeltable.create_table].
+        iterator: The iterator to use for this snapshot. If specified, then this snapshot will be a one-to-many view of
+            the base table.
+        num_retained_versions: Number of versions of the view to retain.
+        comment: Optional comment for the view.
+        ignore_errors: if True, fail silently if the path already exists or is invalid.
+
+    Returns:
+        A handle to the [`Table`][pixeltable.Table] representing the newly created snapshot. If the path already
+            exists or is invalid and `ignore_errors=True`, returns `None`.
+
+    Raises:
+        Error: if the path already exists or is invalid and `ignore_errors=False`.
+
+    Examples:
+        Create a snapshot of `my_table`:
+
+        >>> tbl = pxt.get_table('my_table')
+        ... snapshot = pxt.create_snapshot('my_snapshot', tbl)
+    """
+    return create_view(
+        path_str,
+        base,
+        additional_columns=additional_columns,
+        iterator=iterator,
+        is_snapshot=True,
+        num_retained_versions=num_retained_versions,
+        comment=comment,
+        media_validation=media_validation,
+        ignore_errors=ignore_errors,
+    )
+
+
 def get_table(path: str) -> catalog.Table:
     """Get a handle to an existing table, view, or snapshot.
 

pixeltable/plan.py

@@ -1,4 +1,4 @@
-from typing import Any, Iterable, Optional, Sequence, cast
+from typing import Any, Iterable, Optional, Sequence
 from uuid import UUID
 
 import sqlalchemy as sql

pixeltable/tool/create_test_db_dump.py

@@ -153,7 +153,7 @@ class Dumper:
         self.__add_expr_columns(v, 'view')
 
         # snapshot
-        _ = pxt.create_view('views.snapshot', t.where(t.c2 >= 75), is_snapshot=True)
+        _ = pxt.create_snapshot('views.snapshot', t.where(t.c2 >= 75))
 
         # view of views
         vv = pxt.create_view('views.view_of_views', v.where(t.c2 >= 25))

pixeltable/type_system.py

@@ -5,6 +5,7 @@ import datetime
 import enum
 import io
 import json
+import types
 import typing
 import urllib.parse
 import urllib.request
@@ -272,63 +273,110 @@ class ColumnType:
         return inferred_type
 
     @classmethod
-    def from_python_type(cls, t: Union[type, _GenericAlias], nullable_default: bool = False) -> Optional[ColumnType]:
-        if typing.get_origin(t) is typing.Union:
+    def from_python_type(
+        cls,
+        t: Union[type, _GenericAlias],
+        nullable_default: bool = False,
+        allow_builtin_types: bool = True
+    ) -> Optional[ColumnType]:
+        """
+        Convert a Python type into a Pixeltable `ColumnType` instance.
+
+        Args:
+            t: The Python type.
+            nullable_default: If True, then the returned `ColumnType` will be nullable unless it is marked as
+                `Required`.
+            allow_builtin_types: If True, then built-in types such as `str`, `int`, `float`, etc., will be
+                allowed (as in UDF definitions). If False, then only Pixeltable types such as `pxt.String`,
+                `pxt.Int`, etc., will be allowed (as in schema definitions). `Optional` and `Required`
+                designations will be allowed regardless.
+        """
+        origin = typing.get_origin(t)
+        if origin is typing.Union:
+            # Check if `t` has the form Optional[T].
             union_args = typing.get_args(t)
             if len(union_args) == 2 and type(None) in union_args:
                 # `t` is a type of the form Optional[T] (equivalently, Union[T, None] or Union[None, T]).
                 # We treat it as the underlying type but with nullable=True.
                 underlying_py_type = union_args[0] if union_args[1] is type(None) else union_args[1]
-                underlying = cls.from_python_type(underlying_py_type)
+                underlying = cls.from_python_type(underlying_py_type, allow_builtin_types=allow_builtin_types)
                 if underlying is not None:
                     return underlying.copy(nullable=True)
-        elif typing.get_origin(t) is typing.Annotated:
+        elif origin is Required:
+            required_args = typing.get_args(t)
+            assert len(required_args) == 1
+            return cls.from_python_type(
+                required_args[0],
+                nullable_default=False,
+                allow_builtin_types=allow_builtin_types
+            )
+        elif origin is typing.Annotated:
             annotated_args = typing.get_args(t)
             origin = annotated_args[0]
             parameters = annotated_args[1]
             if isinstance(parameters, ColumnType):
                 return parameters.copy(nullable=nullable_default)
-        elif typing.get_origin(t) is Required:
-            required_args = typing.get_args(t)
-            assert len(required_args) == 1
-            return cls.from_python_type(required_args[0], nullable_default=False)
         else:
-            # Discard type parameters to ensure that parameterized types such as `list[T]`
-            # are correctly mapped to Pixeltable types.
-            origin = typing.get_origin(t)
-            if origin is None:
-                # No type parameters; the origin type is just `t` itself
-                origin = t
-            if issubclass(origin, _PxtType):
-                return origin.as_col_type(nullable=nullable_default)
-            if origin is str:
-                return StringType(nullable=nullable_default)
-            if origin is int:
-                return IntType(nullable=nullable_default)
-            if origin is float:
-                return FloatType(nullable=nullable_default)
-            if origin is bool:
-                return BoolType(nullable=nullable_default)
-            if origin is datetime.datetime:
-                return TimestampType(nullable=nullable_default)
-            if origin is PIL.Image.Image:
-                return ImageType(nullable=nullable_default)
-            if issubclass(origin, Sequence) or issubclass(origin, Mapping):
-                return JsonType(nullable=nullable_default)
+            # It's something other than Optional[T], Required[T], or an explicitly annotated type.
+            if origin is not None:
+                # Discard type parameters to ensure that parameterized types such as `list[T]`
+                # are correctly mapped to Pixeltable types.
+                t = origin
+            if isinstance(t, type) and issubclass(t, _PxtType):
+                return t.as_col_type(nullable=nullable_default)
+            elif allow_builtin_types:
+                if t is str:
+                    return StringType(nullable=nullable_default)
+                if t is int:
+                    return IntType(nullable=nullable_default)
+                if t is float:
+                    return FloatType(nullable=nullable_default)
+                if t is bool:
+                    return BoolType(nullable=nullable_default)
+                if t is datetime.datetime:
+                    return TimestampType(nullable=nullable_default)
+                if t is PIL.Image.Image:
+                    return ImageType(nullable=nullable_default)
+                if issubclass(t, Sequence) or issubclass(t, Mapping):
+                    return JsonType(nullable=nullable_default)
         return None
 
     @classmethod
-    def normalize_type(cls, t: Union[ColumnType, type, _AnnotatedAlias], nullable_default: bool = False) -> ColumnType:
+    def normalize_type(
+        cls,
+        t: Union[ColumnType, type, _AnnotatedAlias],
+        nullable_default: bool = False,
+        allow_builtin_types: bool = True
+    ) -> ColumnType:
         """
         Convert any type recognizable by Pixeltable to its corresponding ColumnType.
         """
         if isinstance(t, ColumnType):
             return t
-        col_type = cls.from_python_type(t, nullable_default)
+        col_type = cls.from_python_type(t, nullable_default, allow_builtin_types)
         if col_type is None:
-            raise excs.Error(f'Unknown type: {t}')
+            cls.__raise_exc_for_invalid_type(t)
         return col_type
 
+    __TYPE_SUGGESTIONS: list[tuple[type, str]] = [
+        (str, 'pxt.String'),
+        (bool, 'pxt.Bool'),
+        (int, 'pxt.Int'),
+        (float, 'pxt.Float'),
+        (datetime.datetime, 'pxt.Timestamp'),
+        (PIL.Image.Image, 'pxt.Image'),
+        (Sequence, 'pxt.Json'),
+        (Mapping, 'pxt.Json'),
+    ]
+
+    @classmethod
+    def __raise_exc_for_invalid_type(cls, t: Union[type, _AnnotatedAlias]) -> None:
+        for builtin_type, suggestion in cls.__TYPE_SUGGESTIONS:
+            if t is builtin_type or (isinstance(t, type) and issubclass(t, builtin_type)):
+                name = t.__name__ if t.__module__ == 'builtins' else f'{t.__module__}.{t.__name__}'
+                raise excs.Error(f'Standard Python type `{name}` cannot be used here; use `{suggestion}` instead')
+        raise excs.Error(f'Unknown type: {t}')
+
     def validate_literal(self, val: Any) -> None:
         """Raise TypeError if val is not a valid literal for this type"""
         if val is None:
@@ -979,7 +1027,7 @@ class Array(np.ndarray, _PxtType):
         `item` (the type subscript) must be a tuple with exactly two elements (in any order):
         - A tuple of `Optional[int]`s, specifying the shape of the array
         - A type, specifying the dtype of the array
-        Example: Array[(3, None, 2), float]
+        Example: Array[(3, None, 2), pxt.Float]
         """
         params = item if isinstance(item, tuple) else (item,)
         shape: Optional[tuple] = None
@@ -994,7 +1042,7 @@ class Array(np.ndarray, _PxtType):
             elif isinstance(param, type) or isinstance(param, _AnnotatedAlias):
                 if dtype is not None:
                     raise TypeError(f'Duplicate Array type parameter: {param}')
-                dtype = ColumnType.from_python_type(param)
+                dtype = ColumnType.normalize_type(param, allow_builtin_types=False)
             else:
                 raise TypeError(f'Invalid Array type parameter: {param}')
         if shape is None:

pixeltable/utils/coco.py

@@ -1,6 +1,6 @@
 import json
 from pathlib import Path
-from typing import Any, Dict, List, Set
+from typing import Any
 
 import PIL
 
@@ -22,7 +22,7 @@ Required format:
 }
 """
 
-def _verify_input_dict(input_dict: Dict[str, Any]) -> None:
+def _verify_input_dict(input_dict: dict[str, Any]) -> None:
     """Verify that input_dict is a valid input dict for write_coco_dataset()"""
     if not isinstance(input_dict, dict):
         raise excs.Error(f'Expected dict, got {input_dict}{format_msg}')
@@ -61,11 +61,11 @@ def write_coco_dataset(df: pxt.DataFrame, dest_path: Path) -> Path:
     images_dir = dest_path / 'images'
     images_dir.mkdir()
 
-    images: List[Dict[str, Any]] = []
+    images: list[dict[str, Any]] = []
     img_id = -1
-    annotations: List[Dict[str, Any]] = []
+    annotations: list[dict[str, Any]] = []
     ann_id = -1
-    categories: Set[Any] = set()
+    categories: set[Any] = set()
     for input_row in df._exec():
         if input_dict_slot_idx == -1:
             input_dict_expr = df._select_list_exprs[0]

pixeltable/utils/formatter.py

@@ -138,11 +138,11 @@ class Formatter:
         assert isinstance(img, Image.Image), f'Wrong type: {type(img)}'
         # Try to make it look decent in a variety of display scenarios
         if self.__num_rows > 1:
-            width = 240  # Multiple rows: display small images
+            width = min(240, img.width)  # Multiple rows: display small images
         elif self.__num_cols > 1:
-            width = 480  # Multiple columns: display medium images
+            width = min(480, img.width)  # Multiple columns: display medium images
         else:
-            width = 640  # A single image: larger display
+            width = min(640, img.width)  # A single image: larger display
         with io.BytesIO() as buffer:
             img.save(buffer, 'webp')
             img_base64 = base64.b64encode(buffer.getvalue()).decode()

pixeltable/utils/s3.py

@@ -1,13 +1,16 @@
 from typing import Any
 
 
-def get_client() -> Any:
+def get_client(**kwargs: Any) -> Any:
     import boto3
     import botocore
     try:
         boto3.Session().get_credentials().get_frozen_credentials()
-        return boto3.client('s3')  # credentials are available
+        config = botocore.config.Config(**kwargs)
+        return boto3.client('s3', config=config)  # credentials are available
     except AttributeError:
         # No credentials available, use unsigned mode
-        config = botocore.config.Config(signature_version=botocore.UNSIGNED)
+        config_args = kwargs.copy()
+        config_args['signature_version'] = botocore.UNSIGNED
+        config = botocore.config.Config(**config_args)
         return boto3.client('s3', config=config)