From 1186d51086b69a28079b6039ba09e9c6e926d99d Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 24 Jun 2020 13:13:45 +0100 Subject: [PATCH] Applied changes from code review Co-authored-by: Adam Fekete --- openapi/index_openapi.json | 10 +++++----- openapi/openapi.json | 16 ++++++++-------- optimade/models/jsonapi.py | 4 ++-- optimade/models/optimade_json.py | 8 ++++---- optimade/models/references.py | 2 +- optimade/models/structures.py | 8 +++++--- 6 files changed, 25 insertions(+), 23 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 8398e289f2..c0c04d2c49 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -1422,7 +1422,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON API resources." + "description": "Relationships object describing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -1477,19 +1477,19 @@ "api_version": { "title": "Api Version", "type": "string", - "description": "a string containing the version of the API implementation, e.g. v0.9.5" + "description": "A string containing the version of the API implementation, e.g. v0.9.5" }, "time_stamp": { "title": "Time Stamp", "type": "string", - "description": "a timestamp containing the date and time at which the query was executed.", + "description": "A timestamp containing the date and time at which the query was executed.", "format": "date-time" }, "data_returned": { "title": "Data Returned", "minimum": 0.0, "type": "integer", - "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." + "description": "An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." }, "more_data_available": { "title": "More Data Available", @@ -1508,7 +1508,7 @@ "data_available": { "title": "Data Available", "type": "integer", - "description": "an integer containing the total number of data resource objects available in the database for the endpoint." + "description": "An integer containing the total number of data resource objects available in the database for the endpoint." }, "last_id": { "title": "Last Id", diff --git a/openapi/openapi.json b/openapi/openapi.json index ee8fce8932..7372e84555 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1037,7 +1037,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON API resources." + "description": "Relationships object describing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -2596,7 +2596,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON API resources." + "description": "Relationships object describing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -2651,19 +2651,19 @@ "api_version": { "title": "Api Version", "type": "string", - "description": "a string containing the version of the API implementation, e.g. v0.9.5" + "description": "A string containing the version of the API implementation, e.g. v0.9.5" }, "time_stamp": { "title": "Time Stamp", "type": "string", - "description": "a timestamp containing the date and time at which the query was executed.", + "description": "A timestamp containing the date and time at which the query was executed.", "format": "date-time" }, "data_returned": { "title": "Data Returned", "minimum": 0.0, "type": "integer", - "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." + "description": "An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." }, "more_data_available": { "title": "More Data Available", @@ -2682,7 +2682,7 @@ "data_available": { "title": "Data Available", "type": "integer", - "description": "an integer containing the total number of data resource objects available in the database for the endpoint." + "description": "An integer containing the total number of data resource objects available in the database for the endpoint." }, "last_id": { "title": "Last Id", @@ -2849,7 +2849,7 @@ "type": { "title": "Type", "type": "string", - "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`" + "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`" }, "links": { "title": "Links", @@ -2925,7 +2925,7 @@ "nelements": { "title": "Nelements", "type": "integer", - "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Example**: `3`\n\n- **Querying**:\n - Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n - A filter that matches structures that have exactly 4 elements: `nelements=4`.\n - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`." + "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\n - Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n - A filter that matches structures that have exactly 4 elements: `nelements=4`.\n - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`." }, "elements_ratios": { "title": "Elements Ratios", diff --git a/optimade/models/jsonapi.py b/optimade/models/jsonapi.py index e5ca557b96..080a26b2dc 100644 --- a/optimade/models/jsonapi.py +++ b/optimade/models/jsonapi.py @@ -137,7 +137,7 @@ class BaseResource(BaseModel): class RelationshipLinks(BaseModel): - """ A resource object **MAY** contain references to other resource objects (\"relationships\"). + """A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object. @@ -255,7 +255,7 @@ class Resource(BaseResource): ) relationships: Optional[Relationships] = Field( None, - description="a relationships object describing relationships between the resource and other JSON API resources.", + description="Relationships object describing relationships between the resource and other JSON API resources.", ) diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index 54c7f6a31f..3e16c3439a 100644 --- a/optimade/models/optimade_json.py +++ b/optimade/models/optimade_json.py @@ -238,17 +238,17 @@ class ResponseMeta(jsonapi.Meta): api_version: str = Field( ..., - description="a string containing the version of the API implementation, e.g. v0.9.5", + description="A string containing the version of the API implementation, e.g. v0.9.5", ) time_stamp: datetime = Field( ..., - description="a timestamp containing the date and time at which the query was executed.", + description="A timestamp containing the date and time at which the query was executed.", ) data_returned: int = Field( ..., - description="an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.", + description="An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.", ge=0, ) @@ -263,7 +263,7 @@ class ResponseMeta(jsonapi.Meta): data_available: Optional[int] = Field( None, - description="an integer containing the total number of data resource objects available in the database for the endpoint.", + description="An integer containing the total number of data resource objects available in the database for the endpoint.", ) last_id: Optional[str] = Field( diff --git a/optimade/models/references.py b/optimade/models/references.py index 9f24dfcc6e..0ce04ccb2f 100644 --- a/optimade/models/references.py +++ b/optimade/models/references.py @@ -111,7 +111,7 @@ class ReferenceResourceAttributes(EntryResourceAttributes): class ReferenceResource(EntryResource): - """ The `references` entries describe bibliographic references. + """The `references` entries describe bibliographic references. The following properties are used to provide the bibliographic details: - **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings; diff --git a/optimade/models/structures.py b/optimade/models/structures.py index c11ed691a5..d944fae904 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -45,7 +45,7 @@ class StructureFeatures(Enum): class Species(BaseModel): - """ A list describing the species of the sites of this structure. + """A list describing the species of the sites of this structure. Species can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are @@ -245,7 +245,8 @@ class StructureResourceAttributes(EntryResourceAttributes): - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. - **Query**: MUST be a queryable property with support for all mandatory filter features. -- **Example**: `3` +- **Examples**: + - `3` - **Querying**: - Note: queries on this property can equivalently be formulated using `elements LENGTH`. @@ -884,7 +885,8 @@ class StructureResource(EntryResource): - MUST be an existing entry type. - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL. -- **Example**: `"structures"`""", +- **Examples**: + - `"structures"`""", ) attributes: StructureResourceAttributes