Update docs

README.md

@@ -587,7 +587,7 @@ metadata.drop_all(engine)
 *  `create(**kwargs): -> Model`
 *  `get(*args, **kwargs): -> Model`
 *  `get_or_none(*args, **kwargs): -> Optional[Model]`
-*  `get_or_create(*args, **kwargs) -> Model`
+*  `get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Tuple[Model, bool]`
 *  `first(*args, **kwargs): -> Model`
 *  `update(each: bool = False, **kwargs) -> int`
 *  `update_or_create(**kwargs) -> Model`

docs/api/query-set/query-set.md

@@ -745,7 +745,7 @@ below.
 #### get\_or\_create
 
 ```python
- | async get_or_create(*args: Any, **kwargs: Any) -> "T"
+ | async get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args: Any, **kwargs: Any) -> Tuple["T", bool]
 ```
 
 Combination of create and get methods.

docs/api/relations/queryset-proxy.md

@@ -396,7 +396,7 @@ each=True flag to affect whole table.
 #### get\_or\_create
 
 ```python
- | async get_or_create(*args: Any, **kwargs: Any) -> "T"
+ | async get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args: Any, **kwargs: Any) -> Tuple["T", bool]
 ```
 
 Combination of create and get methods.

docs/index.md

@@ -596,7 +596,7 @@ metadata.drop_all(engine)
 *  `create(**kwargs): -> Model`
 *  `get(*args, **kwargs): -> Model`
 *  `get_or_none(*args, **kwargs): -> Optional[Model]`
-*  `get_or_create(*args, **kwargs) -> Model`
+*  `get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Tuple[Model, bool]`
 *  `first(*args, **kwargs): -> Model`
 *  `update(each: bool = False, **kwargs) -> int`
 *  `update_or_create(**kwargs) -> Model`

docs/queries/create.md

@@ -3,7 +3,7 @@
 Following methods allow you to insert data into the database.
 
 * `create(**kwargs) -> Model`
-* `get_or_create(**kwargs) -> Model`
+* `get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[Model, bool]`
 * `update_or_create(**kwargs) -> Model`
 * `bulk_create(objects: List[Model]) -> None`
 
@@ -16,7 +16,7 @@ Following methods allow you to insert data into the database.
 
 * `QuerysetProxy`
       * `QuerysetProxy.create(**kwargs)` method
-      * `QuerysetProxy.get_or_create(**kwargs)` method
+      * `QuerysetProxy.get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs)` method
       * `QuerysetProxy.update_or_create(**kwargs)` method
 
 ## create
@@ -56,12 +56,12 @@ await malibu.save()
 
 ## get_or_create
 
-`get_or_create(**kwargs) -> Model`
+`get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[Model, bool]`
 
 Combination of create and get methods.
 
 Tries to get a row meeting the criteria and if `NoMatch` exception is raised it creates
-a new one with given kwargs.
+a new one with given kwargs and _defaults.
 
 ```python
 class Album(ormar.Model):
@@ -72,12 +72,17 @@ class Album(ormar.Model):
 
     id: int = ormar.Integer(primary_key=True)
     name: str = ormar.String(max_length=100)
+    year: int = ormar.Integer()
 ```
 
 ```python
-album = await Album.objects.get_or_create(name='The Cat')
+album, created = await Album.objects.get_or_create(name='The Cat', _defaults={"year": 1999})
+assert created is True
+assert album.name == "The Cat"
+assert album.year == 1999
 # object is created as it does not exist
-album2 = await Album.objects.get_or_create(name='The Cat')
+album2, created = await Album.objects.get_or_create(name='The Cat')
+assert created is False
 assert album == album2
 # return True as the same db row is returned
 ```

docs/queries/filter-and-sort.md

@@ -6,7 +6,7 @@ You can use following methods to filter the data (sql where clause).
 * `exclude(*args, **kwargs) -> QuerySet`
 * `get(*args, **kwargs) -> Model`
 * `get_or_none(*args, **kwargs) -> Optional[Model]`
-* `get_or_create(*args, **kwargs) -> Model`
+* `get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Tuple[Model, bool]`
 * `all(*args, **kwargs) -> List[Optional[Model]]`
 
 
@@ -15,7 +15,7 @@ You can use following methods to filter the data (sql where clause).
     * `QuerysetProxy.exclude(*args, **kwargs)` method
     * `QuerysetProxy.get(*args, **kwargs)` method
     * `QuerysetProxy.get_or_none(*args, **kwargs)` method
-    * `QuerysetProxy.get_or_create(*args, **kwargs)` method
+    * `QuerysetProxy.get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs)` method
     * `QuerysetProxy.all(*args, **kwargs)` method
 
 And following methods to sort the data (sql order by clause).
@@ -598,7 +598,7 @@ Exact equivalent of get described above but instead of raising the exception ret
 
 ## get_or_create
 
-`get_or_create(*args, **kwargs) -> Model`
+`get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Tuple[Model, bool]`
 
 Combination of create and get methods.
 

docs/queries/index.md

@@ -24,7 +24,7 @@ To read more about any specific section or function please refer to the details
 ###[Insert data into database](./create.md)
 
 * `create(**kwargs) -> Model`
-* `get_or_create(**kwargs) -> Model`
+* `get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[Model, bool]`
 * `update_or_create(**kwargs) -> Model`
 * `bulk_create(objects: List[Model]) -> None`
 
@@ -37,7 +37,7 @@ To read more about any specific section or function please refer to the details
   
 * `QuerysetProxy`
     * `QuerysetProxy.create(**kwargs)` method
-    * `QuerysetProxy.get_or_create(**kwargs)` method
+    * `QuerysetProxy.get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs)` method
     * `QuerysetProxy.update_or_create(**kwargs)` method
   
 !!!tip
@@ -47,7 +47,7 @@ To read more about any specific section or function please refer to the details
 
 * `get(**kwargs) -> Model`
 * `get_or_none(**kwargs) -> Optional[Model]`
-* `get_or_create(**kwargs) -> Model`
+* `get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[Model, bool]`
 * `first() -> Model`
 * `all(**kwargs) -> List[Optional[Model]]`
 
@@ -59,7 +59,7 @@ To read more about any specific section or function please refer to the details
 * `QuerysetProxy`
     * `QuerysetProxy.get(**kwargs)` method
     * `QuerysetProxy.get_or_none(**kwargs)` method
-    * `QuerysetProxy.get_or_create(**kwargs)` method
+    * `QuerysetProxy.get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs)` method
     * `QuerysetProxy.first()` method
     * `QuerysetProxy.all(**kwargs)` method
   
@@ -140,7 +140,7 @@ Instead of ormar models return raw data in form list of dictionaries or tuples.
 * `order_by(columns:Union[List, str]) -> QuerySet`
 * `get(**kwargs) -> Model`
 * `get_or_none(**kwargs) -> Optional[Model]`
-* `get_or_create(**kwargs) -> Model`
+* `get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[Model, bool]`
 * `all(**kwargs) -> List[Optional[Model]]`
 
 
@@ -150,7 +150,7 @@ Instead of ormar models return raw data in form list of dictionaries or tuples.
     * `QuerysetProxy.order_by(columns:Union[List, str])` method
     * `QuerysetProxy.get(**kwargs)` method
     * `QuerysetProxy.get_or_none(**kwargs)` method
-    * `QuerysetProxy.get_or_create(**kwargs)` method
+    * `QuerysetProxy.get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs)` method
     * `QuerysetProxy.all(**kwargs)` method
   
 !!!tip

docs/queries/read.md

@@ -3,7 +3,7 @@
 Following methods allow you to load data from the database.
 
 * `get(*args, **kwargs) -> Model`
-* `get_or_create(*args, **kwargs) -> Model`
+* `get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Tuple[Model, bool]`
 * `first(*args, **kwargs) -> Model`
 * `all(*args, **kwargs) -> List[Optional[Model]]`
 
@@ -14,7 +14,7 @@ Following methods allow you to load data from the database.
 
 * `QuerysetProxy`
     * `QuerysetProxy.get(*args, **kwargs)` method
-    * `QuerysetProxy.get_or_create(*args, **kwargs)` method
+    * `QuerysetProxy.get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs)` method
     * `QuerysetProxy.first(*args, **kwargs)` method
     * `QuerysetProxy.all(*args, **kwargs)` method
 
@@ -64,12 +64,12 @@ Exact equivalent of get described above but instead of raising the exception ret
 
 ## get_or_create
 
-`get_or_create(*args, **kwargs) -> Model`
+`get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Tuple[Model, bool]`
 
 Combination of create and get methods.
 
 Tries to get a row meeting the criteria and if `NoMatch` exception is raised it creates
-a new one with given kwargs.
+a new one with given kwargs and _defaults.
 
 ```python
 class Album(ormar.Model):
@@ -80,12 +80,17 @@ class Album(ormar.Model):
 
     id: int = ormar.Integer(primary_key=True)
     name: str = ormar.String(max_length=100)
+    year: int = ormar.Integer()
 ```
 
 ```python
-album = await Album.objects.get_or_create(name='The Cat')
+album, created = await Album.objects.get_or_create(name='The Cat', _defaults={"year": 1999})
+assert created is True
+assert album.name == "The Cat"
+assert album.year == 1999
 # object is created as it does not exist
-album2 = await Album.objects.get_or_create(name='The Cat')
+album2, created = await Album.objects.get_or_create(name='The Cat')
+assert created is False
 assert album == album2
 # return True as the same db row is returned
 ```

docs/relations/queryset-proxy.md

@@ -56,9 +56,9 @@ assert post.categories[0] == news
 
 ### get_or_create
 
-`get_or_create(**kwargs) -> Model`
+`get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[Model, bool]`
 
-Tries to get a row meeting the criteria and if NoMatch exception is raised it creates a new one with given kwargs.
+Tries to get a row meeting the criteria and if NoMatch exception is raised it creates a new one with given kwargs and _defaults.
 
 !!!tip
     Read more in queries documentation [get_or_create][get_or_create]
@@ -129,7 +129,7 @@ await post.categories.create(
 
 ### get_or_create
 
-`get_or_create(**kwargs) -> Model`
+`get_or_create(_defaults: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[Model, bool]`
 
 Tries to get a row meeting the criteria and if NoMatch exception is raised it creates a new one with given kwargs.