Replace field docstring with Pydantic Field Description to appear in schemas

Author: BenjaminCharmes

pydatalab/schemas/cell.json

@@ -33,32 +33,41 @@ class Cell(Item):
 
     type: Literal["cells"] = "cells"
 
-    cell_format: CellFormat | None = None
-    """The form factor of the cell, e.g., coin, pouch, in situ or otherwise."""
-
-    cell_format_description: str | None = None
-    """Additional human-readable description of the cell form factor, e.g., 18650, AMPIX, CAMPIX"""
-
-    cell_preparation_description: str | None = None
-    """Description of how the cell was prepared."""
-
-    characteristic_mass: float | None = None
-    """The characteristic mass of the cell in milligrams. Can be used to normalize capacities."""
-
-    characteristic_chemical_formula: str | None = None
-    """The chemical formula of the active material. Can be used to calculated molar mass in g/mol for normalizing capacities."""
-
-    characteristic_molar_mass: float | None = None
-    """The molar mass of the active material, in g/mol. Will be inferred from the chemical formula, or can be supplied if it cannot be supplied"""
+    cell_format: CellFormat | None = Field(
+        None, description="The form factor of the cell, e.g., coin, pouch, in situ or otherwise."
+    )
+
+    cell_format_description: str | None = Field(
+        None,
+        description="Additional human-readable description of the cell form factor, e.g., 18650, AMPIX, CAMPIX",
+    )
+
+    cell_preparation_description: str | None = Field(
+        None, description="Description of how the cell was prepared."
+    )
+
+    characteristic_mass: float | None = Field(
+        None,
+        description="The characteristic mass of the cell in milligrams. Can be used to normalize capacities.",
+    )
+
+    characteristic_chemical_formula: str | None = Field(
+        None,
+        description="The chemical formula of the active material. Can be used to calculated molar mass in g/mol for normalizing capacities.",
+    )
+
+    characteristic_molar_mass: float | None = Field(
+        None,
+        description="The molar mass of the active material, in g/mol. Will be inferred from the chemical formula, or can be supplied if it cannot be supplied",
+    )
 
     positive_electrode: list[CellComponent] = Field(default_factory=list)
     negative_electrode: list[CellComponent] = Field(default_factory=list)
     electrolyte: list[CellComponent] = Field(default_factory=list)
 
     active_ion_charge: float = 1
 
-    active_ion: str | None = None
-    """The active ion species."""
+    active_ion: str | None = Field(None, description="The active ion species.")
 
     @field_validator("characteristic_molar_mass", mode="before")
     @classmethod

pydatalab/schemas/equipment.json

@@ -13,17 +13,20 @@
 class Collection(Entry, HasOwner, HasBlocks):
     type: Literal["collections"] = "collections"
 
-    collection_id: HumanReadableIdentifier = Field(None)
-    """A short human-readable/usable name for the collection."""
+    collection_id: HumanReadableIdentifier = Field(
+        None, description="A short human-readable/usable name for the collection."
+    )
 
-    title: str | None = None
-    """A descriptive title for the collection."""
+    title: str | None = Field(None, description="A descriptive title for the collection.")
 
-    description: str | None = None
-    """A description of the collection, either in plain-text or a markup language."""
+    description: str | None = Field(
+        None,
+        description="A description of the collection, either in plain-text or a markup language.",
+    )
 
-    num_items: int | None = Field(None)
-    """Inlined number of items associated with this collection."""
+    num_items: int | None = Field(
+        None, description="Inlined number of items associated with this collection."
+    )
 
     @model_validator(mode="before")
     @classmethod

pydatalab/schemas/sample.json

@@ -16,22 +16,23 @@ class Entry(BaseModel, abc.ABC):
 
     """
 
-    type: str
-    """The resource type of the entry."""
+    type: str = Field(description="The resource type of the entry.")
 
     immutable_id: PyObjectId | None = Field(
         None,
         title="Immutable ID",
         alias="_id",
         json_schema_extra={"format": "uuid"},
+        description="The immutable database ID of the entry.",
     )
-    """The immutable database ID of the entry."""
 
-    last_modified: IsoformatDateTime | None = None
-    """The timestamp at which the entry was last modified."""
+    last_modified: IsoformatDateTime | None = Field(
+        None, description="The timestamp at which the entry was last modified."
+    )
 
-    relationships: list[TypedRelationship] = Field(default_factory=list)
-    """A list of related entries and their types."""
+    relationships: list[TypedRelationship] = Field(
+        default_factory=list, description="A list of related entries and their types."
+    )
 
     @model_validator(mode="before")
     @classmethod

pydatalab/schemas/startingmaterial.json

@@ -1,5 +1,7 @@
 from typing import Literal
 
+from pydantic import Field
+
 from pydatalab.models.items import Item
 
 
@@ -8,14 +10,16 @@ class Equipment(Item):
 
     type: Literal["equipment"] = "equipment"
 
-    serial_numbers: str | None = None
-    """A string describing one or more serial numbers for the instrument."""
+    serial_numbers: str | None = Field(
+        None, description="A string describing one or more serial numbers for the instrument."
+    )
 
-    manufacturer: str | None = None
-    """The manufacturer of this piece of equipment"""
+    manufacturer: str | None = Field(
+        None, description="The manufacturer of this piece of equipment"
+    )
 
-    location: str | None = None
-    """Place where the equipment is located"""
+    location: str | None = Field(None, description="Place where the equipment is located")
 
-    contact: str | None = None
-    """Contact information for equipment (e.g., email address or phone number)."""
+    contact: str | None = Field(
+        None, description="Contact information for equipment (e.g., email address or phone number)."
+    )

pydatalab/src/pydatalab/models/cells.py

@@ -12,49 +12,48 @@ class File(Entry, HasOwner, HasRevisionControl):
 
     type: Literal["files"] = "files"
 
-    size: int | None = None
-    """The size of the file on disk in bytes."""
+    size: int | None = Field(None, description="The size of the file on disk in bytes.")
 
-    last_modified_remote: IsoformatDateTime | None = None
-    """The last date/time at which the remote file was modified."""
+    last_modified_remote: IsoformatDateTime | None = Field(
+        None, description="The last date/time at which the remote file was modified."
+    )
 
-    item_ids: list[str] = Field(default_factory=list)
-    """A list of item IDs associated with this file."""
+    item_ids: list[str] = Field(
+        default_factory=list, description="A list of item IDs associated with this file."
+    )
 
-    blocks: list[str] = Field(default_factory=list)
-    """A list of block IDs associated with this file."""
+    blocks: list[str] = Field(
+        default_factory=list, description="A list of block IDs associated with this file."
+    )
 
-    name: str
-    """The filename on disk."""
+    name: str = Field(description="The filename on disk.")
 
-    extension: str
-    """The file extension that the file was uploaded with."""
+    extension: str = Field(description="The file extension that the file was uploaded with.")
 
-    original_name: str | None = None
-    """The raw filename as uploaded."""
+    original_name: str | None = Field(None, description="The raw filename as uploaded.")
 
-    location: str | None = None
-    """The location of the file on disk."""
+    location: str | None = Field(None, description="The location of the file on disk.")
 
-    url_path: str | None = None
-    """The path to a remote file."""
+    url_path: str | None = Field(None, description="The path to a remote file.")
 
-    source: str | None = None
-    """The source of the file, e.g. 'remote' or 'uploaded'."""
+    source: str | None = Field(
+        None, description="The source of the file, e.g. 'remote' or 'uploaded'."
+    )
 
-    time_added: IsoformatDateTime
-    """The timestamp for the original file upload."""
+    time_added: IsoformatDateTime = Field(description="The timestamp for the original file upload.")
 
-    metadata: dict[Any, Any] | None = None
-    """Any additional metadata."""
+    metadata: dict[Any, Any] | None = Field(None, description="Any additional metadata.")
 
     representation: Any | None = None
 
-    source_server_name: str | None = None
-    """The server name at which the file is stored."""
+    source_server_name: str | None = Field(
+        None, description="The server name at which the file is stored."
+    )
 
-    source_path: str | None = None
-    """The path to the file on the remote resource."""
+    source_path: str | None = Field(
+        None, description="The path to the file on the remote resource."
+    )
 
-    is_live: bool
-    """Whether or not the file should be watched for future updates."""
+    is_live: bool = Field(
+        description="Whether or not the file should be watched for future updates."
+    )

pydatalab/src/pydatalab/models/collections.py

@@ -21,28 +21,33 @@
 class Item(Entry, HasOwner, HasRevisionControl, IsCollectable, HasBlocks, abc.ABC):
     """The generic model for data types that will be exposed with their own named endpoints."""
 
-    refcode: Refcode | None = None  # type: ignore
-    """A globally unique immutable ID comprised of the deployment prefix (e.g., `grey`)
-    and a locally unique string, ideally created with some consistent scheme.
-    """
+    refcode: Refcode | None = Field(
+        None,
+        description="A globally unique immutable ID comprised of the deployment prefix (e.g., `grey`) and a locally unique string, ideally created with some consistent scheme.",
+    )
 
-    item_id: HumanReadableIdentifier
-    """A locally unique, human-readable identifier for the entry. This ID is mutable."""
+    item_id: HumanReadableIdentifier = Field(
+        description="A locally unique, human-readable identifier for the entry. This ID is mutable."
+    )
 
-    description: str | None = None
-    """A description of the item, either in plain-text or a markup language."""
+    description: str | None = Field(
+        None, description="A description of the item, either in plain-text or a markup language."
+    )
 
-    date: IsoformatDateTime | None = None
-    """A relevant 'creation' timestamp for the entry (e.g., purchase date, synthesis date)."""
+    date: IsoformatDateTime | None = Field(
+        None,
+        description="A relevant 'creation' timestamp for the entry (e.g., purchase date, synthesis date).",
+    )
 
-    name: str | None = None
-    """An optional human-readable/usable name for the entry."""
+    name: str | None = Field(
+        None, description="An optional human-readable/usable name for the entry."
+    )
 
-    files: list[File] | None = None
-    """Any files attached to this sample."""
+    files: list[File] | None = Field(None, description="Any files attached to this sample.")
 
-    file_ObjectIds: list[PyObjectId] = Field(default_factory=list)
-    """Links to object IDs of files stored within the database."""
+    file_ObjectIds: list[PyObjectId] = Field(
+        default_factory=list, description="Links to object IDs of files stored within the database."
+    )
 
     @field_validator("refcode", mode="before")
     @classmethod