Feat: Adds type annotations

mypy.ini

@@ -0,0 +1,2 @@
+[mypy]
+show_error_codes = True

saq/__init__.py

@@ -2,5 +2,4 @@
 from saq.queue import Queue
 from saq.worker import Worker
 
-
 __version__ = "0.9.0"

saq/job.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import dataclasses
 import enum
 import typing
@@ -6,8 +8,11 @@
 
 ABORT_ID_PREFIX = "saq:abort:"
 
+if typing.TYPE_CHECKING:
+    from saq.queue import Queue
+
 
-def get_default_job_key():
+def get_default_job_key() -> str:
     return uuid1()
 
 
@@ -103,7 +108,7 @@ class Job:
     status: Status = Status.NEW
     meta: dict = dataclasses.field(default_factory=dict)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         kwargs = ", ".join(
             f"{k}={v}"
             for k, v in {
@@ -126,22 +131,22 @@ def __repr__(self):
         )
         return f"Job<{kwargs}>"
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.key)
 
     @property
-    def id(self):
+    def id(self) -> str:
         return self.queue.job_id(self.key)
 
     @classmethod
-    def key_from_id(cls, job_id):
+    def key_from_id(cls, job_id: str) -> str:
         return job_id.split(":")[-1]
 
     @property
-    def abort_id(self):
+    def abort_id(self) -> str:
         return f"{ABORT_ID_PREFIX}{self.key}"
 
-    def to_dict(self):
+    def to_dict(self) -> typing.Dict[str, typing.Any]:
         result = {}
         for field in dataclasses.fields(self):
             key = field.name
@@ -155,7 +160,7 @@ def to_dict(self):
             result[key] = value
         return result
 
-    def duration(self, kind):
+    def duration(self, kind: str) -> typing.Optional[int]:
         """
         Returns the duration of the job given kind.
 
@@ -172,19 +177,19 @@ def duration(self, kind):
             return self._duration(now(), self.started)
         raise ValueError(f"Unknown duration type: {kind}")
 
-    def _duration(self, a, b):
+    def _duration(self, a: int, b: int) -> typing.Optional[int]:
         return a - b if a and b else None
 
     @property
-    def stuck(self):
-        """Checks if an active job is passed it's timeout or heartbeat."""
+    def stuck(self) -> bool:
+        """Checks if an active job is passed its timeout or heartbeat."""
         current = now()
-        return (self.status == Status.ACTIVE) and (
+        return (self.status == Status.ACTIVE) and bool(
             seconds(current - self.started) > self.timeout
             or (self.heartbeat and seconds(current - self.touched) > self.heartbeat)
         )
 
-    def next_retry_delay(self):
+    def next_retry_delay(self) -> float:
         if self.retry_backoff:
             max_delay = self.retry_delay
             if max_delay is True:
@@ -197,7 +202,7 @@ def next_retry_delay(self):
             )
         return self.retry_delay
 
-    async def enqueue(self, queue=None):
+    async def enqueue(self, queue: typing.Optional[Queue] = None) -> None:
         """
         Enqueues the job to it's queue or a provided one.
 
@@ -209,19 +214,19 @@ async def enqueue(self, queue=None):
         if not await queue.enqueue(self):
             await self.refresh()
 
-    async def abort(self, error, ttl=5):
+    async def abort(self, error: str, ttl: int = 5) -> None:
         """Tries to abort the job."""
         await self.queue.abort(self, error, ttl=ttl)
 
-    async def finish(self, status, *, result=None, error=None):
+    async def finish(self, status: Status, *, result=None, error=None) -> None:
         """Finishes the job with a Job.Status, result, and or error."""
         await self.queue.finish(self, status, result=result, error=error)
 
-    async def retry(self, error):
+    async def retry(self, error: typing.Optional[str]) -> None:
         """Retries the job by removing it from active and requeueing it."""
         await self.queue.retry(self, error)
 
-    async def update(self, **kwargs):
+    async def update(self, **kwargs) -> None:
         """
         Updates the stored job in redis.
 
@@ -231,7 +236,7 @@ async def update(self, **kwargs):
             setattr(self, k, v)
         await self.queue.update(self)
 
-    async def refresh(self, until_complete=None):
+    async def refresh(self, until_complete: typing.Optional[float] = None) -> None:
         """
         Refresh the current job with the latest data from the db.
 
@@ -254,7 +259,7 @@ async def callback(_id, status):
             await self.queue.listen([self.key], callback, until_complete)
             await self.refresh()
 
-    def replace(self, job):
+    def replace(self, job: "Job") -> None:
         """Replace current attributes with job attributes."""
         for field in job.__dataclass_fields__:
             setattr(self, field, getattr(job, field))