Coverage for src/fluree_py/types/common.py: 91%

1from typing import Any, Literal, TypeAlias, TypeGuard, TypedDict 

2 

3 

4# Type alias for JSON-serializable data that can be either a single dict or a list of dicts 

5JsonObject: TypeAlias = dict[str, Any] 

6JsonArray: TypeAlias = list[Any] 

7 

8LedgerName: TypeAlias = str 

9"""A textal name for the ledger.""" 

10 

11 

12Subject: TypeAlias = str 

13"""A textual identifier for a subject.""" 

14 

15Context: TypeAlias = JsonObject 

16""" 

17A W3C JSON-LD context for a FlureeQL request. 

18""" 

19 

20Predicate: TypeAlias = str 

21""" 

22 A predicate identifier in a FlureeQL query. 

23 A predicate is a string that identifies a property or relationship in the database. 

24 

25 Examples: 

26 "schema:name" 

27 "schema:age" 

28 "schema:friend" 

29""" 

30 

31 

32Wildcard: TypeAlias = Literal["*"] 

33""" 

34A wildcard character in a FlureeQL query. 

35The wildcard character is used to select all predicates of a subject. 

36 

37Examples: 

38 "*" 

39""" 

40 

41### Time Types 

42TimeCommit: TypeAlias = int 

43 

44 

45def is_time_commit(t: Any) -> TypeGuard[TimeCommit]: 

46 """Checks if a value is a valid time commit.""" 

47 return isinstance(t, int) and t >= 0 

48 

49 

50LatestTimeConstraint = Literal["latest"] 

51 

52TimeConstraint = TypedDict( 

53 "TimeConstraint", 

54 { 

55 "at": TimeCommit | LatestTimeConstraint, 

56 "from": TimeCommit | LatestTimeConstraint, 

57 "to": TimeCommit | LatestTimeConstraint, 

58 }, 

59 total=False, 

60) 

61 

62 

63def is_time_constraint(t: Any) -> TypeGuard[TimeConstraint]: 

64 """Checks if a value is a valid time constraint.""" 

65 return isinstance(t, dict) and all( 

66 is_time_commit(v) or v == "latest" 

67 for v in t.values() # type: ignore 

68 ) 

69 

70 

71TimeClause: TypeAlias = TimeConstraint | TimeCommit 

72""" 

73A time clause for a FlureeQL query. It is either a commit number or a constraint on the commit. 

74 

75Examples: 

76 - {"t": {"at": 123}} 

77 - {"t": {"from": 123, "to": 456}} 

78 - {"t": 123} 

79"""