From 660d40a20effd53a1ad247429670004285c7586b Mon Sep 17 00:00:00 2001
From: Ivan Yelizariev <yelizariev@itpp.dev>
Date: Wed, 5 Aug 2020 15:27:26 +0500
Subject: [PATCH] :memo: improve search_or_create

* nested call for many2one fields
* custom domain for search
---
 base_api/doc/index.rst | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/base_api/doc/index.rst b/base_api/doc/index.rst
index 2af1d159..ed32aa23 100644
--- a/base_api/doc/index.rst
+++ b/base_api/doc/index.rst
@@ -10,7 +10,7 @@ Usage
 search_or_create
 ----------------
 
-*search_or_create(self, vals, active\_test=True)*
+*search_or_create(self, vals, active\_test=True, domain=None)*
 
 *– Purpose*:
   - To resolve “race conditions”, comparing to separated searching
@@ -36,15 +36,26 @@ search_or_create
 
                  active_test = False`  # to also search in *in-active* records
 
+  - `domain`-variable explicit search domain before creating 
 *– Notes*:
   - *many2one* fields in `vals`:
-      - type of integer
-      - e.g.
+      - integer or dictionary
+      - example for integer
             .. code-block::
 
                 vals = {
                         'company_id': 1
                        }
+      - dictionary has same arguments as for `search_or_create` itself
+            .. code-block::
+
+                vals = {
+                        'company_id': {
+                            'vals': {
+                                'name': 'My Company'
+                            }
+                         }
+                       }
 
   - *x2many* fields in `vals`:
       - ignored for searching
@@ -89,7 +100,7 @@ search_or_create
 
 *– Algorithm*:
 
-1.  Creates *domain* out of `vals` for searching
+1.  If `domain` arg is not provided, create *domain* out of `vals` for searching
 
 2.  Searches for records satisfiy *domain* constraints (`is_new = False`)