feat: added docs for add_database_rows

docs/how-to/data-hub/add-data.md

@@ -0,0 +1,43 @@
+# Add data to a Deep Origin Database
+
+This document describes how to add data to a Deep Origin Database.
+
+Consider the following dataframe constructed from a database using:
+
+```python
+from deeporigin.data_hub import api
+df = api.get_dataframe("xy")
+df
+```
+
+![](../../images/df-xy.png)
+
+## Add new rows
+
+To add new rows to the underlying database, use the `add_databse_rows` function:
+
+```python
+data = dict(X=[1, 2], Y=[2, 3])
+api.add_database_rows(database_id="xy", data=data)
+```
+
+`data` should be a dictionary where the keys are column names and the values are lists of values to be written to the corresponding columns. `add_database_rows` will add this data to the database, creating as many new rows as needed. 
+
+`add_database_rows` returns a list of the row IDs created during this process.
+
+
+## Add fragments of new rows 
+
+Similarly, fragments of rows (subsets of columns) can be written to the database:
+
+```python
+data = dict(X=[10, 20]) # note Y is not specified
+api.add_database_rows(database_id="xy", data=data)
+```
+
+`add_database_rows` returns a list of the row IDs created during this process.
+
+
+## Reference
+
+The reference documentation for [add_database_rows](../../ref/data-hub/high-level-api.md#src.data_hub.api.add_database_rows)

mkdocs.yaml

@@ -59,6 +59,7 @@ nav:
     - Upload files: how-to/data-hub/upload-files.md
     - Download files: how-to/data-hub/download-files.md
     - Write data: how-to/data-hub/write-data.md
+    - Add data to database: how-to/data-hub/add-data.md
   - API reference:
     - High-level API: ref/data-hub/high-level-api.md
     - Low-level API: ref/data-hub/low-level-api.md
@@ -112,7 +113,7 @@ plugins:
       handlers:
         python:
           paths: ["."]
-          options:            
+          options:   
             annotations_path: brief
             show_source: false
             docstring_options:

src/data_hub/api.py

@@ -368,8 +368,10 @@ def add_database_rows(
 ) -> list[str]:
     """Add new data to a database.
 
+    Use this function to add new rows, or fragments of rows, to a Deep Origin database.
+
     Args:
-        database_id: ID of the database
+        database_id: Human ID or System ID of the database
         data: A dictionary where each key is a column name and each value is a list of values. All values should have the same length. Key names should match column names in the database.
 
     Returns:
@@ -1316,7 +1318,7 @@ def add_row_to_data(
 
 @beartype
 def row_to_dict(
-    row,
+    row: dict,
     *,
     file_ids: Optional[list] = None,
     reference_ids: Optional[list] = None,

src/platform/utils.py

@@ -13,7 +13,7 @@
 
 @beartype
 def add_functions_to_module(
-    module: str,
+    module,
     api_name: str,
 ) -> set:
     """utility function to dynamically add functions to a module