Add QueryParams attributes documentation

Update malformed cross-references after rebasing. Move the attributes `provider_prefix` and `provider_fields` from `MongoCollection` to the parent abstract class `EntryCollection`.
Materials-Consortia · Jul 30, 2020 · d759b48 · d759b48
1 parent cf0843b
commit d759b48
Show file tree

Hide file tree

Showing 3 changed files with 105 additions and 8 deletions.
diff --git a/optimade/server/entry_collections/entry_collections.py b/optimade/server/entry_collections/entry_collections.py
@@ -16,7 +16,7 @@
 
 class EntryCollection(ABC):
     """ Backend-agnostic base class for querying collections of
-    [`EntryResource`][optimade.models.EntryResource]s. """
+    [`EntryResource`][optimade.models.entries.EntryResource]s. """
 
     def __init__(
         self,
@@ -44,6 +44,9 @@ def __init__(
         self.resource_mapper = resource_mapper
         self.transformer = transformer
 
+        self.provider_prefix = CONFIG.provider.prefix
+        self.provider_fields = CONFIG.provider_fields.get(resource_mapper.ENDPOINT, [])
+
     @abstractmethod
     def __len__(self) -> int:
         """ Returns the total number of entries in the collection. """
@@ -65,8 +68,9 @@ def find(
         """
         Fetches results and indicates if more data is available.
 
-        Also gives the total number of data available in the absence of
-        [`page_limit`][optimade.server.query_params.EntryListingQueryParams.page_limit].
+        Also gives the total number of data available in the absence of `page_limit`.
+        See [`EntryListingQueryParams`][optimade.server.query_params.EntryListingQueryParams]
+        for more information.
 
         Parameters:
             params (EntryListingQueryParams): entry listing URL query params

diff --git a/optimade/server/entry_collections/mongo.py b/optimade/server/entry_collections/mongo.py
@@ -33,7 +33,7 @@
 
 class MongoCollection(EntryCollection):
     """ Class for querying MongoDB collections (implemented by either pymongo or mongomock)
-    containing serialized [`EntryResource`][optimade.models.EntryResource]s objects.
+    containing serialized [`EntryResource`][optimade.models.entries.EntryResource]s objects.
 
     """
 
@@ -64,8 +64,6 @@ def __init__(
             MongoTransformer(mapper=resource_mapper),
         )
 
-        self.provider_prefix = CONFIG.provider.prefix
-        self.provider_fields = CONFIG.provider_fields.get(resource_mapper.ENDPOINT, [])
         self.parser = LarkParser(
             version=(0, 10, 1), variant="default"
         )  # The MongoTransformer only supports v0.10.1 as the latest grammar

diff --git a/optimade/server/query_params.py b/optimade/server/query_params.py
@@ -5,7 +5,71 @@
 
 
 class EntryListingQueryParams:
-    """Common query params for all Entry listing endpoints."""
+    """
+    Common query params for all Entry listing endpoints.
+
+    Attributes:
+        filter (str): A filter string, in the format described in section API Filtering Format Specification of the specification.
+        response_format (str): The output format requested (see section Response Format).
+            Defaults to the format string 'json', which specifies the standard output format described in this specification.
+            Example: `http://example.com/v1/structures?response_format=xml`
+        email_address (EmailStr): An email address of the user making the request.
+            The email SHOULD be that of a person and not an automatic system.
+            Example: `http://example.com/v1/structures?email_address=user@example.com`
+        response_fields (str): A comma-delimited set of fields to be provided in the output.
+            If provided, these fields MUST be returned along with the REQUIRED fields.
+            Other OPTIONAL fields MUST NOT be returned when this parameter is present.
+            Example: `http://example.com/v1/structures?response_fields=last_modified,nsites`
+        sort (str): If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified
+            by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).
+
+            An implementation MAY support multiple sort fields for a single query.
+            If it does, it again MUST conform to the JSON API 1.0 specification.
+
+            If an implementation supports sorting for an entry listing endpoint, then the `/info/<entries>` endpoint MUST include,
+            for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting,
+            the key `sortable` with value `true`.
+            If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either
+            leave out the `sortable` key or set it equal to `false` for the specific field name.
+            The set of field names, with `sortable` equal to `true` are allowed to be used in the "sort fields" list according to
+            its definition in the JSON API 1.0 specification.
+            The field `sortable` is in addition to each property description and other OPTIONAL fields.
+            An example is shown in the section Entry Listing Info Endpoints.
+        page_limit (int): Sets a numerical limit on the number of entries returned.
+            See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination).
+            The API implementation MUST return no more than the number specified.
+            It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers
+            (in which case an error code -- `403 Forbidden` -- MUST be returned).
+            The default limit value is up to the API implementation to decide.
+            Example: `http://example.com/optimade/v1/structures?page_limit=100`
+        page_offset (int): RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.
+            Example: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.
+        page_number (int): RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.
+            It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.
+            Example: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.
+        page_cursor (int): RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.
+        page_above (int): RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.
+            Example: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by
+            increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.
+        page_below (int): RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.
+        include (str): A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents)
+            by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).
+
+            All related resource objects MUST be returned as part of an array value for the top-level `included` field,
+            see the section JSON Response Schema: Common Fields.
+
+            The value of `include` MUST be a comma-separated list of "relationship paths", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).
+            If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.
+
+            The **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field
+            `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.
+            Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level
+            field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.
+
+            !!! note
+                A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.
+
+    """
 
     def __init__(
         self,
@@ -82,7 +146,38 @@ def __init__(
 
 
 class SingleEntryQueryParams:
-    """Common query params for single entry endpoints."""
+    """
+    Common query params for single entry endpoints.
+
+    Attributes:
+        response_format (str): The output format requested (see section Response Format).
+            Defaults to the format string 'json', which specifies the standard output format described in this specification.
+            Example: `http://example.com/v1/structures?response_format=xml`
+        email_address (EmailStr): An email address of the user making the request.
+            The email SHOULD be that of a person and not an automatic system.
+            Example: `http://example.com/v1/structures?email_address=user@example.com`
+        response_fields (str): A comma-delimited set of fields to be provided in the output.
+            If provided, these fields MUST be returned along with the REQUIRED fields.
+            Other OPTIONAL fields MUST NOT be returned when this parameter is present.
+            Example: `http://example.com/v1/structures?response_fields=last_modified,nsites`
+        include (str): A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents)
+            by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).
+
+            All related resource objects MUST be returned as part of an array value for the top-level `included` field,
+            see the section JSON Response Schema: Common Fields.
+
+            The value of `include` MUST be a comma-separated list of "relationship paths", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).
+            If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.
+
+            The **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field
+            `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.
+            Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level
+            field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.
+
+            !!! note
+                A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.
+
+    """
 
     def __init__(
         self,