piccolo 0.109.0__py3-none-any.whl → 0.111.0__py3-none-any.whl

piccolo/__init__.py

@@ -1 +1 @@
-__VERSION__ = "0.109.0"
+__VERSION__ = "0.111.0"

piccolo/apps/asgi/commands/new.py

@@ -10,10 +10,9 @@ from jinja2 import Environment, FileSystemLoader
 
 TEMPLATE_DIR = os.path.join(os.path.dirname(__file__), "templates/app/")
 SERVERS = ["uvicorn", "Hypercorn"]
-ROUTERS = ["starlette", "fastapi", "blacksheep", "xpresso", "starlite"]
+ROUTERS = ["starlette", "fastapi", "blacksheep", "litestar"]
 ROUTER_DEPENDENCIES = {
-    "starlite": ["starlite>=1.46.0"],
-    "xpresso": ["xpresso==0.43.0", "di==0.72.1"],
+    "litestar": ["litestar==2.0.0a3"],
 }
 
 

piccolo/apps/asgi/commands/templates/app/{_starlite_app.py.jinja → _litestar_app.py.jinja}

@@ -2,13 +2,13 @@ import typing as t
 
 from piccolo.engine import engine_finder
 from piccolo_admin.endpoints import create_admin
-from starlite import Starlite, asgi, delete, get, patch, post
-from starlite.config.static_files import StaticFilesConfig
-from starlite.config.template import TemplateConfig
-from starlite.contrib.jinja import JinjaTemplateEngine
-from starlite.exceptions import NotFoundException
-from starlite.plugins.piccolo_orm import PiccoloORMPlugin
-from starlite.types import Receive, Scope, Send
+from litestar import Litestar, asgi, delete, get, patch, post
+from litestar.static_files import StaticFilesConfig
+from litestar.template import TemplateConfig
+from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.contrib.piccolo_orm import PiccoloORMPlugin
+from litestar.exceptions import NotFoundException
+from litestar.types import Receive, Scope, Send
 
 from home.endpoints import home
 from home.piccolo_app import APP_CONFIG
@@ -71,7 +71,7 @@ async def close_database_connection_pool():
         print("Unable to connect to the database")
 
 
-app = Starlite(
+app = Litestar(
     route_handlers=[
         admin,
         home,

piccolo/apps/asgi/commands/templates/app/app.py.jinja

@@ -4,8 +4,6 @@
     {% include '_starlette_app.py.jinja' %}
 {% elif router == 'blacksheep' %}
     {% include '_blacksheep_app.py.jinja' %}
-{% elif router == 'xpresso' %}
-    {% include '_xpresso_app.py.jinja' %}
-{% elif router == 'starlite' %}
-    {% include '_starlite_app.py.jinja' %}
+{% elif router == 'litestar' %}
+    {% include '_litestar_app.py.jinja' %}
 {% endif %}

piccolo/apps/asgi/commands/templates/app/home/{_starlite_endpoints.py.jinja → _litestar_endpoints.py.jinja}

@@ -1,7 +1,7 @@
 import os
 
 import jinja2
-from starlite import MediaType, Request, Response, get
+from litestar import MediaType, Request, Response, get
 
 ENVIRONMENT = jinja2.Environment(
     loader=jinja2.FileSystemLoader(
@@ -19,3 +19,4 @@ def home(request: Request) -> Response:
         media_type=MediaType.HTML,
         status_code=200,
     )
+

piccolo/apps/asgi/commands/templates/app/home/endpoints.py.jinja

@@ -2,8 +2,6 @@
     {% include '_starlette_endpoints.py.jinja' %}
 {% elif router == 'blacksheep' %}
     {% include '_blacksheep_endpoints.py.jinja' %}
-{% elif router == 'xpresso' %}
-    {% include '_xpresso_endpoints.py.jinja' %}
-{% elif router == 'starlite' %}
-    {% include '_starlite_endpoints.py.jinja' %}
+{% elif router == 'litestar' %}
+    {% include '_litestar_endpoints.py.jinja' %}
 {% endif %}

piccolo/apps/asgi/commands/templates/app/home/templates/home.html.jinja_raw

@@ -51,12 +51,7 @@
                 <li><a href="/admin/">Admin</a></li>
                 <li><a href="/docs/">Swagger API</a></li>
             </ul>
-            <h3>Xpresso</h3>
-            <ul>
-                <li><a href="/admin/">Admin</a></li>
-                <li><a href="/docs/">Swagger API</a></li>
-            </ul>
-            <h3>Starlite</h3>
+            <h3>Litestar</h3>
             <ul>
                 <li><a href="/admin/">Admin</a></li>
                 <li><a href="/schema/swagger">Swagger API</a></li>

piccolo/apps/playground/commands/run.py

@@ -136,8 +136,7 @@ def populate():
     """
     for _table in reversed(TABLES):
         try:
-            if _table.table_exists().run_sync():
-                _table.alter().drop_table().run_sync()
+            _table.alter().drop_table(if_exists=True).run_sync()
         except Exception as e:
             print(e)
 
@@ -180,13 +179,30 @@ def populate():
     ticket = Ticket(concert=concert.id, price=Decimal("50.0"))
     ticket.save().run_sync()
 
-    discount_code = DiscountCode(code=uuid.uuid4())
-    discount_code.save().run_sync()
+    DiscountCode.insert(
+        *[DiscountCode({DiscountCode.code: uuid.uuid4()}) for _ in range(5)]
+    ).run_sync()
 
-    recording_studio = RecordingStudio(
-        name="Abbey Road", facilities={"restaurant": True, "mixing_desk": True}
-    )
-    recording_studio.save().run_sync()
+    RecordingStudio.insert(
+        RecordingStudio(
+            {
+                RecordingStudio.name: "Abbey Road",
+                RecordingStudio.facilities: {
+                    "restaurant": True,
+                    "mixing_desk": True,
+                },
+            }
+        ),
+        RecordingStudio(
+            {
+                RecordingStudio.name: "Electric Lady",
+                RecordingStudio.facilities: {
+                    "restaurant": False,
+                    "mixing_desk": True,
+                },
+            },
+        ),
+    ).run_sync()
 
 
 def run(

piccolo/columns/column_types.py

@@ -1784,7 +1784,7 @@ class ForeignKey(Column):
 
     :param on_update:
         Determines what the database should do when a row has it's primary key
-        updated. If set to ``OnDelete.cascade``, any rows referencing the
+        updated. If set to ``OnUpdate.cascade``, any rows referencing the
         updated row will have their references updated to point to the new
         primary key.
 
@@ -1800,7 +1800,7 @@ class ForeignKey(Column):
 
         .. code-block:: python
 
-            from piccolo.columns import OnDelete
+            from piccolo.columns import OnUpdate
 
             class Band(Table):
                 name = ForeignKey(

piccolo/query/methods/insert.py

@@ -2,9 +2,16 @@ from __future__ import annotations
 
 import typing as t
 
-from piccolo.custom_types import TableInstance
+from typing_extensions import Literal
+
+from piccolo.custom_types import Combinable, TableInstance
 from piccolo.query.base import Query
-from piccolo.query.mixins import AddDelegate, ReturningDelegate
+from piccolo.query.mixins import (
+    AddDelegate,
+    OnConflictAction,
+    OnConflictDelegate,
+    ReturningDelegate,
+)
 from piccolo.querystring import QueryString
 
 if t.TYPE_CHECKING:  # pragma: no cover
@@ -15,7 +22,7 @@ if t.TYPE_CHECKING:  # pragma: no cover
 class Insert(
     t.Generic[TableInstance], Query[TableInstance, t.List[t.Dict[str, t.Any]]]
 ):
-    __slots__ = ("add_delegate", "returning_delegate")
+    __slots__ = ("add_delegate", "on_conflict_delegate", "returning_delegate")
 
     def __init__(
         self, table: t.Type[TableInstance], *instances: TableInstance, **kwargs
@@ -23,6 +30,7 @@ class Insert(
         super().__init__(table, **kwargs)
         self.add_delegate = AddDelegate()
         self.returning_delegate = ReturningDelegate()
+        self.on_conflict_delegate = OnConflictDelegate()
         self.add(*instances)
 
     ###########################################################################
@@ -36,6 +44,43 @@ class Insert(
         self.returning_delegate.returning(columns)
         return self
 
+    def on_conflict(
+        self: Self,
+        target: t.Optional[t.Union[str, Column, t.Tuple[Column, ...]]] = None,
+        action: t.Union[
+            OnConflictAction, Literal["DO NOTHING", "DO UPDATE"]
+        ] = OnConflictAction.do_nothing,
+        values: t.Optional[
+            t.Sequence[t.Union[Column, t.Tuple[Column, t.Any]]]
+        ] = None,
+        where: t.Optional[Combinable] = None,
+    ) -> Self:
+        if (
+            self.engine_type == "sqlite"
+            and self.table._meta.db.get_version_sync() < 3.24
+        ):
+            raise NotImplementedError(
+                "SQLite versions lower than 3.24 don't support ON CONFLICT"
+            )
+
+        if (
+            self.engine_type in ("postgres", "cockroach")
+            and len(self.on_conflict_delegate._on_conflict.on_conflict_items)
+            == 1
+        ):
+            raise NotImplementedError(
+                "Postgres and Cockroach only support a single ON CONFLICT "
+                "clause."
+            )
+
+        self.on_conflict_delegate.on_conflict(
+            target=target,
+            action=action,
+            values=values,
+            where=where,
+        )
+        return self
+
     ###########################################################################
 
     def _raw_response_callback(self, results):
@@ -70,16 +115,27 @@ class Insert(
 
         engine_type = self.engine_type
 
+        on_conflict = self.on_conflict_delegate._on_conflict
+        if on_conflict.on_conflict_items:
+            querystring = QueryString(
+                "{}{}",
+                querystring,
+                on_conflict.querystring,
+                query_type="insert",
+                table=self.table,
+            )
+
         if engine_type in ("postgres", "cockroach") or (
             engine_type == "sqlite"
             and self.table._meta.db.get_version_sync() >= 3.35
         ):
-            if self.returning_delegate._returning:
+            returning = self.returning_delegate._returning
+            if returning:
                 return [
                     QueryString(
                         "{}{}",
                         querystring,
-                        self.returning_delegate._returning.querystring,
+                        returning.querystring,
                         query_type="insert",
                         table=self.table,
                     )

piccolo/query/methods/objects.py

@@ -230,6 +230,8 @@ class Objects(
         return self
 
     def as_of(self, interval: str = "-1s") -> Objects:
+        if self.engine_type != "cockroach":
+            raise NotImplementedError("Only CockroachDB supports AS OF")
         self.as_of_delegate.as_of(interval)
         return self
 

piccolo/query/methods/select.py

@@ -353,8 +353,13 @@ class Select(Query[TableInstance, t.List[t.Dict[str, t.Any]]]):
         self.columns_delegate.columns(*_columns)
         return self
 
-    def distinct(self: Self) -> Self:
-        self.distinct_delegate.distinct()
+    def distinct(
+        self: Self, *, on: t.Optional[t.Sequence[Column]] = None
+    ) -> Self:
+        if on is not None and self.engine_type == "sqlite":
+            raise NotImplementedError("SQLite doesn't support DISTINCT ON")
+
+        self.distinct_delegate.distinct(enabled=True, on=on)
         return self
 
     def group_by(self: Self, *columns: t.Union[Column, str]) -> Self:
@@ -367,6 +372,9 @@ class Select(Query[TableInstance, t.List[t.Dict[str, t.Any]]]):
         return self
 
     def as_of(self: Self, interval: str = "-1s") -> Self:
+        if self.engine_type != "cockroach":
+            raise NotImplementedError("Only CockroachDB supports AS OF")
+
         self.as_of_delegate.as_of(interval)
         return self
 
@@ -722,17 +730,22 @@ class Select(Query[TableInstance, t.List[t.Dict[str, t.Any]]]):
 
         #######################################################################
 
-        select = (
-            "SELECT DISTINCT" if self.distinct_delegate._distinct else "SELECT"
-        )
-        query = f"{select} {columns_str} FROM {self.table._meta.tablename}"
+        args: t.List[t.Any] = []
 
-        for join in joins:
-            query += f" {join}"
+        query = "SELECT"
 
-        #######################################################################
+        distinct = self.distinct_delegate._distinct
+        if distinct:
+            if distinct.on:
+                distinct.validate_on(self.order_by_delegate._order_by)
 
-        args: t.List[t.Any] = []
+            query += "{}"
+            args.append(distinct.querystring)
+
+        query += f" {columns_str} FROM {self.table._meta.tablename}"
+
+        for join in joins:
+            query += f" {join}"
 
         if self.as_of_delegate._as_of:
             query += "{}"

piccolo/query/mixins.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 import asyncio
+import collections.abc
 import itertools
 import typing as t
 from dataclasses import dataclass, field
 from enum import Enum, auto
 
+from typing_extensions import Literal
+
 from piccolo.columns import And, Column, Or, Where
 from piccolo.columns.column_types import ForeignKey
 from piccolo.custom_types import Combinable
@@ -18,6 +21,70 @@ if t.TYPE_CHECKING:  # pragma: no cover
     from piccolo.table import Table  # noqa
 
 
+class DistinctOnError(ValueError):
+    """
+    Raised when ``DISTINCT ON`` queries are malformed.
+    """
+
+    pass
+
+
+@dataclass
+class Distinct:
+    __slots__ = ("enabled", "on")
+
+    enabled: bool
+    on: t.Optional[t.Sequence[Column]]
+
+    @property
+    def querystring(self) -> QueryString:
+        if self.enabled:
+            if self.on:
+                column_names = ", ".join(
+                    i._meta.get_full_name(with_alias=False) for i in self.on
+                )
+                return QueryString(f" DISTINCT ON ({column_names})")
+            else:
+                return QueryString(" DISTINCT")
+        else:
+            return QueryString(" ALL")
+
+    def validate_on(self, order_by: OrderBy):
+        """
+        When using the `on` argument, the first column must match the first
+        order by column.
+
+        :raises DistinctOnError:
+            If the columns don't match.
+
+        """
+        validated = True
+
+        try:
+            first_order_column = order_by.order_by_items[0].columns[0]
+        except IndexError:
+            validated = False
+        else:
+            if not self.on:
+                validated = False
+            elif isinstance(first_order_column, Column) and not self.on[
+                0
+            ]._equals(first_order_column):
+                validated = False
+
+        if not validated:
+            raise DistinctOnError(
+                "The first `order_by` column must match the first column "
+                "passed to `on`."
+            )
+
+    def __str__(self) -> str:
+        return self.querystring.__str__()
+
+    def copy(self) -> Distinct:
+        return self.__class__(enabled=self.enabled, on=self.on)
+
+
 @dataclass
 class Limit:
     __slots__ = ("number",)
@@ -259,10 +326,19 @@ class AsOfDelegate:
 @dataclass
 class DistinctDelegate:
 
-    _distinct: bool = False
+    _distinct: Distinct = field(
+        default_factory=lambda: Distinct(enabled=False, on=None)
+    )
+
+    def distinct(
+        self, enabled: bool, on: t.Optional[t.Sequence[Column]] = None
+    ):
+        if on and not isinstance(on, collections.abc.Sequence):
+            # Check a sequence is passed in, otherwise the user will get some
+            # unuseful errors later on.
+            raise ValueError("`on` must be a sequence of `Column` instances")
 
-    def distinct(self):
-        self._distinct = True
+        self._distinct = Distinct(enabled=enabled, on=on)
 
 
 @dataclass
@@ -507,9 +583,10 @@ class OffsetDelegate:
 
     Typically used in conjunction with order_by and limit.
 
-    Example usage:
+    Example usage::
+
+        .offset(100)
 
-    .offset(100)
     """
 
     _offset: t.Optional[Offset] = None
@@ -539,12 +616,173 @@ class GroupBy:
 @dataclass
 class GroupByDelegate:
     """
-    Used to group results - needed when doing aggregation.
+    Used to group results - needed when doing aggregation::
+
+        .group_by(Band.name)
 
-    .group_by(Band.name)
     """
 
     _group_by: t.Optional[GroupBy] = None
 
     def group_by(self, *columns: Column):
         self._group_by = GroupBy(columns=columns)
+
+
+class OnConflictAction(str, Enum):
+    """
+    Specify which action to take on conflict.
+    """
+
+    do_nothing = "DO NOTHING"
+    do_update = "DO UPDATE"
+
+
+@dataclass
+class OnConflictItem:
+    target: t.Optional[t.Union[str, Column, t.Tuple[Column, ...]]] = None
+    action: t.Optional[OnConflictAction] = None
+    values: t.Optional[
+        t.Sequence[t.Union[Column, t.Tuple[Column, t.Any]]]
+    ] = None
+    where: t.Optional[Combinable] = None
+
+    @property
+    def target_string(self) -> str:
+        target = self.target
+        assert target
+
+        def to_string(value) -> str:
+            if isinstance(value, Column):
+                return f'"{value._meta.db_column_name}"'
+            else:
+                raise ValueError("OnConflict.target isn't a valid type")
+
+        if isinstance(target, str):
+            return f'ON CONSTRAINT "{target}"'
+        elif isinstance(target, Column):
+            return f"({to_string(target)})"
+        elif isinstance(target, tuple):
+            columns_str = ", ".join([to_string(i) for i in target])
+            return f"({columns_str})"
+        else:
+            raise ValueError("OnConflict.target isn't a valid type")
+
+    @property
+    def action_string(self) -> QueryString:
+        action = self.action
+        if isinstance(action, OnConflictAction):
+            if action == OnConflictAction.do_nothing:
+                return QueryString(OnConflictAction.do_nothing.value)
+            elif action == OnConflictAction.do_update:
+                values = []
+                query = f"{OnConflictAction.do_update.value} SET"
+
+                if not self.values:
+                    raise ValueError("No values specified for `on conflict`")
+
+                for value in self.values:
+                    if isinstance(value, Column):
+                        column_name = value._meta.db_column_name
+                        query += f' "{column_name}"=EXCLUDED."{column_name}",'
+                    elif isinstance(value, tuple):
+                        column = value[0]
+                        value_ = value[1]
+                        if isinstance(column, Column):
+                            column_name = column._meta.db_column_name
+                        else:
+                            raise ValueError("Unsupported column type")
+
+                        query += f' "{column_name}"={{}},'
+                        values.append(value_)
+
+                return QueryString(query.rstrip(","), *values)
+
+        raise ValueError("OnConflict.action isn't a valid type")
+
+    @property
+    def querystring(self) -> QueryString:
+        query = " ON CONFLICT"
+        values = []
+
+        if self.target:
+            query += f" {self.target_string}"
+
+        if self.action:
+            query += " {}"
+            values.append(self.action_string)
+
+        if self.where:
+            query += " WHERE {}"
+            values.append(self.where.querystring)
+
+        return QueryString(query, *values)
+
+    def __str__(self) -> str:
+        return self.querystring.__str__()
+
+
+@dataclass
+class OnConflict:
+    """
+    Multiple `ON CONFLICT` statements are allowed - which is why we have this
+    parent class.
+    """
+
+    on_conflict_items: t.List[OnConflictItem] = field(default_factory=list)
+
+    @property
+    def querystring(self) -> QueryString:
+        query = "".join("{}" for i in self.on_conflict_items)
+        return QueryString(
+            query, *[i.querystring for i in self.on_conflict_items]
+        )
+
+    def __str__(self) -> str:
+        return self.querystring.__str__()
+
+
+@dataclass
+class OnConflictDelegate:
+    """
+    Used with insert queries to specify what to do when a query fails due to
+    a constraint::
+
+        .on_conflict(action='DO NOTHING')
+
+        .on_conflict(action='DO UPDATE', values=[Band.popularity])
+
+        .on_conflict(action='DO UPDATE', values=[(Band.popularity, 1)])
+
+    """
+
+    _on_conflict: OnConflict = field(default_factory=OnConflict)
+
+    def on_conflict(
+        self,
+        target: t.Optional[t.Union[str, Column, t.Tuple[Column, ...]]] = None,
+        action: t.Union[
+            OnConflictAction, Literal["DO NOTHING", "DO UPDATE"]
+        ] = OnConflictAction.do_nothing,
+        values: t.Optional[
+            t.Sequence[t.Union[Column, t.Tuple[Column, t.Any]]]
+        ] = None,
+        where: t.Optional[Combinable] = None,
+    ):
+        action_: OnConflictAction
+        if isinstance(action, OnConflictAction):
+            action_ = action
+        elif isinstance(action, str):
+            action_ = OnConflictAction(action.upper())
+        else:
+            raise ValueError("Unrecognised `on conflict` action.")
+
+        if where and action_ == OnConflictAction.do_nothing:
+            raise ValueError(
+                "The `where` option can only be used with DO NOTHING."
+            )
+
+        self._on_conflict.on_conflict_items.append(
+            OnConflictItem(
+                target=target, action=action_, values=values, where=where
+            )
+        )