Added comments to a few sections of the code

rframe/data_accessor.py

@@ -1,3 +1,8 @@
+"""
+This code provides a way to interact with a REST API,
+allowing a Python client to query, insert, update, and delete data from the API,
+as well as retrieve summary statistics about the data.
+"""
 import inspect
 import makefun
 import pandas as pd
@@ -11,6 +16,12 @@
 
 
 class DataAccessor:
+    """
+    This class provides an interface for interacting
+    with data in a storage and, utilizes Pydantic for data
+    validation. It provides methods for querying data, adding new data,
+    removing existing data, and for initializing the database.
+    """
     schema: "BaseSchema"
     storage: Any
     initialized: bool = False
@@ -49,7 +60,7 @@ def __init__(self, schema, datasource, initdb=False):
             )
             method = makefun.create_function(signature, impl, func_name=name)
             setattr(self, name[1:], method)
-            
+
         if initdb:
             self.initdb()
 
@@ -102,7 +113,7 @@ def _min(self, fields=None, **labels) -> Any:
             fields = list(self.schema.__fields__)
         elif isinstance(fields, str):
             fields = [fields]
-        
+
         labels = {k: v for k, v in labels.items() if v is not None}
         query = self.schema.compile_query(self.storage, **labels)
 
@@ -156,10 +167,10 @@ def _count(self, **labels):
     def insert(self, docs, raise_on_error=True):
         if not self.initialized:
             self.initdb()
-            
+
         if not isinstance(docs, (list, tuple)):
             docs = [docs]
-        
+
         res = {
             "success": [],
             "failed": [],

rframe/dispatchers.py

@@ -1,4 +1,13 @@
 # type: ignore
+"""
+Due to a variety of reasons, sometimes the '==' symbol does not
+produce the desired results even when 2 qauntities should be considered
+equal, for example due to the  imprecise nature of float point arithmetic
+we could have 2 values that are the same but are treated as different,
+so we can define an 'are_equal' functions to check if the two values
+are 'close enough' to be considered equal.
+"""
+
 
 import math
 from numbers import Number

rframe/rest_client.py

@@ -1,3 +1,9 @@
+"""
+Defines a REST client that can interact with a REST API.
+The client can make requests to the REST AO using HTTPS methods.
+
+"""
+
 import requests
 
 from loguru import logger
@@ -30,6 +36,12 @@ def min(self, fields: List[str]):
 
 
 class RestClient(BaseRestClient):
+    """
+    The RestClient class takes a URL for the REST API, along with optional headers,
+    authentication, and an HTTP client to use.
+    It defines URLs for the various endpoints of the API,
+    and methods for constructing these URLs based on the base URL.
+    """
     QUERY_PATH = "/query"
     INSERT_PATH = "/insert"
     UPDATE_PATH = "/update"

rframe/rest_server.py

@@ -29,6 +29,11 @@
 
 
 class SchemaRouter(APIRouter):
+    """
+     Provides a set of HTTP endpoints for interacting with data stored in a database. The class
+     constructor takes a number of arguments that configure the endpoints, such as the URL path
+     and HTTP methods that each endpoint supports.
+    """
     schema: Type[BaseSchema]
     _base_path: str = "/"
 

rframe/schema.py

@@ -34,6 +34,9 @@ class DeletionError(EditError):
 
 
 class BaseSchema(BaseModel):
+    """
+    Defines the base schema all other schemas will inherit from.
+    """
     class Config:
         validate_assignment = True
 
@@ -50,7 +53,7 @@ def register_datasource(cls, datasource, name='data', initialize=False):
 
         if hasattr(cls, name):
             raise ValueError(f"Datasource name '{name}' is already registered.")
-            
+
         from rframe.data_accessor import DataAccessor
 
         accessor = DataAccessor(cls, datasource, initdb=initialize)
@@ -114,7 +117,7 @@ def get_query_signature(cls, default=None):
                         )
                     params.append(alias_param)
                     break
-                
+
         return inspect.Signature(params)
 
     @classmethod

rframe/types.py

@@ -1,3 +1,9 @@
+"""
+Defines data types that can be useful for the indexing of
+data. In particular this defines the new datatypes which
+will be interval and defines operations within these datatypes.
+"""
+
 import datetime
 import pytz
 from typing import ClassVar, Literal, Mapping, Optional, TypeVar, Union
@@ -192,5 +198,5 @@ def _validate_boundary(cls, value):
 
         if value > cls._max:
             raise ValueError(f"{cls} boundary must be less than {cls._max}.")
-        
+
         return value

rframe/utils.py

@@ -1,4 +1,4 @@
-import re
+import re # https://docs.python.org/3/library/re.html
 import json
 import math
 import inspect
@@ -15,11 +15,17 @@
 
 
 def camel_to_snake(name):
+    # translates sentence concatenated by capitalization
+    # to a sentence concatenates by underscores
+    # Example: HiHowAreYou -> hi_how_are_you
     name = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
     return re.sub("([a-z0-9])([A-Z])", r"\1_\2", name).lower()
 
 
 def snake_to_camel(name):
+    # translates sentence concatenated by underscores
+    # to a sentence concatenates by capitalizations
+    # Example: hi_how_are_you -> HiHowAreYou
     return name.title().replace("_", "")
 
 
@@ -44,6 +50,7 @@ def filter_kwargs(func, kwargs):
 
 
 def jsonable(obj):
+    # Converts objects to json format
 
     if obj is None:
         return obj
@@ -80,6 +87,11 @@ def jsonable(obj):
 
 
 def as_bson_schema(schema, resolver=None):
+    """
+    converts a JSON schema to a BSON schema. BSON is a binary format used to store
+    data in MongoDB, and it is similar to JSON in structure but uses a binary encoding
+    scheme to store the data.
+    """
 
     if not isinstance(schema, dict):
         return schema