From 358f4ce45e009d5355d1960b6fa280f4037217fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Goran=20Meki=C4=87?= <meka@tilda.center>
Date: Mon, 12 Feb 2024 17:54:34 +0100
Subject: [PATCH] Change line numbers in documentation

---
 docs/fields/common-parameters.md |  2 +-
 docs/models/index.md             | 37 ++++++++++----------
 docs/models/internals.md         |  4 +--
 docs/queries/create.md           |  4 +--
 docs/queries/delete.md           |  4 +--
 docs/queries/update.md           |  6 ++--
 docs/relations/foreign-key.md    | 16 ++++-----
 docs/relations/index.md          | 60 ++++++++++++++++++--------------
 docs/relations/many-to-many.md   | 23 ++++++------
 docs/relations/queryset-proxy.md |  4 +--
 docs/signals.md                  | 30 ++++++++--------
 docs_src/signals/docs002.py      |  3 +-
 12 files changed, 102 insertions(+), 91 deletions(-)

diff --git a/docs/fields/common-parameters.md b/docs/fields/common-parameters.md
index bee0f4150..c7c7f906d 100644
--- a/docs/fields/common-parameters.md
+++ b/docs/fields/common-parameters.md
@@ -108,7 +108,7 @@ Used in sql only.
 
 Sample usage:
 
-```Python hl_lines="21-23"
+```Python hl_lines="20-22"
 --8<-- "../docs_src/fields/docs004.py"
 ```
 
diff --git a/docs/models/index.md b/docs/models/index.md
index 4c3239350..4c1d90d76 100644
--- a/docs/models/index.md
+++ b/docs/models/index.md
@@ -9,7 +9,7 @@ They are being managed in the background and you do not have to create them on y
 
 To build an ormar model you simply need to inherit a `ormar.Model` class.
 
-```Python hl_lines="10"
+```Python hl_lines="9"
 --8<-- "../docs_src/models/docs001.py"
 ```
 
@@ -23,7 +23,7 @@ Each table **has to** have a primary key column, which you specify by setting `p
 
 Only one primary key column is allowed.
 
-```Python hl_lines="15 16 17"
+```Python hl_lines="15-17"
 --8<-- "../docs_src/models/docs001.py"
 ```
 
@@ -60,7 +60,7 @@ you should get back exactly same value in `response`.).
 !!!warning
     pydantic fields have to be always **Optional** and it cannot be changed (otherwise db load validation would fail)
 
-```Python hl_lines="18"
+```Python hl_lines="19"
 --8<-- "../docs_src/models/docs014.py"
 ```
 
@@ -134,17 +134,17 @@ If for whatever reason you prefer to change the name in the database but keep th
 with specifying `name` parameter during Field declaration
 
 Here you have a sample model with changed names
-```Python hl_lines="16-19"
+```Python hl_lines="18-21"
 --8<-- "../docs_src/models/docs008.py"
 ```
 
 Note that you can also change the ForeignKey column name
-```Python hl_lines="21"
+```Python hl_lines="34"
 --8<-- "../docs_src/models/docs009.py"
 ```
 
 But for now you cannot change the ManyToMany column names as they go through other Model anyway.
-```Python hl_lines="28"
+```Python hl_lines="43"
 --8<-- "../docs_src/models/docs010.py"
 ```
 
@@ -219,7 +219,7 @@ One is `Database` instance created with your database url in [sqlalchemy connect
 
 Created instance needs to be passed to every `Model` with `Meta` class `database` parameter.
 
-```Python hl_lines="1 6 12"
+```Python hl_lines="1 5 11"
 --8<-- "../docs_src/models/docs001.py"
 ```
 
@@ -233,7 +233,7 @@ Second dependency is sqlalchemy `MetaData` instance.
 
 Created instance needs to be passed to every `Model` with `Meta` class `metadata` parameter.
 
-```Python hl_lines="2 7 13"
+```Python hl_lines="3 6 12"
 --8<-- "../docs_src/models/docs001.py"
 ```
 
@@ -243,11 +243,12 @@ Created instance needs to be passed to every `Model` with `Meta` class `metadata
 
 #### Best practice
 
-Only thing that `ormar` expects is a class with name `Meta` and two class variables: `metadata` and `databases`.
+Only thing that `ormar` expects is a field with name `ormar_config`.
 
-So instead of providing the same parameters over and over again for all models you should creata a class and subclass it in all models.
+So instead of providing the same parameters over and over again for all models
+you should creat an object and use its copy in all models.
 
-```Python hl_lines="14 20 33"
+```Python hl_lines="9-11 18 27"
 --8<-- "../docs_src/models/docs013.py"
 ```
 
@@ -261,7 +262,7 @@ By default table name is created from Model class name as lowercase name plus 's
 
 You can overwrite this parameter by providing `Meta` class `tablename` argument.
 
-```Python hl_lines="12 13 14"
+```Python hl_lines="14-16"
 --8<-- "../docs_src/models/docs002.py"
 ```
 
@@ -281,7 +282,7 @@ Right now only `IndexColumns` and `UniqueColumns` constraints are supported.
 
 You can set this parameter by providing `Meta` class `constraints` argument.
 
-```Python hl_lines="14-17"
+```Python hl_lines="13-16"
 --8<-- "../docs_src/models/docs006.py"
 ```
 
@@ -294,7 +295,7 @@ You can set this parameter by providing `Meta` class `constraints` argument.
 
 You can set this parameter by providing `Meta` class `constraints` argument.
 
-```Python hl_lines="14-17"
+```Python hl_lines="13-16"
 --8<-- "../docs_src/models/docs017.py"
 ```
 
@@ -307,7 +308,7 @@ You can set this parameter by providing `Meta` class `constraints` argument.
 
 You can set this parameter by providing `Meta` class `constraints` argument.
 
-```Python hl_lines="14-17"
+```Python hl_lines="15-20"
 --8<-- "../docs_src/models/docs018.py"
 ```
 
@@ -336,7 +337,7 @@ class Config(pydantic.BaseConfig):
 ```
 
 So to overwrite setting or provide your own a sample model can look like following:
-```Python hl_lines="15-16"
+```Python hl_lines="16"
 --8<-- "../docs_src/models/docs016.py"
 ```
 
@@ -425,7 +426,7 @@ There are two ways to create and persist the `Model` instance in the database.
 
 If you plan to modify the instance in the later execution of your program you can initiate your `Model` as a normal class and later await a `save()` call.  
 
-```Python hl_lines="20 21"
+```Python hl_lines="25-26"
 --8<-- "../docs_src/models/docs007.py"
 ```
 
@@ -435,7 +436,7 @@ For creating multiple objects at once a `bulk_create()` QuerySet's method is ava
 
 Each model has a `QuerySet` initialised as `objects` parameter 
 
-```Python hl_lines="23"
+```Python hl_lines="28"
 --8<-- "../docs_src/models/docs007.py"
 ```
 
diff --git a/docs/models/internals.md b/docs/models/internals.md
index 463d368fa..defce7a43 100644
--- a/docs/models/internals.md
+++ b/docs/models/internals.md
@@ -24,7 +24,7 @@ To access auto created sqlalchemy table you can use `Model.Meta.table` parameter
 
 For example to list table columns you can:
 
-```Python hl_lines="20"
+```Python hl_lines="24"
 --8<-- "../docs_src/models/docs004.py"
 ```
 
@@ -40,7 +40,7 @@ To access ormar `Fields` you can use `Model.Meta.model_fields` parameter
 
 For example to list table model fields you can:
 
-```Python hl_lines="20"
+```Python hl_lines="22"
 --8<-- "../docs_src/models/docs005.py"
 ```
 
diff --git a/docs/queries/create.md b/docs/queries/create.md
index 76b5d2e48..31572587f 100644
--- a/docs/queries/create.md
+++ b/docs/queries/create.md
@@ -106,7 +106,7 @@ assert album == album2
 
 Updates the model, or in case there is no match in database creates a new one.
 
-```Python hl_lines="26-32"
+```Python hl_lines="40-48"
 --8<-- "../docs_src/queries/docs003.py"
 ```
 
@@ -122,7 +122,7 @@ Allows you to create multiple objects at once.
 
 A valid list of `Model` objects needs to be passed.
 
-```python hl_lines="21-27"
+```python hl_lines="26-32"
 --8<-- "../docs_src/queries/docs004.py"
 ```
 
diff --git a/docs/queries/delete.md b/docs/queries/delete.md
index aec5171a1..ef5b1a202 100644
--- a/docs/queries/delete.md
+++ b/docs/queries/delete.md
@@ -26,7 +26,7 @@ If you do not provide this flag or a filter a `QueryDefinitionError` will be rai
 
 Return number of rows deleted.
 
-```python hl_lines="26-30"
+```python hl_lines="40-44"
 --8<-- "../docs_src/queries/docs005.py"
 ```
 
@@ -148,4 +148,4 @@ await album.tracks.clear()
 await album.tracks.clear(keep_reversed=False)
 ```
 
-[querysetproxy]: ../relations/queryset-proxy.md
\ No newline at end of file
+[querysetproxy]: ../relations/queryset-proxy.md
diff --git a/docs/queries/update.md b/docs/queries/update.md
index 642f04407..f9f00e901 100644
--- a/docs/queries/update.md
+++ b/docs/queries/update.md
@@ -29,7 +29,7 @@ If you do not provide this flag or a filter a `QueryDefinitionError` will be rai
 
 Return number of rows updated.
 
-```Python hl_lines="26-28"
+```Python hl_lines="42-44"
 --8<-- "../docs_src/queries/docs002.py"
 ```
 
@@ -44,7 +44,7 @@ Return number of rows updated.
 
 Updates the model, or in case there is no match in database creates a new one.
 
-```Python hl_lines="26-32"
+```Python hl_lines="40-48"
 --8<-- "../docs_src/queries/docs003.py"
 ```
 
@@ -123,4 +123,4 @@ from other side of the relation.
 
 [querysetproxy]: ../relations/queryset-proxy.md
 [models-upsert]: ../models/methods.md#upsert
-[models-save-related]: ../models/methods.md#save_related
\ No newline at end of file
+[models-save-related]: ../models/methods.md#save_related
diff --git a/docs/relations/foreign-key.md b/docs/relations/foreign-key.md
index 2f880a1e9..4e84ffb55 100644
--- a/docs/relations/foreign-key.md
+++ b/docs/relations/foreign-key.md
@@ -14,7 +14,7 @@ Sqlalchemy column and Type are automatically taken from target `Model`.
 
 To define a relation add `ForeignKey` field that points to related `Model`.
 
-```Python hl_lines="29"
+```Python hl_lines="30"
 --8<-- "../docs_src/fields/docs003.py"
 ```
 
@@ -24,7 +24,7 @@ To define a relation add `ForeignKey` field that points to related `Model`.
 
 By default it's child (source) `Model` name + s, like courses in snippet below: 
 
-```Python hl_lines="29 35"
+```Python hl_lines="29 36"
 --8<-- "../docs_src/fields/docs001.py"
 ```
 
@@ -175,7 +175,7 @@ To read which methods of QuerySet are available read below [querysetproxy][query
 
 But you can overwrite this name by providing `related_name` parameter like below:
 
-```Python hl_lines="29 35"
+```Python hl_lines="27-29 35"
 --8<-- "../docs_src/fields/docs002.py"
 ```
 
@@ -230,7 +230,7 @@ You have several ways to set-up a relationship connection.
 
 The most obvious one is to pass a related `Model` instance to the constructor.
 
-```Python hl_lines="34-35"
+```Python hl_lines="35-36"
 --8<-- "../docs_src/relations/docs001.py"
 ```
 
@@ -238,7 +238,7 @@ The most obvious one is to pass a related `Model` instance to the constructor.
 
 You can setup the relation also with just the pk column value of the related model.
 
-```Python hl_lines="37-38"
+```Python hl_lines="38-39"
 --8<-- "../docs_src/relations/docs001.py"
 ```
 
@@ -248,7 +248,7 @@ Next option is with a dictionary of key-values of the related model.
 
 You can build the dictionary yourself or get it from existing model with `model_dump()` method.
 
-```Python hl_lines="40-41"
+```Python hl_lines="41-42"
 --8<-- "../docs_src/relations/docs001.py"
 ```
 
@@ -256,7 +256,7 @@ You can build the dictionary yourself or get it from existing model with `model_
 
 Finally you can explicitly set it to None (default behavior if no value passed).
 
-```Python hl_lines="43-44"
+```Python hl_lines="44-45"
 --8<-- "../docs_src/relations/docs001.py"
 ```
 
@@ -283,4 +283,4 @@ Finally you can explicitly set it to None (default behavior if no value passed).
 [fields]: ./queries.md#fields
 [exclude_fields]: ./queries.md#exclude_fields
 [order_by]: ./queries.md#order_by
-[server_default]: ../fields/common-parameters.md#server-default
\ No newline at end of file
+[server_default]: ../fields/common-parameters.md#server-default
diff --git a/docs/relations/index.md b/docs/relations/index.md
index 385516a8e..eaa539675 100644
--- a/docs/relations/index.md
+++ b/docs/relations/index.md
@@ -13,7 +13,7 @@ To read more about methods, possibilities, definition etc. please read the subse
 
 To define many-to-one relation use `ForeignKey` field.
 
-```Python hl_lines="17"
+```Python hl_lines="26"
 --8<-- "../docs_src/relations/docs003.py"
 ```
 
@@ -26,7 +26,7 @@ The definition of one-to-many relation also uses `ForeignKey`, and it's register
 
 So in relation ato example above.
 
-```Python hl_lines="17"
+```Python hl_lines="9"
 class Department(ormar.Model):
     class Meta:
         database = database
@@ -54,19 +54,21 @@ To define many-to-many relation use `ManyToMany` field.
 
 ```python hl_lines="18"
 class Category(ormar.Model):
-    class Meta:
-        tablename = "categories"
-        database = database
-        metadata = metadata
+    ormar_config = ormar.OrmarConfig(
+        database=database,
+        metadata=metadata,
+        tablename="posts",
+    )
 
     id: int = ormar.Integer(primary_key=True)
     name: str = ormar.String(max_length=40)
 
 class Post(ormar.Model):
-    class Meta:
-        tablename = "posts"
-        database = database
-        metadata = metadata
+    ormar_config = ormar.OrmarConfig(
+        database=database,
+        metadata=metadata,
+        tablename="posts",
+    )
 
     id: int = ormar.Integer(primary_key=True)
     title: str = ormar.String(max_length=200)
@@ -92,18 +94,23 @@ side of the current query for m2m models.
 So if you query from model `A` to model `B`, only model `B` has through field exposed.
 Which kind of make sense, since it's a one through model/field for each of related models.
 
-```python hl_lines="10-15"
+```python hl_lines="12-20"
 class Category(ormar.Model):
-    class Meta(BaseMeta):
-        tablename = "categories"
+    ormar_config = ormar.OrmarConfig(
+        database=database,
+        metadata=metadata,
+    )
 
     id = ormar.Integer(primary_key=True)
     name = ormar.String(max_length=40)
 
 # you can specify additional fields on through model
 class PostCategory(ormar.Model):
-    class Meta(BaseMeta):
-        tablename = "posts_x_categories"
+    ormar_config = ormar.OrmarConfig(
+        database=database,
+        metadata=metadata,
+        tablename="posts_x_categories",
+    )
 
     id: int = ormar.Integer(primary_key=True)
     sort_order: int = ormar.Integer(nullable=True)
@@ -111,8 +118,10 @@ class PostCategory(ormar.Model):
 
 
 class Post(ormar.Model):
-    class Meta(BaseMeta):
-        pass
+    ormar_config = ormar.OrmarConfig(
+        database=database,
+        metadata=metadata,
+    )
 
     id: int = ormar.Integer(primary_key=True)
     title: str = ormar.String(max_length=200)
@@ -143,27 +152,26 @@ columns also `Through` model columns `{through_field_name}__{column_name}`
 
 Sample configuration might look like this:
 
-```python hl_lines="24"
+```python hl_lines="23"
 database = databases.Database(DATABASE_URL)
 metadata = sqlalchemy.MetaData()
 
 
-class BaseMeta(ormar.ModelMeta):
-    metadata = metadata
-    database = database
+base_ormar_config = ormar.OrmarConfig(
+    database=database,
+    metadata=metadata,
+)
 
 
 class Author(ormar.Model):
-    class Meta(BaseMeta):
-        tablename = "authors"
+    ormar_config = base_ormar_config.copy()
 
     id: int = ormar.Integer(primary_key=True)
     name: str = ormar.String(max_length=100)
 
 
 class Book(ormar.Model):
-    class Meta(BaseMeta):
-        tablename = "books"
+    ormar_config = base_ormar_config.copy()
 
     id: int = ormar.Integer(primary_key=True)
     author: Optional[Author] = ormar.ForeignKey(
@@ -210,4 +218,4 @@ Person.update_forward_refs()
 [foreign-keys]: ./foreign-key.md
 [many-to-many]: ./many-to-many.md
 [queryset-proxy]: ./queryset-proxy.md
-[postponed-annotations]: ./postponed-annotations.md
\ No newline at end of file
+[postponed-annotations]: ./postponed-annotations.md
diff --git a/docs/relations/many-to-many.md b/docs/relations/many-to-many.md
index d3eb7bdd4..c9d6ee443 100644
--- a/docs/relations/many-to-many.md
+++ b/docs/relations/many-to-many.md
@@ -9,7 +9,7 @@ Sqlalchemy column and Type are automatically taken from target `Model`.
 
 ## Defining Models
 
-```Python hl_lines="40"
+```Python hl_lines="34"
 --8<-- "../docs_src/relations/docs002.py"
 ```
 
@@ -141,7 +141,7 @@ assert len(categories) == 1
 Optionally if you want to add additional fields you can explicitly create and pass
 the through model class.
 
-```Python hl_lines="14-20 29"
+```Python hl_lines="19-24 32"
 --8<-- "../docs_src/relations/docs004.py"
 ```
 
@@ -198,11 +198,15 @@ To customize the names of fields/relation in Through model now you can use new p
 Example:
 
 ```python
+base_ormar_config = ormar.OrmarConfig(
+    database=databases.Database("sqlite:///db.sqlite"),
+    metadata=sqlalchemy.MetaData(),
+)
+
+
 ... # course declaration ommited
 class Student(ormar.Model):
-    class Meta:
-        database = database
-        metadata = metadata
+    ormar_config = base_ormar_config.copy()
 
     id: int = ormar.Integer(primary_key=True)
     name: str = ormar.String(max_length=100)
@@ -212,10 +216,7 @@ class Student(ormar.Model):
 
 # will produce Through model like follows (example simplified)
 class StudentCourse(ormar.Model):
-    class Meta:
-        database = database
-        metadata = metadata
-        tablename = "students_courses"
+    ormar_config = base_ormar_config.copy()
 
     id: int = ormar.Integer(primary_key=True)
     student_id = ormar.ForeignKey(Student) # set by through_relation_name
@@ -238,7 +239,7 @@ so it's useful only when additional fields are provided on `Through` model.
 
 In a sample model setup as following:
 
-```Python hl_lines="14-20 29"
+```Python hl_lines="19-24 32"
 --8<-- "../docs_src/relations/docs004.py"
 ```
 
@@ -419,4 +420,4 @@ To read which methods of QuerySet are available read below [querysetproxy][query
 [exists]: ./queries.md#exists
 [fields]: ./queries.md#fields
 [exclude_fields]: ./queries.md#exclude_fields
-[order_by]: ./queries.md#order_by
\ No newline at end of file
+[order_by]: ./queries.md#order_by
diff --git a/docs/relations/queryset-proxy.md b/docs/relations/queryset-proxy.md
index fa70d6f41..90c89fbfb 100644
--- a/docs/relations/queryset-proxy.md
+++ b/docs/relations/queryset-proxy.md
@@ -127,7 +127,7 @@ provided Through model.
 
 Given sample like this:
 
-```Python hl_lines="14-20 29"
+```Python hl_lines="19-24 32"
 --8<-- "../docs_src/relations/docs004.py"
 ```
 
@@ -174,7 +174,7 @@ Updates the related model with provided keyword arguments, return number of upda
 Note that for `ManyToMany` relations update can also accept an argument with through field
 name and a dictionary of fields.
 
-```Python hl_lines="14-20 29"
+```Python hl_lines="19-24 32"
 --8<-- "../docs_src/relations/docs004.py"
 ```
 
diff --git a/docs/signals.md b/docs/signals.md
index 2c33eebdd..9905ac83f 100644
--- a/docs/signals.md
+++ b/docs/signals.md
@@ -14,15 +14,15 @@ import sqlalchemy
 
 import ormar
 
-database = databases.Database("sqlite:///db.sqlite")
-metadata = sqlalchemy.MetaData()
+
+base_ormar_config = ormar.OrmarConfig(
+    database=databases.Database("sqlite:///db.sqlite"),
+    metadata=sqlalchemy.MetaData(),
+)
 
 
 class Album(ormar.Model):
-    class Meta:
-        tablename = "albums"
-        metadata = metadata
-        database = database
+    ormar_config = base_ormar_config.copy()
 
     id: int = ormar.Integer(primary_key=True)
     name: str = ormar.String(max_length=100)
@@ -34,7 +34,7 @@ You can for example define a trigger that will set `album.is_best_seller` status
 
 Import `pre_update` decorator, for list of currently available decorators/ signals check below.
 
-```Python hl_lines="1"
+```Python hl_lines="7"
 --8<-- "../docs_src/signals/docs002.py"
 ```
 
@@ -54,7 +54,7 @@ for which you want to run the signal receiver.
 
 Currently there is no way to set signal for all models at once without explicitly passing them all into registration of receiver.
 
-```Python hl_lines="4-7"
+```Python hl_lines="27-30"
 --8<-- "../docs_src/signals/docs002.py"
 ```
 
@@ -65,7 +65,7 @@ Currently there is no way to set signal for all models at once without explicitl
 Note that our newly created function has instance and class of the instance so you can easily run database 
 queries inside your receivers if you want to.
 
-```Python hl_lines="15-22"
+```Python hl_lines="40-47"
 --8<-- "../docs_src/signals/docs002.py"
 ```
 
@@ -251,15 +251,15 @@ import sqlalchemy
 
 import ormar
 
-database = databases.Database("sqlite:///db.sqlite")
-metadata = sqlalchemy.MetaData()
+
+base_ormar_config = ormar.OrmarConfig(
+    database=databases.Database("sqlite:///db.sqlite"),
+    metadata=sqlalchemy.MetaData(),
+)
 
 
 class Album(ormar.Model):
-    class Meta:
-        tablename = "albums"
-        metadata = metadata
-        database = database
+    ormar_config = base_ormar_config.copy()
 
     id: int = ormar.Integer(primary_key=True)
     name: str = ormar.String(max_length=100)
diff --git a/docs_src/signals/docs002.py b/docs_src/signals/docs002.py
index fd42ed337..0795d67fb 100644
--- a/docs_src/signals/docs002.py
+++ b/docs_src/signals/docs002.py
@@ -9,7 +9,8 @@
 DATABASE_URL = "sqlite:///test.db"
 
 ormar_base_config = ormar.OrmarConfig(
-    database=databases.Database(DATABASE_URL), metadata=sqlalchemy.MetaData()
+    database=databases.Database(DATABASE_URL),
+    metadata=sqlalchemy.MetaData(),
 )