From 6412bba7c77193b50591ec0a7e0ba1cf80357856 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Thu, 12 Jan 2023 15:09:10 -0800 Subject: [PATCH] Update docstring syntax around types Take advantage of the new Sphinx support for typing by dropping most of the type information from docstrings. --- src/vocutouts/actors.py | 8 ++-- src/vocutouts/models/parameters.py | 4 +- src/vocutouts/policy.py | 8 ++-- src/vocutouts/uws/dependencies.py | 8 ++-- src/vocutouts/uws/jobs.py | 26 ++++++------- src/vocutouts/uws/policy.py | 18 ++++----- src/vocutouts/uws/results.py | 2 +- src/vocutouts/uws/service.py | 60 +++++++++++++++--------------- src/vocutouts/uws/storage.py | 44 +++++++++++----------- src/vocutouts/uws/utils.py | 2 +- src/vocutouts/workers.py | 20 +++++----- 11 files changed, 101 insertions(+), 99 deletions(-) diff --git a/src/vocutouts/actors.py b/src/vocutouts/actors.py index 350be0c..de7cc0e 100644 --- a/src/vocutouts/actors.py +++ b/src/vocutouts/actors.py @@ -66,13 +66,13 @@ 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 @@ -80,7 +80,7 @@ def cutout( 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. diff --git a/src/vocutouts/models/parameters.py b/src/vocutouts/models/parameters.py index 4f93476..33ea3d1 100644 --- a/src/vocutouts/models/parameters.py +++ b/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 diff --git a/src/vocutouts/policy.py b/src/vocutouts/policy.py index ea0a5bb..ff3be86 100644 --- a/src/vocutouts/policy.py +++ b/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 diff --git a/src/vocutouts/uws/dependencies.py b/src/vocutouts/uws/dependencies.py index b0d0ed8..46f5a40 100644 --- a/src/vocutouts/uws/dependencies.py +++ b/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 diff --git a/src/vocutouts/uws/jobs.py b/src/vocutouts/uws/jobs.py index ef71c2b..08ce8ac 100644 --- a/src/vocutouts/uws/jobs.py +++ b/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) diff --git a/src/vocutouts/uws/policy.py b/src/vocutouts/uws/policy.py index ed12bb4..12498f1 100644 --- a/src/vocutouts/uws/policy.py +++ b/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 diff --git a/src/vocutouts/uws/results.py b/src/vocutouts/uws/results.py index f27cd62..fd1ace3 100644 --- a/src/vocutouts/uws/results.py +++ b/src/vocutouts/uws/results.py @@ -22,7 +22,7 @@ class ResultStore: Parameters ---------- - config : `vocutouts.uws.config.UWSConfig` + config The UWS configuration. """ diff --git a/src/vocutouts/uws/service.py b/src/vocutouts/uws/service.py index 1cad981..05291b2 100644 --- a/src/vocutouts/uws/service.py +++ b/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,20 +137,20 @@ 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 @@ -158,7 +158,7 @@ async def get( 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. diff --git a/src/vocutouts/uws/storage.py b/src/vocutouts/uws/storage.py index 6aa57e7..58fa805 100644 --- a/src/vocutouts/uws/storage.py +++ b/src/vocutouts/uws/storage.py @@ -125,7 +125,7 @@ class FrontendJobStore: Parameters ---------- - session : `sqlalchemy.ext.asyncio.async_scoped_session` + session The underlying database session. Notes @@ -170,22 +170,22 @@ async def add( Parameters ---------- - owner : `str` + owner The username of the owner of the job. - 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. - execution_duration : `int` + execution_duration The maximum length of time for which a job is allowed to run in seconds. - lifetime : `int` + lifetime The maximum lifetime of the job and its results, in seconds. After this time, any record of the job will be deleted. Returns ------- - job : `vocutouts.uws.models.Job` + vocutouts.uws.models.Job The internal representation of the newly-created job. """ now = datetime.now(tz=timezone.utc).replace(microsecond=0) @@ -250,19 +250,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 in UTC. - 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. """ stmt = select( @@ -303,9 +303,9 @@ async def mark_queued(self, job_id: str, message_id: str) -> None: Parameters ---------- - job_id : `str` + job_id The identifier of the job. - message_id : `str` + message_id The identifier for the execution of that job in the work queuing system. """ @@ -322,9 +322,9 @@ async def update_destruction( Parameters ---------- - job_id : `str` + job_id The identifier of the job. - destruction : `datetime.datetime` + destruction The new destruction time. """ async with self._session.begin(): @@ -338,9 +338,9 @@ async def update_execution_duration( Parameters ---------- - job_id : `str` + job_id The identifier of the job. - execution_duration : `int` + execution_duration The new execution duration. """ async with self._session.begin(): @@ -391,7 +391,7 @@ class WorkerJobStore: Parameters ---------- - session : `sqlalchemy.orm.scoped_session` + session The underlying database session. """ @@ -436,12 +436,12 @@ def start_executing( Parameters ---------- - job_id : `str` + job_id The identifier of the job. - message_id : `str` + message_id The identifier for the execution of that job in the work queuing system. - start_time : `datetime` + start_time The time at which the job started executing. """ with self._session.begin(): diff --git a/src/vocutouts/uws/utils.py b/src/vocutouts/uws/utils.py index 9a3c6f1..d1017f5 100644 --- a/src/vocutouts/uws/utils.py +++ b/src/vocutouts/uws/utils.py @@ -16,7 +16,7 @@ def parse_isodatetime(time_string: str) -> datetime | None: Returns ------- - timestamp : `datetime.datetime` or `None` + datetime.datetime or None The corresponding `datetime.datetime` or `None` if the string is invalid. """ diff --git a/src/vocutouts/workers.py b/src/vocutouts/workers.py index 0d24103..e5f23a3 100644 --- a/src/vocutouts/workers.py +++ b/src/vocutouts/workers.py @@ -95,12 +95,12 @@ def get_backend(butler_label: str) -> ImageCutoutBackend: Parameters ---------- - butler_label : `str` + butler_label The label portion fo the Butler URI. Returns ------- - backend : `lsst.image_cutout_backend.ImageCutoutBackend` + lsst.image_cutout_backend.ImageCutoutBackend Backend to use. """ if butler_label in BACKENDS: @@ -119,13 +119,15 @@ def parse_uri(uri: str) -> tuple[str, UUID]: Parameters ---------- - uri : `str` + uri URI to a Butler object. Returns ------- - data : tuple[`str`, `uuid.UUID`] - The Butler label and the object UUID. + str + The Butler label. + uuid.UUID + The object UUID. """ parsed_uri = urlparse(uri) return parsed_uri.netloc, UUID(parsed_uri.path[1:]) @@ -147,13 +149,13 @@ 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 @@ -161,7 +163,7 @@ def cutout( 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. """