Skip to content

Commit

Permalink
Update docstring syntax around types
Browse files Browse the repository at this point in the history
Take advantage of the new Sphinx support for typing by dropping
most of the type information from docstrings.
  • Loading branch information
rra committed Jan 12, 2023
1 parent 83e48bf commit 6412bba
Show file tree
Hide file tree
Showing 11 changed files with 101 additions and 99 deletions.
8 changes: 4 additions & 4 deletions src/vocutouts/actors.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions src/vocutouts/models/parameters.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions src/vocutouts/policy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""

Expand All @@ -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
Expand Down
8 changes: 4 additions & 4 deletions src/vocutouts/uws/dependencies.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -131,7 +131,7 @@ def override_policy(self, policy: UWSPolicy) -> None:
Parameters
----------
actor : `vocutouts.uws.policy.UWSPolicy`
actor
The new policy.
"""
self._policy = policy
Expand Down
26 changes: 13 additions & 13 deletions src/vocutouts/uws/jobs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand Down
18 changes: 9 additions & 9 deletions src/vocutouts/uws/policy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""

Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -95,7 +95,7 @@ def validate_params(self, params: list[JobParameter]) -> None:
Parameters
----------
params : list[`vocutouts.uws.models.JobParameter`]
params
The new parameters.
Raises
Expand Down
2 changes: 1 addition & 1 deletion src/vocutouts/uws/results.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ class ResultStore:
Parameters
----------
config : `vocutouts.uws.config.UWSConfig`
config
The UWS configuration.
"""

Expand Down
60 changes: 30 additions & 30 deletions src/vocutouts/uws/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""

Expand All @@ -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()
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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(
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
Loading

0 comments on commit 6412bba

Please sign in to comment.