From be1a6989cff0c4cfa677da2260949c91dc88b78a Mon Sep 17 00:00:00 2001 From: Luis Sanchez <45677170+LuisSanchez25@users.noreply.github.com> Date: Tue, 25 Apr 2023 01:32:34 -0500 Subject: [PATCH] Added comments to a few sections of the code --- rframe/data_accessor.py | 19 +++++++++++++++---- rframe/dispatchers.py | 9 +++++++++ rframe/rest_client.py | 12 ++++++++++++ rframe/rest_server.py | 5 +++++ rframe/schema.py | 7 +++++-- rframe/types.py | 8 +++++++- rframe/utils.py | 14 +++++++++++++- 7 files changed, 66 insertions(+), 8 deletions(-) diff --git a/rframe/data_accessor.py b/rframe/data_accessor.py index b9232fd..43b8956 100644 --- a/rframe/data_accessor.py +++ b/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": [], diff --git a/rframe/dispatchers.py b/rframe/dispatchers.py index d1a9042..6271f39 100644 --- a/rframe/dispatchers.py +++ b/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 diff --git a/rframe/rest_client.py b/rframe/rest_client.py index 7e20a98..21124fb 100644 --- a/rframe/rest_client.py +++ b/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" diff --git a/rframe/rest_server.py b/rframe/rest_server.py index 4d735bc..2313337 100644 --- a/rframe/rest_server.py +++ b/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 = "/" diff --git a/rframe/schema.py b/rframe/schema.py index 1c8ff12..de29c9d 100644 --- a/rframe/schema.py +++ b/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 diff --git a/rframe/types.py b/rframe/types.py index 333ff0b..5e39d94 100644 --- a/rframe/types.py +++ b/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 diff --git a/rframe/utils.py b/rframe/utils.py index 997ed78..6aef72f 100644 --- a/rframe/utils.py +++ b/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