added create method (piccolo-orm#245)

* added create method piccolo-orm#238

* removed unnecessary comment

* updated Docs

Author: AliSayyah

docs/src/piccolo/query_types/objects.rst

@@ -57,6 +57,12 @@ Creating objects
     >>> band = Band(name="C-Sharps", popularity=100)
     >>> band.save().run_sync()
 
+This can also be done like this:
+
+.. code-block:: python
+
+    >>> band.objects().create(name="C-Sharps", popularity=100).run_sync()
+
 -------------------------------------------------------------------------------
 
 Updating objects

piccolo/query/methods/objects.py

@@ -82,6 +82,36 @@ def prefetch(self, *fk_columns) -> GetOrCreate:
         return self
 
 
+@dataclass
+class Create:
+    query: Objects
+    columns: t.Dict[str, t.Any]
+
+    async def run(self):
+        instance = self.query.table()
+
+        for column, value in self.columns.items():
+            if isinstance(column, str):
+                column = instance._meta.get_column_by_name(column)
+            setattr(instance, column._meta.name, value)
+
+        await instance.save().run()
+
+        instance._was_created = True
+
+        return instance
+
+    def __await__(self):
+        """
+        If the user doesn't explicity call .run(), proxy to it as a
+        convenience.
+        """
+        return self.run().__await__()
+
+    def run_sync(self):
+        return run_sync(self.run())
+
+
 @dataclass
 class Objects(Query):
     """
@@ -151,6 +181,9 @@ def get_or_create(
     ):
         return GetOrCreate(query=self, where=where, defaults=defaults)
 
+    def create(self, **columns: t.Any):
+        return Create(query=self, columns=columns)
+
     def order_by(self, *columns: Column, ascending=True) -> Objects:
         self.order_by_delegate.order_by(*columns, ascending=ascending)
         return self

tests/table/instance/test_create.py

@@ -0,0 +1,20 @@
+from unittest import TestCase
+
+from tests.example_apps.music.tables import Manager
+
+
+class TestCreate(TestCase):
+    def setUp(self):
+        Manager.create_table().run_sync()
+
+    def tearDown(self):
+        Manager.alter().drop_table().run_sync()
+
+    def test_create_new(self):
+        """
+        Make sure that creating a new instance works.
+        """
+        Manager.objects().create(name="Maz").run_sync()
+
+        names = [i["name"] for i in Manager.select(Manager.name).run_sync()]
+        self.assertTrue("Maz" in names)