piccolo 1.21.0__tar.gz → 1.22.0__tar.gz

{piccolo-1.21.0 → piccolo-1.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piccolo
-Version: 1.21.0
+Version: 1.22.0
 Summary: A fast, user friendly ORM and query builder which supports asyncio.
 Home-page: https://github.com/piccolo-orm/piccolo
 Author: Daniel Townsend
@@ -9,44 +9,28 @@ License: MIT
 Project-URL: Documentation, https://piccolo-orm.readthedocs.io/en/latest/index.html
 Project-URL: Source, https://github.com/piccolo-orm/piccolo
 Project-URL: Tracker, https://github.com/piccolo-orm/piccolo/issues
+Platform: UNKNOWN
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Framework :: AsyncIO
 Classifier: Typing :: Typed
 Classifier: Topic :: Database
-Requires-Python: >=3.8.0
+Requires-Python: >=3.9.0
 Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: black
-Requires-Dist: colorama>=0.4.0
-Requires-Dist: Jinja2>=2.11.0
-Requires-Dist: targ>=0.3.7
-Requires-Dist: inflection>=0.5.1
-Requires-Dist: typing-extensions>=4.3.0
-Requires-Dist: pydantic[email]==2.*
 Provides-Extra: orjson
-Requires-Dist: orjson>=3.5.1; extra == "orjson"
 Provides-Extra: playground
-Requires-Dist: ipython; extra == "playground"
 Provides-Extra: postgres
-Requires-Dist: asyncpg>=0.21.0; extra == "postgres"
 Provides-Extra: sqlite
-Requires-Dist: aiosqlite>=0.16.0; extra == "sqlite"
 Provides-Extra: uvloop
-Requires-Dist: uvloop>=0.12.0; sys_platform != "win32" and extra == "uvloop"
 Provides-Extra: all
-Requires-Dist: orjson>=3.5.1; extra == "all"
-Requires-Dist: ipython; extra == "all"
-Requires-Dist: asyncpg>=0.21.0; extra == "all"
-Requires-Dist: aiosqlite>=0.16.0; extra == "all"
-Requires-Dist: uvloop>=0.12.0; sys_platform != "win32" and extra == "all"
+License-File: LICENSE
 
 ![Logo](https://raw.githubusercontent.com/piccolo-orm/piccolo/master/docs/logo_hero.png "Piccolo Logo")
 
@@ -155,3 +139,5 @@ We have a handy page which shows the equivalent of [common Django queries in Pic
 Our documentation is on [Read the docs](https://piccolo-orm.readthedocs.io/en/latest/piccolo/getting_started/index.html).
 
 We also have some great [tutorial videos on YouTube](https://www.youtube.com/channel/UCE7x5nm1Iy9KDfXPNrNQ5lA).
+
+

piccolo-1.22.0/piccolo/__init__.py

@@ -0,0 +1 @@
+__VERSION__ = "1.22.0"

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo/apps/playground/commands/run.py

@@ -233,6 +233,11 @@ def populate():
             RecordingStudio.facilities: {
                 "restaurant": True,
                 "mixing_desk": True,
+                "instruments": {"electric_guitars": 10, "drum_kits": 2},
+                "technicians": [
+                    {"name": "Alice Jones"},
+                    {"name": "Bob Williams"},
+                ],
             },
         }
     )
@@ -244,6 +249,10 @@ def populate():
             RecordingStudio.facilities: {
                 "restaurant": False,
                 "mixing_desk": True,
+                "instruments": {"electric_guitars": 6, "drum_kits": 3},
+                "technicians": [
+                    {"name": "Frank Smith"},
+                ],
             },
         },
     )

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo/columns/column_types.py

@@ -70,6 +70,10 @@ from piccolo.utils.warnings import colored_warning
 
 if t.TYPE_CHECKING:  # pragma: no cover
     from piccolo.columns.base import ColumnMeta
+    from piccolo.query.operators.json import (
+        GetChildElement,
+        GetElementFromPath,
+    )
     from piccolo.table import Table
 
 
@@ -2319,6 +2323,76 @@ class JSON(Column):
         else:
             return "JSON"
 
+    ###########################################################################
+
+    def arrow(self, key: t.Union[str, int, QueryString]) -> GetChildElement:
+        """
+        Allows a child element of the JSON structure to be returned - for
+        example::
+
+            >>> await RecordingStudio.select(
+            ...     RecordingStudio.facilities.arrow("restaurant")
+            ... )
+
+        """
+        from piccolo.query.operators.json import GetChildElement
+
+        alias = self._alias or self._meta.get_default_alias()
+        return GetChildElement(identifier=self, key=key, alias=alias)
+
+    def __getitem__(
+        self, value: t.Union[str, int, QueryString]
+    ) -> GetChildElement:
+        """
+        A shortcut for the ``arrow`` method, used for retrieving a child
+        element.
+
+        For example:
+
+        .. code-block:: python
+
+            >>> await RecordingStudio.select(
+            ...     RecordingStudio.facilities["restaurant"]
+            ... )
+
+        """
+        return self.arrow(key=value)
+
+    def from_path(
+        self,
+        path: t.List[t.Union[str, int]],
+    ) -> GetElementFromPath:
+        """
+        Allows an element of the JSON structure to be returned, which can be
+        arbitrarily deep. For example::
+
+            >>> await RecordingStudio.select(
+            ...     RecordingStudio.facilities.from_path([
+            ...         "technician",
+            ...         0,
+            ...         "first_name"
+            ...     ])
+            ... )
+
+        It's the same as calling ``arrow`` multiple times, but is more
+        efficient / convenient if extracting highly nested data::
+
+            >>> await RecordingStudio.select(
+            ...     RecordingStudio.facilities.arrow(
+            ...         "technician"
+            ...     ).arrow(
+            ...         0
+            ...     ).arrow(
+            ...         "first_name"
+            ...     )
+            ... )
+
+        """
+        from piccolo.query.operators.json import GetElementFromPath
+
+        alias = self._alias or self._meta.get_default_alias()
+        return GetElementFromPath(identifier=self, path=path, alias=alias)
+
     ###########################################################################
     # Descriptors
 
@@ -2337,10 +2411,10 @@ class JSON(Column):
 
 class JSONB(JSON):
     """
-    Used for storing JSON strings - Postgres only. The data is stored in a
-    binary format, and can be queried. Insertion can be slower (as it needs to
-    be converted to the binary format). The benefits of JSONB generally
-    outweigh the downsides.
+    Used for storing JSON strings - Postgres / CochroachDB only. The data is
+    stored in a binary format, and can be queried more efficiently. Insertion
+    can be slower (as it needs to be converted to the binary format). The
+    benefits of JSONB generally outweigh the downsides.
 
     :param default:
         Either a JSON string can be provided, or a Python ``dict`` or ``list``
@@ -2352,41 +2426,6 @@ class JSONB(JSON):
     def column_type(self):
         return "JSONB"  # Must be defined, we override column_type() in JSON()
 
-    def arrow(self, key: str) -> JSONB:
-        """
-        Allows part of the JSON structure to be returned - for example,
-        for {"a": 1}, and a key value of "a", then 1 will be returned.
-        """
-        instance = t.cast(JSONB, self.copy())
-        instance.json_operator = f"-> '{key}'"
-        return instance
-
-    def get_select_string(
-        self, engine_type: str, with_alias: bool = True
-    ) -> QueryString:
-        select_string = self._meta.get_full_name(with_alias=False)
-
-        if self.json_operator is not None:
-            select_string += f" {self.json_operator}"
-
-        if with_alias:
-            alias = self._alias or self._meta.get_default_alias()
-            select_string += f' AS "{alias}"'
-
-        return QueryString(select_string)
-
-    def eq(self, value) -> Where:
-        """
-        See ``Boolean.eq`` for more details.
-        """
-        return self.__eq__(value)
-
-    def ne(self, value) -> Where:
-        """
-        See ``Boolean.ne`` for more details.
-        """
-        return self.__ne__(value)
-
     ###########################################################################
     # Descriptors
 

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo/query/base.py

@@ -6,6 +6,7 @@ from time import time
 from piccolo.columns.column_types import JSON, JSONB
 from piccolo.custom_types import QueryResponseType, TableInstance
 from piccolo.query.mixins import ColumnsDelegate
+from piccolo.query.operators.json import JSONQueryString
 from piccolo.querystring import QueryString
 from piccolo.utils.encoding import load_json
 from piccolo.utils.objects import make_nested_object
@@ -65,16 +66,20 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
                 self, "columns_delegate", None
             )
 
+            json_column_names: t.List[str] = []
+
             if columns_delegate is not None:
-                json_columns = [
-                    i
-                    for i in columns_delegate.selected_columns
-                    if isinstance(i, (JSON, JSONB))
-                ]
+                json_columns: t.List[t.Union[JSON, JSONB]] = []
+
+                for column in columns_delegate.selected_columns:
+                    if isinstance(column, (JSON, JSONB)):
+                        json_columns.append(column)
+                    elif isinstance(column, JSONQueryString):
+                        if alias := column._alias:
+                            json_column_names.append(alias)
             else:
                 json_columns = self.table._meta.json_columns
 
-            json_column_names = []
             for column in json_columns:
                 if column._alias is not None:
                     json_column_names.append(column._alias)

piccolo-1.22.0/piccolo/query/operators/json.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import typing as t
+
+from piccolo.querystring import QueryString
+from piccolo.utils.encoding import dump_json
+
+if t.TYPE_CHECKING:
+    from piccolo.columns.column_types import JSON
+
+
+class JSONQueryString(QueryString):
+
+    def clean_value(self, value: t.Any):
+        if not isinstance(value, (str, QueryString)):
+            value = dump_json(value)
+        return value
+
+    def __eq__(self, value) -> QueryString:  # type: ignore[override]
+        value = self.clean_value(value)
+        return QueryString("{} = {}", self, value)
+
+    def __ne__(self, value) -> QueryString:  # type: ignore[override]
+        value = self.clean_value(value)
+        return QueryString("{} != {}", self, value)
+
+    def eq(self, value) -> QueryString:
+        return self.__eq__(value)
+
+    def ne(self, value) -> QueryString:
+        return self.__ne__(value)
+
+
+class GetChildElement(JSONQueryString):
+    """
+    Allows you to get a child element from a JSON object.
+
+    You can access this via the ``arrow`` function on ``JSON`` and ``JSONB``
+    columns.
+
+    """
+
+    def __init__(
+        self,
+        identifier: t.Union[JSON, QueryString],
+        key: t.Union[str, int, QueryString],
+        alias: t.Optional[str] = None,
+    ):
+        if isinstance(key, int):
+            # asyncpg only accepts integer keys if we explicitly mark it as an
+            # int.
+            key = QueryString("{}::int", key)
+
+        super().__init__("{} -> {}", identifier, key, alias=alias)
+
+    def arrow(self, key: t.Union[str, int, QueryString]) -> GetChildElement:
+        """
+        This allows you to drill multiple levels deep into a JSON object if
+        needed.
+
+        For example::
+
+            >>> await RecordingStudio.select(
+            ...     RecordingStudio.name,
+            ...     RecordingStudio.facilities.arrow(
+            ...         "instruments"
+            ...     ).arrow(
+            ...         "drum_kits"
+            ...     ).as_alias("drum_kits")
+            ... ).output(load_json=True)
+            [
+                {'name': 'Abbey Road', 'drum_kits': 2},
+                {'name': 'Electric Lady', 'drum_kits': 3}
+            ]
+
+        """
+        return GetChildElement(identifier=self, key=key, alias=self._alias)
+
+    def __getitem__(
+        self, value: t.Union[str, int, QueryString]
+    ) -> GetChildElement:
+        return GetChildElement(identifier=self, key=value, alias=self._alias)
+
+
+class GetElementFromPath(JSONQueryString):
+    """
+    Allows you to retrieve an element from a JSON object by specifying a path.
+    It can be several levels deep.
+
+    You can access this via the ``from_path`` function on ``JSON`` and
+    ``JSONB`` columns.
+
+    """
+
+    def __init__(
+        self,
+        identifier: t.Union[JSON, QueryString],
+        path: t.List[t.Union[str, int]],
+        alias: t.Optional[str] = None,
+    ):
+        """
+        :param path:
+            For example: ``["technician", 0, "name"]``.
+
+        """
+        super().__init__(
+            "{} #> {}",
+            identifier,
+            [str(i) if isinstance(i, int) else i for i in path],
+            alias=alias,
+        )

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo/querystring.py

@@ -259,10 +259,22 @@ class QueryString(Selectable):
     # Basic logic
 
     def __eq__(self, value) -> QueryString:  # type: ignore[override]
-        return QueryString("{} = {}", self, value)
+        if value is None:
+            return QueryString("{} IS NULL", self)
+        else:
+            return QueryString("{} = {}", self, value)
 
     def __ne__(self, value) -> QueryString:  # type: ignore[override]
-        return QueryString("{} != {}", self, value)
+        if value is None:
+            return QueryString("{} IS NOT NULL", self, value)
+        else:
+            return QueryString("{} != {}", self, value)
+
+    def eq(self, value) -> QueryString:
+        return self.__eq__(value)
+
+    def ne(self, value) -> QueryString:
+        return self.__ne__(value)
 
     def __add__(self, value) -> QueryString:
         return QueryString("{} + {}", self, value)

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo/table_reflection.py

@@ -8,6 +8,8 @@ import typing as t
 from dataclasses import dataclass
 
 from piccolo.apps.schema.commands.generate import get_output_schema
+from piccolo.engine import engine_finder
+from piccolo.engine.base import Engine
 from piccolo.table import Table
 
 
@@ -78,9 +80,16 @@ class TableStorage(metaclass=Singleton):
     works with Postgres.
     """
 
-    def __init__(self):
+    def __init__(self, engine: t.Optional[Engine] = None):
+        """
+        :param engine:
+            Which engine to use to make the database queries. If not specified,
+            we try importing an engine from ``piccolo_conf.py``.
+
+        """
+        self.engine = engine or engine_finder()
         self.tables = ImmutableDict()
-        self._schema_tables = {}
+        self._schema_tables: t.Dict[str, t.List[str]] = {}
 
     async def reflect(
         self,
@@ -120,10 +129,13 @@ class TableStorage(metaclass=Singleton):
         exclude_list = self._to_list(exclude)
 
         if keep_existing:
-            exclude += self._schema_tables.get(schema_name, [])
+            exclude_list += self._schema_tables.get(schema_name, [])
 
         output_schema = await get_output_schema(
-            schema_name=schema_name, include=include_list, exclude=exclude_list
+            schema_name=schema_name,
+            include=include_list,
+            exclude=exclude_list,
+            engine=self.engine,
         )
         add_tables = [
             self._add_table(schema_name=schema_name, table=table)
@@ -177,7 +189,7 @@ class TableStorage(metaclass=Singleton):
 
     def _add_to_schema_tables(self, schema_name: str, table_name: str) -> None:
         """
-        We keep record of schemas and their tables for easy use. This method
+        We keep a record of schemas and their tables for easy use. This method
         adds a table to its schema.
 
         """

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piccolo
-Version: 1.21.0
+Version: 1.22.0
 Summary: A fast, user friendly ORM and query builder which supports asyncio.
 Home-page: https://github.com/piccolo-orm/piccolo
 Author: Daniel Townsend
@@ -9,44 +9,28 @@ License: MIT
 Project-URL: Documentation, https://piccolo-orm.readthedocs.io/en/latest/index.html
 Project-URL: Source, https://github.com/piccolo-orm/piccolo
 Project-URL: Tracker, https://github.com/piccolo-orm/piccolo/issues
+Platform: UNKNOWN
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Framework :: AsyncIO
 Classifier: Typing :: Typed
 Classifier: Topic :: Database
-Requires-Python: >=3.8.0
+Requires-Python: >=3.9.0
 Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: black
-Requires-Dist: colorama>=0.4.0
-Requires-Dist: Jinja2>=2.11.0
-Requires-Dist: targ>=0.3.7
-Requires-Dist: inflection>=0.5.1
-Requires-Dist: typing-extensions>=4.3.0
-Requires-Dist: pydantic[email]==2.*
 Provides-Extra: orjson
-Requires-Dist: orjson>=3.5.1; extra == "orjson"
 Provides-Extra: playground
-Requires-Dist: ipython; extra == "playground"
 Provides-Extra: postgres
-Requires-Dist: asyncpg>=0.21.0; extra == "postgres"
 Provides-Extra: sqlite
-Requires-Dist: aiosqlite>=0.16.0; extra == "sqlite"
 Provides-Extra: uvloop
-Requires-Dist: uvloop>=0.12.0; sys_platform != "win32" and extra == "uvloop"
 Provides-Extra: all
-Requires-Dist: orjson>=3.5.1; extra == "all"
-Requires-Dist: ipython; extra == "all"
-Requires-Dist: asyncpg>=0.21.0; extra == "all"
-Requires-Dist: aiosqlite>=0.16.0; extra == "all"
-Requires-Dist: uvloop>=0.12.0; sys_platform != "win32" and extra == "all"
+License-File: LICENSE
 
 ![Logo](https://raw.githubusercontent.com/piccolo-orm/piccolo/master/docs/logo_hero.png "Piccolo Logo")
 
@@ -155,3 +139,5 @@ We have a handy page which shows the equivalent of [common Django queries in Pic
 Our documentation is on [Read the docs](https://piccolo-orm.readthedocs.io/en/latest/piccolo/getting_started/index.html).
 
 We also have some great [tutorial videos on YouTube](https://www.youtube.com/channel/UCE7x5nm1Iy9KDfXPNrNQ5lA).
+
+

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo.egg-info/SOURCES.txt

@@ -182,6 +182,8 @@ piccolo/query/methods/refresh.py
 piccolo/query/methods/select.py
 piccolo/query/methods/table_exists.py
 piccolo/query/methods/update.py
+piccolo/query/operators/__init__.py
+piccolo/query/operators/json.py
 piccolo/testing/__init__.py
 piccolo/testing/model_builder.py
 piccolo/testing/random_builder.py
@@ -203,8 +205,6 @@ piccolo/utils/graphlib/__init__.py
 piccolo/utils/graphlib/_graphlib.py
 profiling/__init__.py
 profiling/run_profile.py
-tests/test_main.py
-tests/test_schema.py
 tests/apps/__init__.py
 tests/apps/app/__init__.py
 tests/apps/app/commands/__init__.py
@@ -325,6 +325,8 @@ tests/query/functions/test_type_conversion.py
 tests/query/mixins/__init__.py
 tests/query/mixins/test_columns_delegate.py
 tests/query/mixins/test_order_by_delegate.py
+tests/query/operators/__init__.py
+tests/query/operators/test_json.py
 tests/table/__init__.py
 tests/table/test_all_columns.py
 tests/table/test_alter.py

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 piccolo = piccolo.main:main
+

{piccolo-1.21.0 → piccolo-1.22.0}/piccolo.egg-info/requires.txt

@@ -9,7 +9,7 @@ pydantic[email]==2.*
 [all]
 orjson>=3.5.1
 ipython
-asyncpg>=0.21.0
+asyncpg>=0.30.0
 aiosqlite>=0.16.0
 
 [all:sys_platform != "win32"]
@@ -22,7 +22,7 @@ orjson>=3.5.1
 ipython
 
 [postgres]
-asyncpg>=0.21.0
+asyncpg>=0.30.0
 
 [sqlite]
 aiosqlite>=0.16.0

{piccolo-1.21.0 → piccolo-1.22.0}/setup.py

@@ -58,7 +58,7 @@ setup(
     long_description_content_type="text/markdown",
     author="Daniel Townsend",
     author_email="dan@dantownsend.co.uk",
-    python_requires=">=3.8.0",
+    python_requires=">=3.9.0",
     url="https://github.com/piccolo-orm/piccolo",
     packages=find_packages(exclude=("tests",)),
     package_data={
@@ -84,11 +84,11 @@ setup(
         "License :: OSI Approved :: MIT License",
         "Programming Language :: Python",
         "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
         "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
         "Programming Language :: Python :: Implementation :: CPython",
         "Framework :: AsyncIO",
         "Typing :: Typed",