documentation (#103)

encode · Sep 3, 2021 · ea9153a · ea9153a
1 parent 569585c
commit ea9153a
Show file tree

Hide file tree

Showing 10 changed files with 454 additions and 141 deletions.
diff --git a/README.md b/README.md
@@ -62,156 +62,21 @@ class Note(orm.Model):
     __tablename__ = "notes"
     __database__ = database
     __metadata__ = metadata
-
     id = orm.Integer(primary_key=True)
     text = orm.String(max_length=100)
     completed = orm.Boolean(default=False)
 
-# Create the database
+# Create the database and tables
 engine = sqlalchemy.create_engine(str(database.url))
 metadata.create_all(engine)
 
-# .create()
 await Note.objects.create(text="Buy the groceries.", completed=False)
-await Note.objects.create(text="Call Mum.", completed=True)
-await Note.objects.create(text="Send invoices.", completed=True)
-
-# .all()
-notes = await Note.objects.all()
-
-# .filter()
-notes = await Note.objects.filter(completed=True).all()
-
-# .exclude()
-notes = await Note.objects.exclude(completed=False).all()
 
-# exact, iexact, contains, icontains, lt, lte, gt, gte, in
-notes = await Note.objects.filter(text__icontains="mum").all()
-
-# .order_by()
-# order by ascending name and descending id
-notes = await Note.objects.order_by("name", "-id").all()
-
-# .get()
 note = await Note.objects.get(id=1)
-
-# .first()
-note = await Note.objects.filter(completed=True).first()
-
-# .update()
-await note.update(completed=True)
-
-# .delete()
-await note.delete()
-
-# 'pk' always refers to the primary key
-note = await Note.objects.get(pk=2)
-note.pk  # 2
-
+print(note)
+# Note(id=1, text="Buy the groceries.", completed=False)
 ```
 
-ORM supports loading and filtering across foreign keys...
-
-```python
-import databases
-import orm
-import sqlalchemy
-
-database = databases.Database("sqlite:///db.sqlite")
-metadata = sqlalchemy.MetaData()
-
-
-class Album(orm.Model):
-    __tablename__ = "album"
-    __metadata__ = metadata
-    __database__ = database
-
-    id = orm.Integer(primary_key=True)
-    name = orm.String(max_length=100)
-
-
-class Track(orm.Model):
-    __tablename__ = "track"
-    __metadata__ = metadata
-    __database__ = database
-
-    id = orm.Integer(primary_key=True)
-    album = orm.ForeignKey(Album)
-    title = orm.String(max_length=100)
-    position = orm.Integer()
-
-
-# Create some records to work with.
-malibu = await Album.objects.create(name="Malibu")
-await Track.objects.create(album=malibu, title="The Bird", position=1)
-await Track.objects.create(album=malibu, title="Heart don't stand a chance", position=2)
-await Track.objects.create(album=malibu, title="The Waters", position=3)
-
-fantasies = await Album.objects.create(name="Fantasies")
-await Track.objects.create(album=fantasies, title="Help I'm Alive", position=1)
-await Track.objects.create(album=fantasies, title="Sick Muse", position=2)
-
-
-# Fetch an instance, without loading a foreign key relationship on it.
-track = await Track.objects.get(title="The Bird")
-
-# We have an album instance, but it only has the primary key populated
-print(track.album)       # Album(id=1) [sparse]
-print(track.album.pk)    # 1
-print(track.album.name)  # Raises AttributeError
-
-# Load the relationship from the database
-await track.album.load()
-assert track.album.name == "Malibu"
-
-# This time, fetch an instance, loading the foreign key relationship.
-track = await Track.objects.select_related("album").get(title="The Bird")
-assert track.album.name == "Malibu"
-
-# Fetch instances, with a filter across an FK relationship.
-tracks = Track.objects.filter(album__name="Fantasies")
-assert len(tracks) == 2
-
-# Fetch instances, with a filter and operator across an FK relationship.
-tracks = Track.objects.filter(album__name__iexact="fantasies")
-assert len(tracks) == 2
-
-# Limit a query
-tracks = await Track.objects.limit(1).all()
-assert len(tracks) == 1
-```
-
-## Data types
-
-The following keyword arguments are supported on all field types.
-
-* `primary_key`
-* `allow_null`
-* `default`
-* `index`
-* `unique`
-
-All fields are required unless one of the following is set:
-
-* `allow_null` - Creates a nullable column. Sets the default to `None`.
-* `allow_blank` - Allow empty strings to validate. Sets the default to `""`.
-* `default` - Set a default value for the field.
-
-The following column types are supported.
-See TypeSystem for [type-specific validation keyword arguments][typesystem-fields].
-
-* `orm.BigInteger()`
-* `orm.Boolean()`
-* `orm.Date()`
-* `orm.DateTime()`
-* `orm.Enum()`
-* `orm.Float()`
-* `orm.Integer()`
-* `orm.String(max_length)`
-* `orm.Text()`
-* `orm.Time()`
-* `orm.JSON()`
-
 [sqlalchemy-core]: https://docs.sqlalchemy.org/en/latest/core/
 [alembic]: https://alembic.sqlalchemy.org/en/latest/
 [psycopg2]: https://www.psycopg.org/

diff --git a/docs/declaring_models.md b/docs/declaring_models.md
@@ -0,0 +1,75 @@
+## Declaring models
+
+You can define models by inheriting from `orm.Model` and
+defining model fields as attributes in the class.
+For each defined model you need to set two special variables:
+
+* `__database__` for database connection.
+* `__metadata__` for `SQLAlchemy` functions and migrations.
+
+You can also specify the table name in database by setting `__tablename__` attribute.
+
+```python
+import databases
+import orm
+import sqlalchemy
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Note(orm.Model):
+    __tablename__ = "notes"
+    __database__ = database
+    __metadata__ = metadata
+
+    id = orm.Integer(primary_key=True)
+    text = orm.String(max_length=100)
+    completed = orm.Boolean(default=False)
+```
+
+ORM can create or drop database and tables from models using SQLAlchemy.
+For using these functions or `Alembic` migrations, you still have to
+install a synchronous DB driver: [psycopg2][psycopg2] for PostgreSQL and [pymysql][pymysql] for MySQL.
+
+Afer installing a synchronous DB driver, you can create tables for the models using:
+
+```python
+engine = sqlalchemy.create_engine(str(database.url))
+metadata.create_all(engine)
+```
+
+## Data types
+
+The following keyword arguments are supported on all field types.
+
+* `primary_key` - A boolean. Determine if column is primary key.
+* `allow_null` - A boolean. Determine if column is nullable.
+* `default` - A value or a callable (function).
+* `index` - A boolean. Determine if database indexes should be created.
+* `unique` - A boolean. Determine if unique constraint should be created.
+
+All fields are required unless one of the following is set:
+
+* `allow_null` - A boolean. Determine if column is nullable. Sets the default to `None`.
+* `allow_blank` - A boolean. Determine if empty strings are allowed. Sets the default to `""`.
+* `default` - A value or a callable (function).
+
+The following column types are supported.
+See `TypeSystem` for [type-specific validation keyword arguments][typesystem-fields].
+
+* `orm.BigInteger()`
+* `orm.Boolean()`
+* `orm.Date()`
+* `orm.DateTime()`
+* `orm.Enum()`
+* `orm.Float()`
+* `orm.Integer()`
+* `orm.String(max_length)`
+* `orm.Text()`
+* `orm.Time()`
+* `orm.JSON()`
+
+[psycopg2]: https://www.psycopg.org/
+[pymysql]: https://github.com/PyMySQL/PyMySQL
+[typesystem-fields]: https://www.encode.io/typesystem/fields/
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,90 @@
+# ORM
+
+<p>
+<a href="https://github.com/encode/orm/actions">
+    <img src="https://github.com/encode/orm/workflows/Test%20Suite/badge.svg" alt="Build Status">
+</a>
+<a href="https://codecov.io/gh/encode/orm">
+    <img src="https://codecov.io/gh/encode/orm/branch/master/graph/badge.svg" alt="Coverage">
+</a>
+<a href="https://pypi.org/project/orm/">
+    <img src="https://badge.fury.io/py/orm.svg" alt="Package version">
+</a>
+</p>
+
+The `orm` package is an async ORM for Python, with support for Postgres,
+MySQL, and SQLite. ORM is built with:
+
+* [SQLAlchemy core][sqlalchemy-core] for query building.
+* [`databases`][databases] for cross-database async support.
+* [`typesystem`][typesystem] for data validation.
+
+Because ORM is built on SQLAlchemy core, you can use Alembic to provide
+database migrations.
+
+**ORM is still under development: We recommend pinning any dependencies with `orm~=0.1`**
+
+---
+
+## Installation
+
+```shell
+$ pip install orm
+```
+
+You can install the required database drivers with:
+
+```shell
+$ pip install orm[postgresql]
+$ pip install orm[mysql]
+$ pip install orm[sqlite]
+```
+
+Driver support is provided using one of [asyncpg][asyncpg], [aiomysql][aiomysql], or [aiosqlite][aiosqlite].
+Note that if you are using any synchronous SQLAlchemy functions such as `engine.create_all()` or [alembic][alembic] migrations then you still have to install a synchronous DB driver: [psycopg2][psycopg2] for PostgreSQL and [pymysql][pymysql] for MySQL.
+
+---
+
+## Quickstart
+
+**Note**: Use `ipython` to try this from the console, since it supports `await`.
+
+```python
+import databases
+import orm
+import sqlalchemy
+
+database = databases.Database("sqlite:///db.sqlite")
+metadata = sqlalchemy.MetaData()
+
+
+class Note(orm.Model):
+    __tablename__ = "notes"
+    __database__ = database
+    __metadata__ = metadata
+    id = orm.Integer(primary_key=True)
+    text = orm.String(max_length=100)
+    completed = orm.Boolean(default=False)
+
+# Create the database and tables
+engine = sqlalchemy.create_engine(str(database.url))
+metadata.create_all(engine)
+
+await Note.objects.create(text="Buy the groceries.", completed=False)
+
+note = await Note.objects.get(id=1)
+print(note)
+# Note(id=1, text="Buy the groceries.", completed=False)
+```
+
+[sqlalchemy-core]: https://docs.sqlalchemy.org/en/latest/core/
+[alembic]: https://alembic.sqlalchemy.org/en/latest/
+[psycopg2]: https://www.psycopg.org/
+[pymysql]: https://github.com/PyMySQL/PyMySQL
+[asyncpg]: https://github.com/MagicStack/asyncpg
+[aiomysql]: https://github.com/aio-libs/aiomysql
+[aiosqlite]: https://github.com/jreese/aiosqlite
+
+[databases]: https://github.com/encode/databases
+[typesystem]: https://github.com/encode/typesystem
+[typesystem-fields]: https://www.encode.io/typesystem/fields/