From 59fa99e32d76ddd998960f9fa962f2168a982266 Mon Sep 17 00:00:00 2001
From: James B <james.baster@opendataservices.coop>
Date: Thu, 2 Jan 2025 09:58:42 +0000
Subject: [PATCH] docs content - database models

---
 docs/python-api/index.rst  |  2 ++
 docs/python-api/models.rst | 13 +++++++++++
 libcoveweb2/models.py      | 48 +++++++++++++++++++++++++++++++++-----
 3 files changed, 57 insertions(+), 6 deletions(-)
 create mode 100644 docs/python-api/models.rst

diff --git a/docs/python-api/index.rst b/docs/python-api/index.rst
index 8c77df4..399df1c 100644
--- a/docs/python-api/index.rst
+++ b/docs/python-api/index.rst
@@ -13,3 +13,5 @@ It does not document Python that is not intended for reuse by others (you can re
    process/base.rst
    process/common_tasks/download_data_task.rst
    process/common_tasks/task_with_state.rst
+   models.rst
+
diff --git a/docs/python-api/models.rst b/docs/python-api/models.rst
new file mode 100644
index 0000000..fca8692
--- /dev/null
+++ b/docs/python-api/models.rst
@@ -0,0 +1,13 @@
+Database Models
+===============
+
+
+.. autoclass:: libcoveweb2.models.SuppliedData
+   :members:
+   :exclude-members: DoesNotExist, MultipleObjectsReturned
+
+.. autoclass:: libcoveweb2.models.SuppliedDataFile
+   :members:
+   :exclude-members: DoesNotExist, MultipleObjectsReturned
+
+
diff --git a/libcoveweb2/models.py b/libcoveweb2/models.py
index d3f8f64..18c74e4 100644
--- a/libcoveweb2/models.py
+++ b/libcoveweb2/models.py
@@ -10,16 +10,35 @@
 
 
 class SuppliedData(models.Model):
+    """
+    The Database Model class to represent one set of supplied data sent to
+    the app by a user.
+    This can be one or more files (modelled by the SuppliedDataFile class).
+    """
+
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    """id - an automatically assigned UUID."""
 
     format = models.TextField()
 
     created = models.DateTimeField(auto_now_add=True, null=True)
+    """Date this supplied data was created. Not Null."""
+
     expired = models.DateTimeField(null=True)
+    """Date this supplied data was expired.
+    Nullable for the situation when it hasn't been expired yet.
+
+    Upon expiration, the data on disk will be deleted (to preserve our users privacy)
+    but the database objects left so we have meta data to track usage.
+    """
+
     processed = models.DateTimeField(null=True)
+    """Date this supplied data was expired.
+    Nullable for the situation when it hasn't been processed yet."""
     error = models.TextField(null=True)
 
     """meta is for any extra information that specific cove implementations need.
+
     This lets them store any info without needing changes to core libraries."""
     meta = models.JSONField(null=False, default=dict)
 
@@ -29,10 +48,12 @@ def data_dir(self):
     def storage_dir(self):
         """For use with Django storage classes.
         Returns directory any data about the SuppliedData should be stored in.
+
         Example use:
-        default_storage.exists(
-            os.path.join(supplied_data.storage_dir(), "some_filename.json")
-        )
+
+            default_storage.exists(
+                os.path.join(supplied_data.storage_dir(), "some_filename.json")
+            )
         """
         return str(self.id)
 
@@ -109,15 +130,28 @@ def save_file_from_source_url(
 
 
 class SuppliedDataFile(models.Model):
+    """
+    The Database Model class to represent one file or one set of data
+    sent to the app by a user.
+    A submission by a user (modelled by the SuppliedData class)
+    may have one or more SuppliedDataFile's.
+    """
+
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    """id - an automatically assigned UUID."""
+
     supplied_data = models.ForeignKey(SuppliedData, on_delete=models.CASCADE)
+    """A foreign key that links back to the SuppliedData this file belongs to."""
+
     filename = models.TextField()
     size = models.PositiveBigIntegerField(null=True)
     content_type = models.TextField(null=True)
     charset = models.TextField(null=True)
+
+    meta = models.JSONField(null=False, default=dict)
     """meta is for any extra information that specific cove implementations need.
     This lets them store any info without needing changes to core libraries."""
-    meta = models.JSONField(null=False, default=dict)
+
     source_method = models.TextField(null=True)
     source_url = models.URLField(null=True)
 
@@ -140,9 +174,11 @@ def upload_url(self):
 
     def storage_name(self):
         """For use with Django storage classes.
-        Returns full name in storage
+        Returns full name in storage.
+
         Example use:
-        default_storage.open(os.path.join(supplied_data_file.storage_name())
+
+            default_storage.open(supplied_data_file.storage_name())
         """
         return os.path.join(
             str(self.supplied_data.id),