api.add_variable() add parameter keyword

metacatalog/api/add.py

@@ -121,7 +121,7 @@
     return add_record(session=session, tablename='units', **attrs)
 
 
-def add_variable(session: 'Session', name: str, symbol: str, column_names: List[str], unit: Union[int, str]) -> models.Variable:
+def add_variable(session: 'Session', name: str, symbol: str, column_names: List[str], unit: Union[int, str], keyword: Union[int, str] = None) -> models.Variable:
     r"""
     Add a new variable to the database.
 
@@ -142,6 +142,12 @@
     unit : int, str
         Either the id or **full** name of the unit to be
         linked to this variable.
+    keyword: int, str
+        .. versionadded:: 0.8.4
+        Either the id or **full** path of the keyword to be
+        linked to this variable.  
+        It is strongly recommended to add a keyword from a controlled thesaurus to a 
+        newly created variable to improve the findability of the variable.
 
     Returns
     -------
@@ -159,9 +165,20 @@
         unit = api.find_unit(session=session,name=unit, return_iterator=True).first()
     else:
         raise AttributeError('unit has to be of type integer or string.')
-
+    
     attrs['unit_id'] = unit.id
 
+    # get the keyword
+    if keyword:
+        if isinstance(keyword, int):
+            keyword = api.find_keyword(session=session, id=keyword, return_iterator=True).one()
+        elif isinstance(keyword, str):
+            keyword = api.find_keyword(session=session, full_path=keyword, return_iterator=True).first()
+        else:
+            raise AttributeError('keyword has to be of type integer or string.')
+
+        attrs['keyword_id'] = keyword.id
+
     # add the variable
     return add_record(session=session, tablename='variables', **attrs)
 

metacatalog/api/find.py

@@ -83,7 +83,7 @@
 def find_keyword(return_iterator: Literal[False] = False) -> List['Keyword']: ...
 @overload
 def find_keyword(return_iterator: Literal[True] = False) -> 'Query': ...
-def find_keyword(session: 'Session', id: Optional[int] = None, uuid: Optional[str] = None, value: Optional[str] = None, thesaurus_name: Optional[str] = None, return_iterator: bool = False) -> List['Keyword'] | 'Query':
+def find_keyword(session: 'Session', id: Optional[int] = None, uuid: Optional[str] = None, value: Optional[str] = None, full_path: Optional[str] = None, thesaurus_name: Optional[str] = None, return_iterator: bool = False) -> List['Keyword'] | 'Query':
     """
     Return one or many keyword entries from the database on
     exact matches.
@@ -103,6 +103,10 @@
     value : str
         Value of the requested keyword(s). Multiple record
         return is possible.
+    full_path : str
+        .. versionadded:: 0.8.4
+
+        Full path of the requested keyword.
     thesaurus_name : str
         .. versionadded:: 0.1.10
 
@@ -133,6 +137,8 @@
     # add needed filter
     if id is not None:
         query = query.filter(models.Keyword.id==id)
+    if full_path is not None:
+        query = query.filter(models.Keyword.full_path==full_path)
     if value is not None:
         query = query.filter(_match(models.Keyword.value, value))
     if thesaurus_name is not None: