Enh/attachments

README.md

@@ -20,6 +20,13 @@ To develop the code, run
 pip install -e .[dev]
 ```
 
+## Usage
+
+### VScode
+![](example-usage.gif)
+
+Requires the pylance extension to be installed.
+
 ## Contributing
 
 ### Linters and testing

src/aind_slims_api/__init__.py

@@ -7,3 +7,28 @@
 config = AindSlimsApiSettings()
 
 from aind_slims_api.core import SlimsClient  # noqa
+
+
+def testmod(**testmod_kwargs):
+    """
+    Run doctests for the module, configured to ignore exception details and
+    normalize whitespace. Also sets logging level to DEBUG.
+
+    Accepts kwargs to pass to doctest.testmod().
+
+    Add to modules to run doctests when run as a script:
+    .. code-block:: text
+        if __name__ == "__main__":
+            from npc_io import testmod
+            testmod()
+
+    """
+    import doctest
+    import logging
+
+    logging.basicConfig(level=logging.DEBUG)
+
+    _ = testmod_kwargs.setdefault(
+        "optionflags", doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
+    )
+    doctest.testmod(**testmod_kwargs)

src/aind_slims_api/behavior_session.py

@@ -3,22 +3,39 @@
 """
 
 import logging
-from typing import Any
 from datetime import datetime
+from typing import ClassVar
 
 from pydantic import Field
 
-from aind_slims_api.core import SlimsBaseModel, SlimsClient, SLIMSTABLES
+from aind_slims_api.core import SlimsBaseModel, SlimsClient
+from aind_slims_api.instrument import SlimsInstrument
+from aind_slims_api.mouse import SlimsMouseContent
+from aind_slims_api.user import SlimsUser
 
 logger = logging.getLogger()
 
 
 class SlimsBehaviorSessionContentEvent(SlimsBaseModel):
-    """Model for an instance of the Behavior Session ContentEvent"""
+    """Model for an instance of the Behavior Session ContentEvent
+
+    Examples
+    --------
+    >>> from aind_slims_api.core import SlimsClient
+    >>> from aind_slims_api.mouse import SlimsMouseContent
+    >>> client = SlimsClient()
+    >>> mouse = client.fetch_model(SlimsMouseContent, barcode="00000000")
+    >>> behavior_sessions = client.fetch_models(SlimsBehaviorSessionContentEvent,
+    ...  mouse_pk=mouse.pk, sort=["date"])
+    """
 
     pk: int | None = Field(default=None, alias="cnvn_pk")
     mouse_pk: int | None = Field(
-        default=None, alias="cnvn_fk_content"
+        default=None,
+        alias="cnvn_fk_content",
+        description=(
+            "The primary key of the mouse associated with this behavior session."
+        ),
     )  # used as reference to mouse
     notes: str | None = Field(default=None, alias="cnvn_cf_notes")
     task_stage: str | None = Field(default=None, alias="cnvn_cf_taskStage")
@@ -32,67 +49,19 @@ class SlimsBehaviorSessionContentEvent(SlimsBaseModel):
         default=None, alias="cnvn_cf_taskSchemaVersion"
     )
     software_version: str | None = Field(default=None, alias="cnvn_cf_softwareVersion")
-    date: datetime | None = Field(..., alias="cnvn_cf_scheduledDate")
-
+    date: datetime | None = Field(default=None, alias="cnvn_cf_scheduledDate")
     cnvn_fk_contentEventType: int = 10  # pk of Behavior Session ContentEvent
-
-    _slims_table: SLIMSTABLES = "ContentEvent"
-
-
-SlimsSingletonFetchReturn = SlimsBaseModel | dict[str, Any] | None
-
-
-def _resolve_pk(
-    model: SlimsSingletonFetchReturn,
-    primary_key_name: str = "pk",
-) -> int:
-    """Utility function shared across read/write
-
-    Notes
-    -----
-    - TODO: Change return type of fetch_mouse_content to match pattern in
-     fetch_behavior_session_content_events, or the other way around?
-    - TODO: Move to core to have better centralized control of when references
-     are resolved
-    """
-    if isinstance(model, dict):
-        logger.warning("Extracting primary key from unvalidated dict.")
-        return model[primary_key_name]
-    elif isinstance(model, SlimsBaseModel):
-        return getattr(model, primary_key_name)
-    elif model is None:
-        raise ValueError(f"Cannot resolve primary key from {model}")
-    else:
-        raise ValueError("Unexpected type for model: %s" % type(model))
-
-
-def fetch_behavior_session_content_events(
-    client: SlimsClient,
-    mouse: SlimsSingletonFetchReturn,
-) -> tuple[list[SlimsBehaviorSessionContentEvent], list[dict[str, Any]]]:
-    """Fetches behavior sessions for a mouse with labtracks id {mouse_name}
-
-    Returns
-    -------
-    tuple:
-        list:
-            Validated SlimsBehaviorSessionContentEvent objects
-        list:
-            Dictionaries representations of objects that failed validation
-    """
-    return client.fetch_models(
-        SlimsBehaviorSessionContentEvent,
-        cnvn_fk_content=_resolve_pk(mouse),
-        cnvt_name="Behavior Session",
-        sort=["cnvn_cf_scheduledDate"],
-    )
+    _slims_table = "ContentEvent"
+    _base_fetch_filters: ClassVar[dict[str, str]] = {
+        "cnvt_name": "Behavior Session",
+    }
 
 
 def write_behavior_session_content_events(
     client: SlimsClient,
-    mouse: SlimsSingletonFetchReturn,
-    instrument: SlimsSingletonFetchReturn,
-    trainers: list[SlimsSingletonFetchReturn],
+    mouse: SlimsMouseContent,
+    instrument: SlimsInstrument,
+    trainers: list[SlimsUser],
     *behavior_sessions: SlimsBehaviorSessionContentEvent,
 ) -> list[SlimsBehaviorSessionContentEvent]:
     """Writes behavior sessions for a mouse with labtracks id {mouse_name}
@@ -102,22 +71,24 @@ def write_behavior_session_content_events(
     - All supplied `behavior_sessions` will have their `mouse_name` field set
      to the value supplied as `mouse_name` to this function
     """
-    mouse_pk = _resolve_pk(mouse)
-    logger.debug(f"Mouse pk: {mouse_pk}")
-    instrument_pk = _resolve_pk(instrument)
-    logger.debug(f"Instrument pk: {instrument_pk}")
-    trainer_pks = [_resolve_pk(trainer) for trainer in trainers]
+    trainer_pks = [trainer.pk for trainer in trainers]
     logger.debug(f"Trainer pks: {trainer_pks}")
     added = []
     for behavior_session in behavior_sessions:
         updated = behavior_session.model_copy(
             update={
-                "mouse_pk": mouse_pk,
-                "instrument": instrument_pk,
+                "mouse_pk": mouse.pk,
+                "instrument": instrument.pk,
                 "trainers": trainer_pks,
             },
         )
         logger.debug(f"Resolved behavior session: {updated}")
         added.append(client.add_model(updated))
 
     return added
+
+
+if __name__ == "__main__":
+    from aind_slims_api import testmod
+
+    testmod()

src/aind_slims_api/configuration.py

@@ -13,4 +13,4 @@ class AindSlimsApiSettings(BaseSettings):
 
     slims_url: str = "https://aind-test.us.slims.agilent.com/slimsrest/"
     slims_username: str = ""
-    slims_password: SecretStr = ""
+    slims_password: SecretStr = SecretStr("")