Add type annotations to public SDK surface

Annotate all function signatures and return types across the public
API: Client, HTTPClient, all 10 model classes, utils, and exceptions.

Uses Python 3.10+ syntax (str | None, built-in generics) with
from __future__ import annotations for forward references.

Closes #293

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nsa-softpay

alertaclient/api.py

@@ -1,11 +1,16 @@
+from __future__ import annotations
+
 from datetime import datetime
+from typing import Any
 
 from alertaclient.utils import DateTime
 
+JSON = dict[str, Any]
+
 
 class Alert:
 
-    def __init__(self, resource, event, **kwargs):
+    def __init__(self, resource: str, event: str, **kwargs: Any) -> None:
         if not resource:
             raise ValueError('Missing mandatory value for "resource"')
         if not event:
@@ -45,12 +50,12 @@ def __init__(self, resource, event, **kwargs):
         self.last_receive_time = kwargs.get('last_receive_time', None)
         self.history = kwargs.get('history', None) or list()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'Alert(id={!r}, environment={!r}, resource={!r}, event={!r}, severity={!r}, status={!r}, customer={!r})'.format(
             self.id, self.environment, self.resource, self.event, self.severity, self.status, self.customer)
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> Alert:
         if not isinstance(json.get('correlate', []), list):
             raise ValueError('correlate must be a list')
         if not isinstance(json.get('service', []), list):
@@ -93,10 +98,10 @@ def parse(cls, json):
             history=json.get('history', None)
         )
 
-    def get_id(self, short=False):
+    def get_id(self, short: bool = False) -> str | None:
         return self.id[:8] if short else self.id
 
-    def tabular(self, timezone=None):
+    def tabular(self, timezone: str | None = None) -> dict[str, Any]:
         return {
             'id': self.get_id(short=True),
             'lastReceiveTime': DateTime.localtime(self.last_receive_time, timezone),

alertaclient/models/alert.py

@@ -1,11 +1,16 @@
+from __future__ import annotations
+
 from datetime import datetime, timedelta
+from typing import Any
 
 from alertaclient.utils import DateTime
 
+JSON = dict[str, Any]
+
 
 class Blackout:
 
-    def __init__(self, environment, **kwargs):
+    def __init__(self, environment: str, **kwargs: Any) -> None:
         if not environment:
             raise ValueError('Missing mandatory value for "environment"')
 
@@ -62,7 +67,7 @@ def __init__(self, environment, **kwargs):
             self.status = 'expired'
             self.remaining = 0
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         more = ''
         if self.service:
             more += 'service=%r, ' % self.service
@@ -91,7 +96,7 @@ def __repr__(self):
         )
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> Blackout:
         if not isinstance(json.get('service', []), list):
             raise ValueError('service must be a list')
         if not isinstance(json.get('tags', []), list):
@@ -115,7 +120,7 @@ def parse(cls, json):
             text=json.get('text', None)
         )
 
-    def tabular(self, timezone=None):
+    def tabular(self, timezone: str | None = None) -> dict[str, Any]:
         return {
             'id': self.id,
             'priority': self.priority,

alertaclient/models/blackout.py

@@ -1,23 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+JSON = dict[str, Any]
+
+
 class Customer:
 
-    def __init__(self, match, customer, **kwargs):
+    def __init__(self, match: str, customer: str, **kwargs: Any) -> None:
         self.id = kwargs.get('id', None)
         self.match = match
         self.customer = customer
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'Customer(id={!r}, match={!r}, customer={!r})'.format(
             self.id, self.match, self.customer)
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> Customer:
         return Customer(
             id=json.get('id', None),
             match=json.get('match', None),
             customer=json.get('customer', None)
         )
 
-    def tabular(self):
+    def tabular(self) -> dict[str, Any]:
         return {
             'id': self.id,
             'match': self.match,

alertaclient/models/customer.py

@@ -1,13 +1,18 @@
+from __future__ import annotations
+
 from datetime import datetime, timedelta
+from typing import Any
 
 from alertaclient.utils import DateTime
 
+JSON = dict[str, Any]
+
 DEFAULT_MAX_LATENCY = 2000  # ms
 
 
 class Heartbeat:
 
-    def __init__(self, origin=None, tags=None, create_time=None, timeout=None, customer=None, **kwargs):
+    def __init__(self, origin: str | None = None, tags: list[str] | None = None, create_time: datetime | None = None, timeout: int | None = None, customer: str | None = None, **kwargs: Any) -> None:
         if any(['.' in key for key in kwargs.get('attributes', dict()).keys()])\
                 or any(['$' in key for key in kwargs.get('attributes', dict()).keys()]):
             raise ValueError('Attribute keys must not contain "." or "$"')
@@ -25,20 +30,20 @@ def __init__(self, origin=None, tags=None, create_time=None, timeout=None, custo
         self.customer = customer
 
     @property
-    def latency(self):
+    def latency(self) -> int:
         return int((self.receive_time - self.create_time).total_seconds() * 1000)
 
     @property
-    def since(self):
+    def since(self) -> timedelta:
         since = datetime.utcnow() - self.receive_time
         return since - timedelta(microseconds=since.microseconds)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'Heartbeat(id={!r}, origin={!r}, create_time={!r}, timeout={!r}, customer={!r})'.format(
             self.id, self.origin, self.create_time, self.timeout, self.customer)
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> Heartbeat:
         if not isinstance(json.get('tags', []), list):
             raise ValueError('tags must be a list')
         if not isinstance(json.get('attributes', {}), dict):
@@ -60,7 +65,7 @@ def parse(cls, json):
             customer=json.get('customer', None)
         )
 
-    def tabular(self, timezone=None):
+    def tabular(self, timezone: str | None = None) -> dict[str, Any]:
         return {
             'id': self.id,
             'origin': self.origin,

alertaclient/models/heartbeat.py

@@ -1,11 +1,16 @@
+from __future__ import annotations
+
 from datetime import datetime
+from typing import Any
 
 from alertaclient.utils import DateTime
 
+JSON = dict[str, Any]
+
 
 class History:
 
-    def __init__(self, id, event, **kwargs):
+    def __init__(self, id: str, event: str, **kwargs: Any) -> None:
         self.id = id
         self.event = event
         self.severity = kwargs.get('severity', None)
@@ -16,14 +21,14 @@ def __init__(self, id, event, **kwargs):
         self.update_time = kwargs.get('update_time', None) or datetime.utcnow()
         self.user = kwargs.get('user', None)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'History(id={!r}, event={!r}, severity={!r}, status={!r}, type={!r})'.format(
             self.id, self.event, self.severity, self.status, self.change_type)
 
 
 class RichHistory:
 
-    def __init__(self, resource, event, **kwargs):
+    def __init__(self, resource: str, event: str, **kwargs: Any) -> None:
 
         self.id = kwargs.get('id', None)
         self.resource = resource
@@ -43,12 +48,12 @@ def __init__(self, resource, event, **kwargs):
         self.change_type = kwargs.get('change_type', kwargs.get('type', None))
         self.customer = kwargs.get('customer', None)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'RichHistory(id={!r}, environment={!r}, resource={!r}, event={!r}, severity={!r}, status={!r}, type={!r}, customer={!r})'.format(
             self.id, self.environment, self.resource, self.event, self.severity, self.status, self.change_type, self.customer)
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> RichHistory:
         if not isinstance(json.get('service', []), list):
             raise ValueError('service must be a list')
         if not isinstance(json.get('tags', []), list):
@@ -73,7 +78,7 @@ def parse(cls, json):
             customer=json.get('customer', None)
         )
 
-    def tabular(self, timezone=None):
+    def tabular(self, timezone: str | None = None) -> dict[str, Any]:
         data = {
             'id': self.id,
             'resource': self.resource,

alertaclient/models/history.py

@@ -1,9 +1,16 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
 from alertaclient.utils import DateTime
 
+JSON = dict[str, Any]
+
 
 class ApiKey:
 
-    def __init__(self, user, scopes, text='', expire_time=None, customer=None, **kwargs):
+    def __init__(self, user: str, scopes: list[str], text: str | None = '', expire_time: datetime | None = None, customer: str | None = None, **kwargs: Any) -> None:
         self.id = kwargs.get('id', None)
         self.key = kwargs.get('key', None)
         self.user = user
@@ -15,15 +22,15 @@ def __init__(self, user, scopes, text='', expire_time=None, customer=None, **kwa
         self.customer = customer
 
     @property
-    def type(self):
+    def type(self) -> str:
         return self.scopes_to_type(self.scopes)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'ApiKey(key={!r}, user={!r}, scopes={!r}, expireTime={!r}, customer={!r})'.format(
             self.key, self.user, self.scopes, self.expire_time, self.customer)
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> ApiKey:
         if not isinstance(json.get('scopes', []), list):
             raise ValueError('scopes must be a list')
 
@@ -39,13 +46,13 @@ def parse(cls, json):
             customer=json.get('customer', None)
         )
 
-    def scopes_to_type(self, scopes):
+    def scopes_to_type(self, scopes: list[str]) -> str:
         for scope in scopes:
             if scope.startswith('write') or scope.startswith('admin'):
                 return 'read-write'
         return 'read-only'
 
-    def tabular(self, timezone=None):
+    def tabular(self, timezone: str | None = None) -> dict[str, Any]:
         return {
             'id': self.id,
             'key': self.key,

alertaclient/models/key.py

@@ -1,11 +1,16 @@
+from __future__ import annotations
+
 from datetime import datetime
+from typing import Any
 
 from alertaclient.utils import DateTime
 
+JSON = dict[str, Any]
+
 
 class Note:
 
-    def __init__(self, text, user, note_type, **kwargs):
+    def __init__(self, text: str, user: str, note_type: str | None, **kwargs: Any) -> None:
 
         self.id = kwargs.get('id', None)
         self.text = text
@@ -18,7 +23,7 @@ def __init__(self, text, user, note_type, **kwargs):
         self.customer = kwargs.get('customer')
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> Note:
         return Note(
             id=json.get('id', None),
             text=json.get('text', None),
@@ -31,12 +36,12 @@ def parse(cls, json):
             customer=json.get('customer', None)
         )
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'Note(id={!r}, text={!r}, user={!r}, type={!r}, customer={!r})'.format(
             self.id, self.text, self.user, self.note_type, self.customer
         )
 
-    def tabular(self, timezone=None):
+    def tabular(self, timezone: str | None = None) -> dict[str, Any]:
         note = {
             'id': self.id,
             'text': self.text,

alertaclient/models/note.py

@@ -1,16 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+JSON = dict[str, Any]
+
+
 class Permission:
 
-    def __init__(self, match, scopes, **kwargs):
+    def __init__(self, match: str, scopes: list[str] | None, **kwargs: Any) -> None:
         self.id = kwargs.get('id', None)
         self.match = match
         self.scopes = scopes or list()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'Perm(id={!r}, match={!r}, scopes={!r})'.format(
             self.id, self.match, self.scopes)
 
     @classmethod
-    def parse(cls, json):
+    def parse(cls, json: JSON) -> Permission:
         if not isinstance(json.get('scopes', []), list):
             raise ValueError('scopes must be a list')
 
@@ -20,7 +27,7 @@ def parse(cls, json):
             scopes=json.get('scopes', list())
         )
 
-    def tabular(self):
+    def tabular(self) -> dict[str, Any]:
         return {
             'id': self.id,
             'match': self.match,