added to_dict (piccolo-orm#201)

* added `to_dict`

* add test for `to_dict`

* support aliases in `to_dict`

* add docs for `to_dict`

* fix typo in docstring

* allow a subset of columns to be specified

* update docs

Author: dantownsend

docs/src/piccolo/query_types/objects.rst

@@ -138,6 +138,29 @@ Complex where clauses are supported, but only within reason. For example:
         defaults={'popularity': 100}
     ).run_sync()
 
+to_dict
+-------
+
+If you need to convert an object into a dictionary, you can do so using the
+``to_dict`` method.
+
+.. code-block:: python
+
+    band = Band.objects().first().run_sync()
+
+    >>> band.to_dict()
+    {'id': 1, 'name': 'Pythonistas', 'manager': 1, 'popularity': 1000}
+
+If you only want a subset of the columns, or want to use aliases for some of
+the columns:
+
+.. code-block:: python
+
+    band = Band.objects().first().run_sync()
+
+    >>> band.to_dict(Band.id, Band.name.as_alias('title'))
+    {'id': 1, 'title': 'Pythonistas'}
+
 
 Query clauses
 -------------

piccolo/table.py

@@ -407,6 +407,41 @@ def get_related(self, foreign_key: t.Union[ForeignKey, str]) -> Objects:
             .first()
         )
 
+    def to_dict(self, *columns: Column) -> t.Dict[str, t.Any]:
+        """
+        A convenience method which returns a dictionary, mapping column names
+        to values for this table instance.
+
+        .. code-block::
+
+            instance = await Manager.objects().get(
+                Manager.name == 'Guido'
+            ).run()
+
+            >>> instance.to_dict()
+            {'id': 1, 'name': 'Guido'}
+
+        If the columns argument is provided, only those columns are included in
+        the output. It also works with column aliases.
+
+        .. code-block::
+
+            >>> instance.to_dict(Manager.id, Manager.name.as_alias('title'))
+            {'id': 1, 'title': 'Guido'}
+
+        """
+        alias_names = {
+            column._meta.name: getattr(column, "alias", None)
+            for column in columns
+        }
+
+        output = {}
+        for column in columns or self._meta.columns:
+            output[
+                alias_names.get(column._meta.name) or column._meta.name
+            ] = getattr(self, column._meta.name)
+        return output
+
     def __setitem__(self, key: str, value: t.Any):
         setattr(self, key, value)
 

tests/table/instance/test_to_dict.py

@@ -0,0 +1,36 @@
+from tests.base import DBTestCase
+from tests.example_app.tables import Manager
+
+
+class TestToDict(DBTestCase):
+    def test_to_dict(self):
+        """
+        Make sure that `to_dict` works correctly.
+        """
+        self.insert_row()
+
+        instance = Manager.objects().first().run_sync()
+        dictionary = instance.to_dict()
+        self.assertEqual(dictionary, {"id": 1, "name": "Guido"})
+
+    def test_filter_rows(self):
+        """
+        Make sure that `to_dict` works correctly with a subset of columns.
+        """
+        self.insert_row()
+
+        instance = Manager.objects().first().run_sync()
+        dictionary = instance.to_dict(Manager.name)
+        self.assertEqual(dictionary, {"name": "Guido"})
+
+    def test_to_dict_aliases(self):
+        """
+        Make sure that `to_dict` works correctly with aliases.
+        """
+        self.insert_row()
+
+        instance = Manager.objects().first().run_sync()
+        dictionary = instance.to_dict(
+            Manager.id, Manager.name.as_alias("title")
+        )
+        self.assertEqual(dictionary, {"id": 1, "title": "Guido"})