Coverage for src / lexigram / contracts / web / types.py: 100%

1"""Standard HTTP response envelope types for Lexigram Framework. 

2 

3Provides consistent, type-safe data structures for common HTTP response 

4patterns: error responses and paginated result sets. 

5""" 

6 

7from __future__ import annotations 

8 

9from dataclasses import dataclass, field 

10from typing import Generic, TypeVar 

11 

12T = TypeVar("T") 

13 

14 

15@dataclass(frozen=True) 

16class ErrorDetail: 

17 """Single error detail in an HTTP error response. 

18 

19 Attributes: 

20 code: Machine-readable error code (e.g., "INVALID_INPUT"). 

21 message: Human-readable error message. 

22 field: Optional field name that caused the error (for form validation). 

23 """ 

24 

25 code: str 

26 message: str 

27 field: str | None = None 

28 

29 

30@dataclass(frozen=True) 

31class ErrorResponseDTO: 

32 """Standard HTTP error response envelope. 

33 

34 Provides a consistent structure for error responses across all endpoints. 

35 Should be used with appropriate HTTP status codes (4xx, 5xx). 

36 

37 Attributes: 

38 error: High-level error category. 

39 message: Human-readable summary of what went wrong. 

40 details: List of specific error details (empty for simple errors). 

41 request_id: Optional request identifier for tracing and support. 

42 """ 

43 

44 error: str 

45 message: str 

46 details: list[ErrorDetail] = field(default_factory=list) 

47 request_id: str | None = None 

48 

49 

50@dataclass(frozen=True) 

51class PaginatedResponseDTO(Generic[T]): 

52 """Standard paginated HTTP response envelope. 

53 

54 Encapsulates a page of results with metadata for navigation. 

55 Supports both offset-based and cursor-based pagination. 

56 

57 Attributes: 

58 items: The entities in this page. 

59 total: Total count of items across all pages. 

60 page: Current page number (1-indexed, 0-indexed for cursor). 

61 page_size: Maximum items returned per page. 

62 has_next: Whether there are more pages after this one. 

63 has_prev: Whether there are pages before this one. 

64 next_cursor: Opaque cursor for the next page (for cursor-based pagination). 

65 """ 

66 

67 items: list[T] 

68 total: int 

69 page: int 

70 page_size: int 

71 has_next: bool 

72 has_prev: bool 

73 next_cursor: str | None = None 

74 

75 

76__all__ = [ 

77 "ErrorDetail", 

78 "ErrorResponseDTO", 

79 "PaginatedResponseDTO", 

80]