Coverage for src / lexigram / contracts / core / types.py: 0%

1"""Common type aliases for Lexigram Framework. 

2 

3All aliases here are defined in terms of standard Python types. Several 

4aliases intentionally share the same **underlying** type (``dict[str, Any]``) 

5but carry distinct **semantic** meaning to make call-sites self-documenting 

6and to enable targeted mypy type-narrowing in the future. 

7 

8Alias semantics 

9--------------- 

10:data:`JSON` 

11 Arbitrary JSON-serialisable mapping. Use at I/O boundaries (HTTP bodies, 

12 cache payloads, event envelopes) where the shape is not yet constrainted by 

13 a typed schema. 

14 

15:data:`Metadata` 

16 Free-form key/value annotations attached to domain objects or context vars. 

17 Unlike :data:`JSON`, callers may include non-serialisable values (e.g. 

18 internal bookkeeping objects). 

19 

20:data:`TokenPayload` 

21 Claims extracted from a validated JWT / session token. Always 

22 ``dict[str, Any]`` because token claim sets are open-world; callers 

23 immediately destructure the payload into typed fields. 

24 

25These three aliases are *intentionally* synonymous at the type level. 

26They exist to make intent visible — prefer the most specific alias at each 

27call-site. 

28""" 

29 

30from __future__ import annotations 

31 

32from datetime import datetime 

33from typing import Any, TypeAlias 

34from uuid import UUID 

35 

36JSON: TypeAlias = dict[str, Any] 

37Metadata: TypeAlias = dict[str, Any] 

38TokenPayload: TypeAlias = dict[str, Any] 

39 

40EntityId: TypeAlias = str | int | UUID 

41"""Identifier for domain entities — accepts both plain strings, ints, and UUIDs.""" 

42 

43Headers: TypeAlias = dict[str, str] 

44"""HTTP-style header mapping (header-name → value).""" 

45 

46QueryParams: TypeAlias = dict[str, str | list[str]] 

47"""URL query-parameter mapping. Values may be repeated (list) or singular (str).""" 

48 

49Timestamp: TypeAlias = datetime 

50"""An unambiguous point in time. Prefer timezone-aware datetimes.""" 

51 

52Version: TypeAlias = int 

53"""Optimistic-locking version counter for aggregate roots.""" 

54 

55__all__ = [ 

56 "JSON", 

57 "EntityId", 

58 "Headers", 

59 "Metadata", 

60 "QueryParams", 

61 "Timestamp", 

62 "TokenPayload", 

63 "Version", 

64]