Merge pull request #923 from ml-evs/main

Tweak docstrings to fix rendered docs

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
     rev: v0.0.280
     hooks:
       - id: ruff
-        args: [--fix, --show-fixes, --ignore, D]
+        args: [--fix, --show-fixes, --ignore, D, --extend-select, D411]
 
   - repo: https://github.com/psf/black
     rev: 23.7.0

src/maggma/api/API.py

@@ -13,7 +13,7 @@
 
 class API(MSONable):
     """
-    Basic API manager to tie together various resources
+    Basic API manager to tie together various resources.
     """
 
     def __init__(
@@ -34,7 +34,7 @@ def __init__(
             debug: turns debug on in FastAPI
             heartbeat_meta: dictionary of additional metadata to include in the heartbeat response
             description: description of the API to be used in the generated docs
-            tags_meta: descriptions of tags to be used in the generated docs
+            tags_meta: descriptions of tags to be used in the generated docs.
         """
         self.title = title
         self.version = version
@@ -50,7 +50,7 @@ def __init__(
 
     def on_startup(self):
         """
-        Basic startup that runs the resource startup functions
+        Basic startup that runs the resource startup functions.
         """
         for resource_list in self.resources.values():
             for resource in resource_list:
@@ -59,7 +59,7 @@ def on_startup(self):
     @property
     def app(self):
         """
-        App server for the cluster manager
+        App server for the cluster manager.
         """
         app = FastAPI(
             title=self.title,
@@ -92,7 +92,7 @@ def app(self):
 
         @app.get("/heartbeat", include_in_schema=False)
         def heartbeat():
-            """API Heartbeat for Load Balancing"""
+            """API Heartbeat for Load Balancing."""
 
             return {
                 "status": "OK",
@@ -103,14 +103,14 @@ def heartbeat():
 
         @app.get("/", include_in_schema=False)
         def redirect_docs():
-            """Redirects the root end point to the docs"""
+            """Redirects the root end point to the docs."""
             return RedirectResponse(url=app.docs_url, status_code=301)
 
         return app
 
     def run(self, ip: str = "127.0.0.1", port: int = 8000, log_level: str = "info"):
         """
-        Runs the Cluster Manager locally
+        Runs the Cluster Manager locally.
 
         Args:
             ip: Local IP to listen on

src/maggma/api/__init__.py

@@ -1 +1 @@
-""" Simple API Interface for Maggma """
+""" Simple API Interface for Maggma. """

src/maggma/api/models.py

@@ -14,7 +14,7 @@
 class Meta(BaseModel):
 
     """
-    Meta information for the MAPI Response
+    Meta information for the MAPI Response.
     """
 
     api_version: str = Field(
@@ -35,7 +35,7 @@ class Config:
 
 class Error(BaseModel):
     """
-    Base Error model for General API
+    Base Error model for General API.
     """
 
     code: int = Field(..., description="The error code")
@@ -48,7 +48,7 @@ def from_traceback(cls, traceback):
 
 class Response(BaseModel, Generic[DataT]):
     """
-    A Generic API Response
+    A Generic API Response.
     """
 
     data: Optional[List[DataT]] = Field(None, description="List of returned data")
@@ -78,7 +78,7 @@ def default_meta(cls, v, values):
 class S3URLDoc(BaseModel):
 
     """
-    S3 pre-signed URL data returned by the S3 URL resource
+    S3 pre-signed URL data returned by the S3 URL resource.
     """
 
     url: str = Field(

src/maggma/api/query_operator/core.py

@@ -9,18 +9,18 @@
 class QueryOperator(MSONable, metaclass=ABCMeta):
     """
     Base Query Operator class for defining powerful query language
-    in the Materials API
+    in the Materials API.
     """
 
     @abstractmethod
     def query(self) -> STORE_PARAMS:
         """
-        The query function that does the work for this query operator
+        The query function that does the work for this query operator.
         """
 
     def meta(self) -> Dict:
         """
-        Returns meta data to return with the Response
+        Returns meta data to return with the Response.
 
         Args:
             store: the Maggma Store that the resource uses
@@ -30,7 +30,7 @@ def meta(self) -> Dict:
 
     def post_process(self, docs: List[Dict], query: Dict) -> List[Dict]:
         """
-        An optional post-processing function for the data
+        An optional post-processing function for the data.
 
         Args:
             docs: the document results to post-process

src/maggma/api/query_operator/dynamic.py

@@ -13,7 +13,7 @@
 
 
 class DynamicQueryOperator(QueryOperator):
-    """Abstract Base class for dynamic query operators"""
+    """Abstract Base class for dynamic query operators."""
 
     def __init__(
         self,
@@ -75,7 +75,7 @@ def query(**kwargs) -> STORE_PARAMS:
         self.query = query  # type: ignore
 
     def query(self):
-        "Stub query function for abstract class"
+        "Stub query function for abstract class."
 
     @abstractmethod
     def field_to_operator(self, name: str, field: FieldInfo) -> List[Tuple[str, Any, Query, Callable[..., Dict]]]:
@@ -84,7 +84,7 @@ def field_to_operator(self, name: str, field: FieldInfo) -> List[Tuple[str, Any,
             - query param name,
             - query param type
             - FastAPI Query object,
-            - and callable to convert the value into a query dict
+            - and callable to convert the value into a query dict.
         """
 
     @classmethod
@@ -97,23 +97,23 @@ def from_dict(cls, d):
 
     def as_dict(self) -> Dict:
         """
-        Special as_dict implemented to convert pydantic models into strings
+        Special as_dict implemented to convert pydantic models into strings.
         """
         d = super().as_dict()  # Ensures sub-classes serialize correctly
         d["model"] = f"{self.model.__module__}.{self.model.__name__}"  # type: ignore
         return d
 
 
 class NumericQuery(DynamicQueryOperator):
-    "Query Operator to enable searching on numeric fields"
+    "Query Operator to enable searching on numeric fields."
 
     def field_to_operator(self, name: str, field: FieldInfo) -> List[Tuple[str, Any, Query, Callable[..., Dict]]]:
         """
         Converts a PyDantic FieldInfo into a Tuple with the
         query_param name,
         default value,
         Query object,
-        and callable to convert it into a query dict
+        and callable to convert it into a query dict.
         """
 
         ops = []
@@ -190,15 +190,15 @@ def field_to_operator(self, name: str, field: FieldInfo) -> List[Tuple[str, Any,
 
 
 class StringQueryOperator(DynamicQueryOperator):
-    "Query Operator to enable searching on numeric fields"
+    "Query Operator to enable searching on numeric fields."
 
     def field_to_operator(self, name: str, field: FieldInfo) -> List[Tuple[str, Any, Query, Callable[..., Dict]]]:
         """
         Converts a PyDantic FieldInfo into a Tuple with the
         query_param name,
         default value,
         Query object,
-        and callable to convert it into a query dict
+        and callable to convert it into a query dict.
         """
 
         ops = []

src/maggma/api/query_operator/pagination.py

@@ -7,13 +7,13 @@
 
 
 class PaginationQuery(QueryOperator):
-    """Query operators to provides Pagination"""
+    """Query operators to provides Pagination."""
 
     def __init__(self, default_limit: int = 100, max_limit: int = 1000):
         """
         Args:
             default_limit: the default number of documents to return
-            max_limit: max number of documents to return
+            max_limit: max number of documents to return.
         """
 
         self.default_limit = default_limit
@@ -39,7 +39,7 @@ def query(
             ),
         ) -> STORE_PARAMS:
             """
-            Pagination parameters for the API Endpoint
+            Pagination parameters for the API Endpoint.
             """
 
             if _page is not None:
@@ -80,10 +80,10 @@ def query(
         self.query = query  # type: ignore
 
     def query(self):
-        "Stub query function for abstract class"
+        "Stub query function for abstract class."
 
     def meta(self) -> Dict:
         """
-        Metadata for the pagination params
+        Metadata for the pagination params.
         """
         return {"max_limit": self.max_limit}

src/maggma/api/query_operator/sorting.py

@@ -8,7 +8,7 @@
 
 class SortQuery(QueryOperator):
     """
-    Method to generate the sorting portion of a query
+    Method to generate the sorting portion of a query.
     """
 
     def query(

src/maggma/api/query_operator/sparse_fields.py

@@ -13,7 +13,7 @@ def __init__(self, model: Type[BaseModel], default_fields: Optional[List[str]] =
         """
         Args:
             model: PyDantic Model that represents the underlying data source
-            default_fields: default fields to return in the API response if no fields are explicitly requested
+            default_fields: default fields to return in the API response if no fields are explicitly requested.
         """
 
         self.model = model
@@ -32,7 +32,7 @@ def query(
             _all_fields: bool = Query(False, description="Include all fields."),
         ) -> STORE_PARAMS:
             """
-            Pagination parameters for the API Endpoint
+            Pagination parameters for the API Endpoint.
             """
 
             properties = _fields.split(",") if isinstance(_fields, str) else self.default_fields
@@ -44,17 +44,17 @@ def query(
         self.query = query  # type: ignore
 
     def query(self):
-        "Stub query function for abstract class"
+        "Stub query function for abstract class."
 
     def meta(self) -> Dict:
         """
-        Returns metadata for the Sparse field set
+        Returns metadata for the Sparse field set.
         """
         return {"default_fields": self.default_fields}
 
     def as_dict(self) -> Dict:
         """
-        Special as_dict implemented to convert pydantic models into strings
+        Special as_dict implemented to convert pydantic models into strings.
         """
 
         d = super().as_dict()  # Ensures sub-classes serialize correctly
@@ -64,7 +64,7 @@ def as_dict(self) -> Dict:
     @classmethod
     def from_dict(cls, d):
         """
-        Special from_dict to autoload the pydantic model from the location string
+        Special from_dict to autoload the pydantic model from the location string.
         """
         model = d.get("model")
         if isinstance(model, str):

src/maggma/api/query_operator/submission.py

@@ -9,7 +9,7 @@
 
 class SubmissionQuery(QueryOperator):
     """
-    Method to generate a query for submission data using status and datetime
+    Method to generate a query for submission data using status and datetime.
     """
 
     def __init__(self, status_enum):
@@ -40,4 +40,4 @@ def query(
         self.query = query
 
     def query(self):
-        "Stub query function for abstract class"
+        "Stub query function for abstract class."

src/maggma/api/resource/aggregation.py

@@ -17,7 +17,7 @@
 
 class AggregationResource(Resource):
     """
-    Implements a REST Compatible Resource as a GET URL endpoint
+    Implements a REST Compatible Resource as a GET URL endpoint.
     """
 
     def __init__(
@@ -58,7 +58,7 @@ def __init__(
     def prepare_endpoint(self):
         """
         Internal method to prepare the endpoint by setting up default handlers
-        for routes
+        for routes.
         """
 
         self.build_dynamic_model_search()