update docs, cleaning

docs_src/fastapi/mypy/docs001.py

@@ -0,0 +1,17 @@
+import databases
+import sqlalchemy
+
+import ormar
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Course(ormar.Model):
+    class Meta:
+        database = database
+        metadata = metadata
+
+    id = ormar.Integer(primary_key=True)
+    name = ormar.String(max_length=100)
+    completed = ormar.Boolean(default=False)

docs_src/models/docs007.py

@@ -18,5 +18,6 @@ class Course(ormar.Model):
 
 
 course = Course(name="Painting for dummies", completed=False)
-await course.save()  # type: ignore
-await Course.objects.create(name="Painting for dummies", completed=False)  # type: ignore
+await course.save()
+
+await Course.objects.create(name="Painting for dummies", completed=False)

docs_src/models/docs010.py

@@ -1,5 +1,3 @@
-from typing import Optional, Union, List
-
 import databases
 import sqlalchemy
 
@@ -27,6 +25,4 @@ class Artist(ormar.Model):
     first_name: str = ormar.String(name="fname", max_length=100)
     last_name: str = ormar.String(name="lname", max_length=100)
     born_year: int = ormar.Integer(name="year")
-    children: Optional[Union[Child, List[Child]]] = ormar.ManyToMany(
-        Child, through=ArtistChildren
-    )
+    children = ormar.ManyToMany(Child, through=ArtistChildren)

docs_src/models/docs011.py

@@ -0,0 +1,19 @@
+import databases
+import sqlalchemy
+
+import ormar
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Course(ormar.Model):
+    class Meta:
+        database = database
+        metadata = metadata
+
+    id: ormar.Integer(primary_key=True)
+    name: ormar.String(max_length=100)
+    completed: ormar.Boolean(default=False)
+
+c1 = Course()

docs_src/models/docs012.py

@@ -0,0 +1,17 @@
+import databases
+import sqlalchemy
+
+import ormar
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Course(ormar.Model):
+    class Meta:
+        database = database
+        metadata = metadata
+
+    id = ormar.Integer(primary_key=True)
+    name = ormar.String(max_length=100)
+    completed = ormar.Boolean(default=False)

docs_src/models/docs013.py

@@ -0,0 +1,38 @@
+from typing import Optional
+
+import databases
+import sqlalchemy
+
+import ormar
+
+database = databases.Database("sqlite:///test.db", force_rollback=True)
+metadata = sqlalchemy.MetaData()
+
+
+# note that you do not have to subclass ModelMeta,
+# it's useful for type hints and code completion
+class MainMeta(ormar.ModelMeta):
+    metadata = metadata
+    database = database
+
+
+class Artist(ormar.Model):
+    class Meta(MainMeta):
+        # note that tablename is optional
+        # if not provided ormar will user class.__name__.lower()+'s'
+        # -> artists in this example
+        pass
+
+    id: int = ormar.Integer(primary_key=True)
+    first_name: str = ormar.String(max_length=100)
+    last_name: str = ormar.String(max_length=100)
+    born_year: int = ormar.Integer(name="year")
+
+
+class Album(ormar.Model):
+    class Meta(MainMeta):
+        pass
+
+    id: int = ormar.Integer(primary_key=True)
+    name: str = ormar.String(max_length=100)
+    artist: Optional[Artist] = ormar.ForeignKey(Artist)

docs_src/queries/docs002.py

@@ -0,0 +1,28 @@
+import databases
+import ormar
+import sqlalchemy
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Book(ormar.Model):
+    class Meta:
+        tablename = "books"
+        metadata = metadata
+        database = database
+
+    id: int = ormar.Integer(primary_key=True)
+    title: str = ormar.String(max_length=200)
+    author: str = ormar.String(max_length=100)
+    genre: str = ormar.String(max_length=100, default='Fiction',
+                              choices=['Fiction', 'Adventure', 'Historic', 'Fantasy'])
+
+
+await Book.objects.create(title='Tom Sawyer', author="Twain, Mark", genre='Adventure')
+await Book.objects.create(title='War and Peace', author="Tolstoy, Leo", genre='Fiction')
+await Book.objects.create(title='Anna Karenina', author="Tolstoy, Leo", genre='Fiction')
+
+await Book.objects.update(each=True, genre='Fiction')
+all_books = await Book.objects.filter(genre='Fiction').all()
+assert len(all_books) == 3

docs_src/queries/docs003.py

@@ -0,0 +1,32 @@
+import databases
+import ormar
+import sqlalchemy
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Book(ormar.Model):
+    class Meta:
+        tablename = "books"
+        metadata = metadata
+        database = database
+
+    id: int = ormar.Integer(primary_key=True)
+    title: str = ormar.String(max_length=200)
+    author: str = ormar.String(max_length=100)
+    genre: str = ormar.String(max_length=100, default='Fiction',
+                              choices=['Fiction', 'Adventure', 'Historic', 'Fantasy'])
+
+
+await Book.objects.create(title='Tom Sawyer', author="Twain, Mark", genre='Adventure')
+await Book.objects.create(title='War and Peace', author="Tolstoy, Leo", genre='Fiction')
+await Book.objects.create(title='Anna Karenina', author="Tolstoy, Leo", genre='Fiction')
+
+# if not exist the instance will be persisted in db
+vol2 = await Book.objects.update_or_create(title="Volume II", author='Anonymous', genre='Fiction')
+assert await Book.objects.count() == 1
+
+# if pk or pkname passed in kwargs (like id here) the object will be updated
+assert await Book.objects.update_or_create(id=vol2.id, genre='Historic')
+assert await Book.objects.count() == 1

docs_src/queries/docs004.py

@@ -0,0 +1,30 @@
+import databases
+import ormar
+import sqlalchemy
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class ToDo(ormar.Model):
+    class Meta:
+        tablename = "todos"
+        metadata = metadata
+        database = database
+
+    id: int = ormar.Integer(primary_key=True)
+    text: str = ormar.String(max_length=500)
+    completed = ormar.Boolean(default=False)
+
+
+# create multiple instances at once with bulk_create
+await ToDo.objects.bulk_create(
+    [
+        ToDo(text="Buy the groceries."),
+        ToDo(text="Call Mum.", completed=True),
+        ToDo(text="Send invoices.", completed=True),
+    ]
+)
+
+todoes = await ToDo.objects.all()
+assert len(todoes) == 3

docs_src/queries/docs005.py

@@ -0,0 +1,30 @@
+import databases
+import ormar
+import sqlalchemy
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Book(ormar.Model):
+    class Meta:
+        tablename = "books"
+        metadata = metadata
+        database = database
+
+    id: int = ormar.Integer(primary_key=True)
+    title: str = ormar.String(max_length=200)
+    author: str = ormar.String(max_length=100)
+    genre: str = ormar.String(max_length=100, default='Fiction',
+                              choices=['Fiction', 'Adventure', 'Historic', 'Fantasy'])
+
+
+await Book.objects.create(title='Tom Sawyer', author="Twain, Mark", genre='Adventure')
+await Book.objects.create(title='War and Peace in Space', author="Tolstoy, Leo", genre='Fantasy')
+await Book.objects.create(title='Anna Karenina', author="Tolstoy, Leo", genre='Fiction')
+
+# delete accepts kwargs that will be used in filter
+# acting in same way as queryset.filter(**kwargs).delete()
+await Book.objects.delete(genre='Fantasy')  # delete all fantasy books
+all_books = await Book.objects.all()
+assert len(all_books) == 2

docs_src/queries/docs006.py

@@ -0,0 +1,67 @@
+import databases
+import sqlalchemy
+
+import ormar
+from tests.settings import DATABASE_URL
+
+database = databases.Database(DATABASE_URL, force_rollback=True)
+metadata = sqlalchemy.MetaData()
+
+
+class Company(ormar.Model):
+    class Meta:
+        tablename = "companies"
+        metadata = metadata
+        database = database
+
+    id: int = ormar.Integer(primary_key=True)
+    name: str = ormar.String(max_length=100)
+    founded: int = ormar.Integer(nullable=True)
+
+
+class Car(ormar.Model):
+    class Meta:
+        tablename = "cars"
+        metadata = metadata
+        database = database
+
+    id: int = ormar.Integer(primary_key=True)
+    manufacturer = ormar.ForeignKey(Company)
+    name: str = ormar.String(max_length=100)
+    year: int = ormar.Integer(nullable=True)
+    gearbox_type: str = ormar.String(max_length=20, nullable=True)
+    gears: int = ormar.Integer(nullable=True)
+    aircon_type: str = ormar.String(max_length=20, nullable=True)
+
+
+# build some sample data
+toyota = await Company.objects.create(name="Toyota", founded=1937)
+await Car.objects.create(manufacturer=toyota, name="Corolla", year=2020, gearbox_type='Manual', gears=5,
+                         aircon_type='Manual')
+await Car.objects.create(manufacturer=toyota, name="Yaris", year=2019, gearbox_type='Manual', gears=5,
+                         aircon_type='Manual')
+await Car.objects.create(manufacturer=toyota, name="Supreme", year=2020, gearbox_type='Auto', gears=6,
+                         aircon_type='Auto')
+
+# select manufacturer but only name - to include related models use notation {model_name}__{column}
+all_cars = await Car.objects.select_related('manufacturer').fields(['id', 'name', 'company__name']).all()
+for car in all_cars:
+    # excluded columns will yield None
+    assert all(getattr(car, x) is None for x in ['year', 'gearbox_type', 'gears', 'aircon_type'])
+    # included column on related models will be available, pk column is always included
+    # even if you do not include it in fields list
+    assert car.manufacturer.name == 'Toyota'
+    # also in the nested related models - you cannot exclude pk - it's always auto added
+    assert car.manufacturer.founded is None
+
+# fields() can be called several times, building up the columns to select
+# models selected in select_related but with no columns in fields list implies all fields
+all_cars = await Car.objects.select_related('manufacturer').fields('id').fields(
+    ['name']).all()
+# all fiels from company model are selected
+assert all_cars[0].manufacturer.name == 'Toyota'
+assert all_cars[0].manufacturer.founded == 1937
+
+# cannot exclude mandatory model columns - company__name in this example
+await Car.objects.select_related('manufacturer').fields(['id', 'name', 'company__founded']).all()
+# will raise pydantic ValidationError as company.name is required