diff --git a/README.md b/README.md index 8183bbb..f8af8ce 100644 --- a/README.md +++ b/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` diff --git a/docs/api/query-set/query-set.md b/docs/api/query-set/query-set.md index b7aa53e..9c8d2ef 100644 --- a/docs/api/query-set/query-set.md +++ b/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. diff --git a/docs/api/relations/queryset-proxy.md b/docs/api/relations/queryset-proxy.md index 009c466..1710f11 100644 --- a/docs/api/relations/queryset-proxy.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 9ecee7d..1b8618c 100644 --- a/docs/index.md +++ b/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` diff --git a/docs/queries/create.md b/docs/queries/create.md index 560ccae..09cc560 100644 --- a/docs/queries/create.md +++ b/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 ``` diff --git a/docs/queries/filter-and-sort.md b/docs/queries/filter-and-sort.md index 1f778d9..ac7aee9 100644 --- a/docs/queries/filter-and-sort.md +++ b/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. diff --git a/docs/queries/index.md b/docs/queries/index.md index e2c5a0a..8d8c1e2 100644 --- a/docs/queries/index.md +++ b/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 diff --git a/docs/queries/read.md b/docs/queries/read.md index 17972b5..9fa6794 100644 --- a/docs/queries/read.md +++ b/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 ``` diff --git a/docs/relations/queryset-proxy.md b/docs/relations/queryset-proxy.md index fc22d75..736d395 100644 --- a/docs/relations/queryset-proxy.md +++ b/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.