Merge pull request #102 from lsst-sqre/tickets/DM-37516

DM-37516: Update docstring syntax around types

src/vocutouts/actors.py

@@ -66,21 +66,21 @@ def cutout(
 
     Parameters
     ----------
-    job_id : `str`
+    job_id
         The UWS job ID, used as the key for storing results.
-    dataset_ids : list[`str`]
+    dataset_ids
         The data objects on which to perform cutouts.  These are opaque
         identifiers passed as-is to the backend.  The user will normally
         discover them via some service such as ObsTAP.
-    stencils : list[dict[`str`, Any]]
+    stencils
         Serialized stencils for the cutouts to perform.  These are
         JSON-serializable (a requirement for Dramatiq) representations of the
         `~vocutouts.models.stencils.Stencil` objects corresponding to the
         user's request.
 
     Returns
     -------
-    result : list[dict[`str`, `str`]]
+    list of dict of str to str
         The results of the job.  This must be a list of dict representations
         of `~vocutouts.uws.models.JobResult` objects.
 

src/vocutouts/models/parameters.py

@@ -27,12 +27,12 @@ def from_job_parameters(
 
         Parameters
         ----------
-        params : list[`vocutouts.uws.models.JobParameter`]
+        params
             Generic input job parameters.
 
         Returns
         -------
-        result : `CutoutParameters`
+        CutoutParameters
             The parsed cutout parameters specific to the image cutout service.
 
         Raises

src/vocutouts/policy.py

@@ -26,11 +26,11 @@ class ImageCutoutPolicy(UWSPolicy):
 
     Parameters
     ----------
-    actor : ``dramatiq.Actor``
+    actor
          The actor to call for a job.  This simple mapping is temporary;
          eventually different types of cutouts will dispatch to different
          actors.
-    logger : ``structlog.stdlib.BoundLogger``
+    logger
          Logger to use to report errors when dispatching the request.
     """
 
@@ -44,12 +44,12 @@ def dispatch(self, job: Job) -> Message:
 
         Parameters
         ----------
-        job : `vocutouts.uws.models.Job`
+        job
             The submitted job description.
 
         Returns
         -------
-        message : `dramatiq.Message`
+        dramatiq.Message
             The dispatched message to the backend.
 
         Notes

src/vocutouts/uws/dependencies.py

@@ -106,11 +106,11 @@ async def initialize(
 
         Parameters
         ----------
-        config : `vocutouts.uws.config.UWSConfig`
+        config
             The UWS configuration.
-        policy : `vocutouts.uws.policy.UWSPolicy`
+        policy
             The UWS policy layer.
-        logger : `structlog.stdlib.BoundLogger`
+        logger
             Logger to use during database initialization.  This is not saved;
             subsequent invocations as a dependency will create a new logger
             from the triggering request.
@@ -131,7 +131,7 @@ def override_policy(self, policy: UWSPolicy) -> None:
 
         Parameters
         ----------
-        actor : `vocutouts.uws.policy.UWSPolicy`
+        actor
             The new policy.
         """
         self._policy = policy

src/vocutouts/uws/jobs.py

@@ -56,15 +56,15 @@ def uws_job_started(
 
     Parameters
     ----------
-    job_id : `str`
+    job_id
         The identifier of the job that was started.
-    message_id : `str`
+    message_id
         The message ID of the Dramatiq message that started it.
-    start_time : `datetime.datetime`
+    start_time
         When the job was started.
-    session : `sqlalchemy.orm.scoped_session`
+    session
         A synchronous session to the UWS database.
-    logger : `structlog.stdlib.BoundLogger`
+    logger
         Logger for any messages.
     """
     storage = WorkerJobStore(session)
@@ -85,14 +85,14 @@ def uws_job_completed(
 
     Parameters
     ----------
-    job_id : `str`
+    job_id
         The identifier of the job that was started.
-    result : list[dict[`str`, Any]]
+    result
         The results of the job.  This must be a list of dict representations
         of `~vocutouts.uws.models.JobResult` objects.
-    session : `sqlalchemy.orm.scoped_session`
+    session
         A synchronous session to the UWS database.
-    logger : `structlog.stdlib.BoundLogger`
+    logger
         Logger for any messages.
     """
     storage = WorkerJobStore(session)
@@ -114,13 +114,13 @@ def uws_job_failed(
 
     Parameters
     ----------
-    job_id : `str`
+    job_id
         The identifier of the job that was started.
-    exception : dict[`str`, `str`]
+    exception
         Exception information as passed to a Dramatiq ``on_failure`` callback.
-    session : `sqlalchemy.orm.scoped_session`
+    session
         A synchronous session to the UWS database.
-    logger : `structlog.stdlib.BoundLogger`
+    logger
         Logger for any messages.
     """
     storage = WorkerJobStore(session)

src/vocutouts/uws/policy.py

@@ -36,12 +36,12 @@ def dispatch(self, job: Job) -> Message:
 
         Parameters
         ----------
-        job : `vocutouts.uws.models.Job`
+        job
             The job to start.
 
         Returns
         -------
-        message : `dramatiq.Message`
+        dramatiq.Message
             The message sent to the backend worker.
         """
 
@@ -53,15 +53,15 @@ def validate_destruction(
 
         Parameters
         ----------
-        destruction : `datetime.datetime`
+        destruction
            New date at which the job outputs and its metadata will be
            deleted to recover resources.
-        job : `vocutouts.uws.models.Job`
+        job
             The existing job.
 
         Returns
         -------
-        destruction : `datetime.datetime`
+        datetime.datetime
             The new destruction time for the job, which should be
             ``job.destruction_time`` if the policy layer doesn't want to allow
             any change.
@@ -75,15 +75,15 @@ def validate_execution_duration(
 
         Parameters
         ----------
-        execution_duration : `int`
+        execution_duration
             New desired maximum execution time for the job in wall clock
             seconds.
-        job : `vocutouts.uws.models.Job`
+        job
             The existing job.
 
         Returns
         -------
-        execution_duration : `int`
+        int
             The new execution duration for the job, which should be
             ``job.execution_duration`` if the policy layer doesn't want to
             allow any change.
@@ -95,7 +95,7 @@ def validate_params(self, params: list[JobParameter]) -> None:
 
         Parameters
         ----------
-        params : list[`vocutouts.uws.models.JobParameter`]
+        params
             The new parameters.
 
         Raises

src/vocutouts/uws/results.py

@@ -22,7 +22,7 @@ class ResultStore:
 
     Parameters
     ----------
-    config : `vocutouts.uws.config.UWSConfig`
+    config
         The UWS configuration.
     """
 

src/vocutouts/uws/service.py

@@ -34,12 +34,12 @@ class JobService:
 
     Parameters
     ----------
-    config : `vocutouts.uws.config.UWSConfig`
+    config
         The UWS configuration.
-    policy : `vocutouts.uws.policy.UWSPolicy`
+    policy
         The policy layer for dispatching jobs and validating parameters,
         destruction times, and execution durations.
-    storage : `vocutouts.uws.storage.JobStore`
+    storage
         The underlying storage for job metadata and result tracking.
     """
 
@@ -63,7 +63,7 @@ async def availability(self) -> Availability:
 
         Returns
         -------
-        available : `vocutouts.uws.models.Availability`
+        vocutouts.uws.models.Availability
             Service availability information.
         """
         return await self._storage.availability()
@@ -82,16 +82,16 @@ async def create(
 
         Parameters
         ----------
-        user : `str`
+        user
             User on behalf this operation is performed.
-        run_id : `str`, optional
+        run_id
             A client-supplied opaque identifier to record with the job.
-        params : list[`vocutouts.uws.models.JobParameter`]
+        params
             The input parameters to the job.
 
         Returns
         -------
-        job : `vocutouts.uws.models.Job`
+        vocutouts.uws.models.Job
             The internal representation of the newly-created job.
         """
         self._policy.validate_params(params)
@@ -137,28 +137,28 @@ async def get(
 
         Parameters
         ----------
-        user : `str`
+        user
             User on behalf this operation is performed.
-        job_id : `str`
+        job_id
             Identifier of the job.
-        wait : `int`, optional
+        wait
             If given, wait up to this many seconds for the status to change
             before returning.  ``-1`` says to wait the maximum length of time.
             This is done by polling the database with exponential backoff.
             This will only be honored if the phase is ``PENDING``, ``QUEUED``,
             or ``EXECUTING``.
-        wait_phase : `vocutouts.uws.models.ExecutionPhase`, optional
+        wait_phase
             If ``wait`` was given, the starting phase for waiting.  Returns
             immediately if the initial phase doesn't match this one.
-        wait_for_completion : `bool`, optional
+        wait_for_completion
             If set to true, wait until the job completes (has a phase other
             than ``QUEUED`` or ``EXECUTING``).  Only one of this or
             ``wait_phase`` should be given.  Ignored if ``wait`` was not
             given.
 
         Returns
         -------
-        job : `vocutouts.uws.models.Job`
+        vocutouts.uws.models.Job
             The corresponding job.
 
         Raises
@@ -224,19 +224,19 @@ async def list_jobs(
 
         Parameters
         ----------
-        user : `str`
+        user
             Name of the user whose jobs to load.
-        phases : list[`vocutouts.uws.models.ExecutionPhase`], optional
+        phases
             Limit the result to jobs in this list of possible execution
             phases.
-        after : `datetime.datetime`, optional
+        after
             Limit the result to jobs created after the given datetime.
-        count : `int`, optional
+        count
             Limit the results to the most recent count jobs.
 
         Returns
         -------
-        descriptions : list[`vocutouts.uws.models.JobDescription`]
+        list of vocutouts.uws.models.JobDescription
             List of job descriptions matching the search criteria.
         """
         return await self._storage.list_jobs(
@@ -248,14 +248,14 @@ async def start(self, user: str, job_id: str) -> Message:
 
         Parameters
         ----------
-        user : `str`
+        user
             User on behalf of whom this operation is performed.
-        job_id : `str`
+        job_id
             Identifier of the job to start.
 
         Returns
         -------
-        message : `dramatiq.Message`
+        dramatiq.Message
             The work queuing message representing this job.
 
         Raises
@@ -280,17 +280,17 @@ async def update_destruction(
 
         Parameters
         ----------
-        user : `str`
+        user
             User on behalf of whom this operation is performed
-        job_id : `str`
+        job_id
             Identifier of the job to update.
-        destruction : `datetime.datetime`
+        destruction
             The new job destruction time.  This may be arbitrarily modified
             by the policy layer.
 
         Returns
         -------
-        destruction : `datetime.datetime` or `None`
+        datetime.datetime or None
             The new destruction time of the job (possibly modified by the
             policy layer), or `None` if the destruction time of the job was
             not changed.
@@ -318,17 +318,17 @@ async def update_execution_duration(
 
         Parameters
         ----------
-        user : `str`
+        user
             User on behalf of whom this operation is performed
-        job_id : `str`
+        job_id
             Identifier of the job to update.
-        duration : `int`
+        duration
             The new job execution duration.  This may be arbitrarily modified
             by the policy layer.
 
         Returns
         -------
-        duration : `int` or `None`
+        int or None
             The new execution duration of the job (possibly modified by the
             policy layer), or `None` if the execution duration of the job was
             not changed.