piccolo 1.19.1__py3-none-any.whl → 1.20.0__py3-none-any.whl

piccolo/__init__.py

@@ -1 +1 @@
-__VERSION__ = "1.19.1"
+__VERSION__ = "1.20.0"

piccolo/query/methods/objects.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import typing as t
 
-from piccolo.columns.column_types import ForeignKey
+from piccolo.columns.column_types import ForeignKey, ReferencedTable
 from piccolo.columns.combination import And, Where
 from piccolo.custom_types import Combinable, TableInstance
 from piccolo.engine.base import BaseBatch
@@ -231,6 +231,63 @@ class UpdateSelf:
         return run_sync(self.run(*args, **kwargs))
 
 
+class GetRelated(t.Generic[ReferencedTable]):
+
+    def __init__(self, row: Table, foreign_key: ForeignKey[ReferencedTable]):
+        self.row = row
+        self.foreign_key = foreign_key
+
+    async def run(
+        self,
+        node: t.Optional[str] = None,
+        in_pool: bool = True,
+    ) -> t.Optional[ReferencedTable]:
+        if not self.row._exists_in_db:
+            raise ValueError("The object doesn't exist in the database.")
+
+        root_table = self.row.__class__
+
+        data = (
+            await root_table.select(
+                *[
+                    i.as_alias(i._meta.name)
+                    for i in self.foreign_key.all_columns()
+                ]
+            )
+            .where(
+                root_table._meta.primary_key
+                == getattr(self.row, root_table._meta.primary_key._meta.name)
+            )
+            .first()
+            .run(node=node, in_pool=in_pool)
+        )
+
+        # Make sure that some values were returned:
+        if data is None or not any(data.values()):
+            return None
+
+        references = t.cast(
+            t.Type[ReferencedTable],
+            self.foreign_key._foreign_key_meta.resolved_references,
+        )
+
+        referenced_object = references(**data)
+        referenced_object._exists_in_db = True
+        return referenced_object
+
+    def __await__(
+        self,
+    ) -> t.Generator[None, None, t.Optional[ReferencedTable]]:
+        """
+        If the user doesn't explicity call .run(), proxy to it as a
+        convenience.
+        """
+        return self.run().__await__()
+
+    def run_sync(self, *args, **kwargs) -> t.Optional[ReferencedTable]:
+        return run_sync(self.run(*args, **kwargs))
+
+
 ###############################################################################
 
 

piccolo/table.py

@@ -46,7 +46,7 @@ from piccolo.query import (
 )
 from piccolo.query.methods.create_index import CreateIndex
 from piccolo.query.methods.indexes import Indexes
-from piccolo.query.methods.objects import First, UpdateSelf
+from piccolo.query.methods.objects import GetRelated, UpdateSelf
 from piccolo.query.methods.refresh import Refresh
 from piccolo.querystring import QueryString
 from piccolo.utils import _camel_to_snake
@@ -612,14 +612,14 @@ class Table(metaclass=TableMetaclass):
     @t.overload
     def get_related(
         self, foreign_key: ForeignKey[ReferencedTable]
-    ) -> First[ReferencedTable]: ...
+    ) -> GetRelated[ReferencedTable]: ...
 
     @t.overload
-    def get_related(self, foreign_key: str) -> First[Table]: ...
+    def get_related(self, foreign_key: str) -> GetRelated[Table]: ...
 
     def get_related(
         self, foreign_key: t.Union[str, ForeignKey[ReferencedTable]]
-    ) -> t.Union[First[Table], First[ReferencedTable]]:
+    ) -> GetRelated[ReferencedTable]:
         """
         Used to fetch a ``Table`` instance, for the target of a foreign key.
 
@@ -630,8 +630,8 @@ class Table(metaclass=TableMetaclass):
             >>> print(manager.name)
             'Guido'
 
-        It can only follow foreign keys one level currently.
-        i.e. ``Band.manager``, but not ``Band.manager.x.y.z``.
+        It can only follow foreign keys multiple levels deep. For example,
+        ``Concert.band_1.manager``.
 
         """
         if isinstance(foreign_key, str):
@@ -645,18 +645,7 @@ class Table(metaclass=TableMetaclass):
                 "ForeignKey column."
             )
 
-        column_name = foreign_key._meta.name
-
-        references = foreign_key._foreign_key_meta.resolved_references
-
-        return (
-            references.objects()
-            .where(
-                foreign_key._foreign_key_meta.resolved_target_column
-                == getattr(self, column_name)
-            )
-            .first()
-        )
+        return GetRelated(foreign_key=foreign_key, row=self)
 
     def get_m2m(self, m2m: M2M) -> M2MGetRelated:
         """

{piccolo-1.19.1.dist-info → piccolo-1.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piccolo
-Version: 1.19.1
+Version: 1.20.0
 Summary: A fast, user friendly ORM and query builder which supports asyncio.
 Home-page: https://github.com/piccolo-orm/piccolo
 Author: Daniel Townsend

{piccolo-1.19.1.dist-info → piccolo-1.20.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-piccolo/__init__.py,sha256=JP09HcvsWvSb_xYAg-Jfrxz8qqh31rbqbIN3dcneflw,23
+piccolo/__init__.py,sha256=9C2I7AvMRyI69S3jlrRv3hQ4kYCgUZBXUC_VSvY3Dv0,23
 piccolo/custom_types.py,sha256=7HMQAze-5mieNLfbQ5QgbRQgR2abR7ol0qehv2SqROY,604
 piccolo/main.py,sha256=1VsFV67FWTUikPTysp64Fmgd9QBVa_9wcwKfwj2UCEA,5117
 piccolo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 piccolo/querystring.py,sha256=yZdURtiVSlxkkEVJoFKAmL2OfNxrUr8xfsfuBBB7IuY,9662
 piccolo/schema.py,sha256=qNNy4tG_HqnXR9t3hHMgYXtGxHabwQAhUpc6RKLJ_gE,7960
-piccolo/table.py,sha256=rwLkom0-4ahOTVon9JDoZ92cp5d3nuwo24ES8attxCM,50896
+piccolo/table.py,sha256=UvEbagMYRkTbyFHTUwUshZlL_dC4UKDP7vUOwF8OXmg,50593
 piccolo/table_reflection.py,sha256=jrN1nHerDJ4tU09GtNN3hz7ap-7rXnSUjljFO6LB2H0,7094
 piccolo/apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 piccolo/apps/app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -166,7 +166,7 @@ piccolo/query/methods/drop_index.py,sha256=5x3vHpoOmQ1SMhj6L7snKXX6M9l9j1E1PFSO6
 piccolo/query/methods/exists.py,sha256=lTMjtrFPFygZmaPV3sfQKXc3K0sVqJ2S6PDc3fRK6YQ,1203
 piccolo/query/methods/indexes.py,sha256=J-QUqaBJwpgahskUH0Cu0Mq7zEKcfVAtDsUVIVX-C4c,943
 piccolo/query/methods/insert.py,sha256=ssLJ_wn08KnOwwr7t-VILyn1P4hrvM63CfPIcAJWT5k,4701
-piccolo/query/methods/objects.py,sha256=kWHSgnXFVYe-x6tIHstbZvZic6mQCCGES-L_2Icbg-I,13910
+piccolo/query/methods/objects.py,sha256=BfCOIbNMj7FWkmK5STaINkfDFmwzZvDZi60jCumjs1o,15627
 piccolo/query/methods/raw.py,sha256=wQWR8b-yA_Gr-5lqRMZe9BOAAMBAw8CqTx37qVYvM1A,987
 piccolo/query/methods/refresh.py,sha256=wg1zghKfwz-VmqK4uWa4GNMiDtK-skTqow591Hb3ONM,5854
 piccolo/query/methods/select.py,sha256=jNR7CsEPUarffYMsXytKm7iScrQ_nqpRX-5mTPrXfjg,22414
@@ -346,7 +346,7 @@ tests/table/test_update.py,sha256=Cqi0xX3kEuJ0k-x_emPGB3arXuGWZ9e3CJ3HPFnw9Zw,20
 tests/table/test_update_self.py,sha256=im6HcM-WLkEhZP0vTL42tYEJZyAZG6gDOxCnbikCBD4,907
 tests/table/instance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/table/instance/test_create.py,sha256=JD0l7L9dDK1FKPhUs6WC_B2bruPR1qQ8aIqXpEbfiUg,1105
-tests/table/instance/test_get_related.py,sha256=dAT89KHuO_XEMY6h0ngDHrXp_nJsMoSToTbH_IRclTE,1275
+tests/table/instance/test_get_related.py,sha256=eracFunh4Qlj5BEkI7OsrOyefRZM0rxrXnFX92VL1ZE,3285
 tests/table/instance/test_get_related_readable.py,sha256=QDMMZykxPsTWcsl8ZIZtmQVLwSGCw7QBilLepAAAnWg,4694
 tests/table/instance/test_instantiate.py,sha256=jvtaqSa_zN1lHQiykN4EnwitZqkWAbXle5IJtyhKuHY,958
 tests/table/instance/test_remove.py,sha256=Zv22ZZqot61rjCVWL1PHDf1oxELcBnmMXx1gsST6j80,648
@@ -368,9 +368,9 @@ tests/utils/test_sql_values.py,sha256=vzxRmy16FfLZPH-sAQexBvsF9MXB8n4smr14qoEOS5
 tests/utils/test_sync.py,sha256=9ytVo56y2vPQePvTeIi9lHIouEhWJbodl1TmzkGFrSo,799
 tests/utils/test_table_reflection.py,sha256=SIzuat-IpcVj1GCFyOWKShI8YkhdOPPFH7qVrvfyPNE,3794
 tests/utils/test_warnings.py,sha256=NvSC_cvJ6uZcwAGf1m-hLzETXCqprXELL8zg3TNLVMw,269
-piccolo-1.19.1.dist-info/LICENSE,sha256=zFIpi-16uIJ420UMIG75NU0JbDBykvrdnXcj5U_EYBI,1059
-piccolo-1.19.1.dist-info/METADATA,sha256=owDJXe8zA0Tiloy78LB-2NPyDCxfM7qfFWOeDnXGNO8,5178
-piccolo-1.19.1.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-piccolo-1.19.1.dist-info/entry_points.txt,sha256=SJPHET4Fi1bN5F3WqcKkv9SClK3_F1I7m4eQjk6AFh0,46
-piccolo-1.19.1.dist-info/top_level.txt,sha256=-SR74VGbk43VoPy1HH-mHm97yoGukLK87HE5kdBW6qM,24
-piccolo-1.19.1.dist-info/RECORD,,
+piccolo-1.20.0.dist-info/LICENSE,sha256=zFIpi-16uIJ420UMIG75NU0JbDBykvrdnXcj5U_EYBI,1059
+piccolo-1.20.0.dist-info/METADATA,sha256=xOURp1sxZOGQ4Q_cnDb9pYcV5XuMlDGEOZ89k9KC5f0,5178
+piccolo-1.20.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+piccolo-1.20.0.dist-info/entry_points.txt,sha256=SJPHET4Fi1bN5F3WqcKkv9SClK3_F1I7m4eQjk6AFh0,46
+piccolo-1.20.0.dist-info/top_level.txt,sha256=-SR74VGbk43VoPy1HH-mHm97yoGukLK87HE5kdBW6qM,24
+piccolo-1.20.0.dist-info/RECORD,,

tests/table/instance/test_get_related.py

@@ -1,42 +1,98 @@
 import typing as t
-from unittest import TestCase
 
-from tests.example_apps.music.tables import Band, Manager
+from piccolo.testing.test_case import AsyncTableTest
+from tests.example_apps.music.tables import Band, Concert, Manager, Venue
 
-TABLES = [Manager, Band]
 
+class TestGetRelated(AsyncTableTest):
+    tables = [Manager, Band, Concert, Venue]
 
-class TestGetRelated(TestCase):
-    def setUp(self):
-        for table in TABLES:
-            table.create_table().run_sync()
+    async def asyncSetUp(self):
+        await super().asyncSetUp()
 
-    def tearDown(self):
-        for table in reversed(TABLES):
-            table.alter().drop_table().run_sync()
+        # Setup two pairs of manager/band, so we can make sure the correct
+        # objects are returned.
 
-    def test_get_related(self) -> None:
+        self.manager = Manager(name="Guido")
+        await self.manager.save()
+
+        self.band = Band(
+            name="Pythonistas", manager=self.manager.id, popularity=100
+        )
+        await self.band.save()
+
+        self.manager_2 = Manager(name="Graydon")
+        await self.manager_2.save()
+
+        self.band_2 = Band(
+            name="Rustaceans", manager=self.manager_2.id, popularity=100
+        )
+        await self.band_2.save()
+
+    async def test_foreign_key(self) -> None:
         """
         Make sure you can get a related object from another object instance.
         """
-        manager = Manager(name="Guido")
-        manager.save().run_sync()
+        manager = await self.band.get_related(Band.manager)
+        assert manager is not None
+        self.assertTrue(manager.id == self.manager.id)
+
+        manager_2 = await self.band_2.get_related(Band.manager)
+        assert manager_2 is not None
+        self.assertTrue(manager_2.id == self.manager_2.id)
 
-        band = Band(name="Pythonistas", manager=manager.id, popularity=100)
-        band.save().run_sync()
+    async def test_non_foreign_key(self):
+        """
+        Make sure that non-ForeignKey raise an exception.
+        """
+        with self.assertRaises(ValueError):
+            self.band.get_related(Band.name)  # type: ignore
 
-        _manager = band.get_related(Band.manager).run_sync()
-        assert _manager is not None
-        self.assertTrue(_manager.name == "Guido")
+    async def test_string(self):
+        """
+        Make sure it also works using a string representation of a foreign key.
+        """
+        manager = t.cast(Manager, await self.band.get_related("manager"))
+        self.assertTrue(manager.id == self.manager.id)
 
-        # Test non-ForeignKey
+    async def test_invalid_string(self):
+        """
+        Make sure an exception is raised if the foreign key string is invalid.
+        """
         with self.assertRaises(ValueError):
-            band.get_related(Band.name)  # type: ignore
+            self.band.get_related("abc123")
 
-        # Make sure it also works using a string
-        _manager_2 = t.cast(Manager, band.get_related("manager").run_sync())
-        self.assertTrue(_manager_2.name == "Guido")
+    async def test_multiple_levels(self):
+        """
+        Make sure ``get_related`` works multiple levels deep.
+        """
+        concert = Concert(band_1=self.band, band_2=self.band_2)
+        await concert.save()
+
+        manager = await concert.get_related(Concert.band_1._.manager)
+        assert manager is not None
+        self.assertTrue(manager.id == self.manager.id)
+
+        manager_2 = await concert.get_related(Concert.band_2._.manager)
+        assert manager_2 is not None
+        self.assertTrue(manager_2.id == self.manager_2.id)
+
+    async def test_no_match(self):
+        """
+        If not related object exists, make sure ``None`` is returned.
+        """
+        concert = Concert(band_1=self.band, band_2=None)
+        await concert.save()
+
+        manager_2 = await concert.get_related(Concert.band_2._.manager)
+        assert manager_2 is None
+
+    async def test_not_in_db(self):
+        """
+        If the object we're calling ``get_related`` on doesn't exist in the
+        database, then make sure an error is raised.
+        """
+        concert = Concert(band_1=self.band, band_2=self.band_2)
 
-        # Test an invalid string
         with self.assertRaises(ValueError):
-            band.get_related("abc123")
+            await concert.get_related(Concert.band_1._.manager)