Coverage for src/metador_core/schema/decorators.py: 100%

1from typing import Any, Dict, Literal, Optional 

2 

3from pydantic.fields import ModelField 

4 

5from ..util import is_public_name 

6from ..util.models import field_parent_type 

7from ..util.typing import get_annotations, is_enum, is_literal, is_subtype, unoptional 

8from .core import MetadataSchema 

9 

10 

11def _expect_schema_class(mcls): 

12 if not issubclass(mcls, MetadataSchema): 

13 raise TypeError("This decorator is for MetadataSchema subclasses!") 

14 

15 

16def _check_names_public(names): 

17 if priv_overrides := set(filter(lambda x: not is_public_name(x), names)): 

18 raise ValueError(f"Illegal private overrides: {priv_overrides}") 

19 

20 

21def make_mandatory(*names: str): 

22 """Make a field inherited from a base class mandatory if it is optional. 

23 

24 The field must exist in a base class and must not be defined in the 

25 decorated class. 

26 

27 Use this decorator instead of manually declaring an annotation, 

28 if all you need to do is making an existing field mandatory. 

29 """ 

30 # NOTE: idea: could take a dict, then values are the new default for non-optional 

31 # but is this good? defaults are implicit optionality -> we discourage it, so no. 

32 _check_names_public(names) 

33 

34 def make_fields_mandatory(mcls): 

35 _expect_schema_class(mcls) 

36 

37 for name in names: 

38 if name not in mcls.__fields__: 

39 raise ValueError(f"{mcls.__name__} has no field named '{name}'!") 

40 if name in get_annotations(mcls): 

41 raise ValueError( 

42 f"{mcls.__name__} already defines '{name}', cannot use decorator!" 

43 ) 

44 

45 hint = unoptional(field_parent_type(mcls, name)) 

46 # update model and type hint (important for type analysis) 

47 mcls.__fields__[name].required = True 

48 mcls.__annotations__[name] = hint 

49 

50 return mcls 

51 

52 return make_fields_mandatory 

53 

54 

55def add_const_fields(consts: Dict[str, Any], *, override: bool = False): 

56 """Add constant fields to pydantic models. 

57 

58 Must be passed a dict of field names and the constant values (only JSON-like types). 

59 

60 Constant fields are optional during input. 

61 If present during parsing, they are be ignored and overriden with the constant. 

62 Constant fields are included in serialization, unless `exclude_defaults` is set. 

63 

64 This can be used e.g. to attach JSON-LD annotations to schemas. 

65 

66 Constant fields are inherited and may only be overridden by other constant fields 

67 using this decorator, they cannot become normal fields again. 

68 """ 

69 _check_names_public(consts.keys()) 

70 

71 def add_fields(mcls): 

72 _expect_schema_class(mcls) 

73 

74 # hacking it in-place approach: 

75 overridden = set() 

76 for name, value in consts.items(): 

77 if field_def := mcls.__fields__.get(name): # overriding a field 

78 # we allow to silently override of enum/literal types with suitable values 

79 # to support a schema design pattern of marked subclasses 

80 # but check that it is actually used correctly. 

81 enum_specialization = is_enum(field_def.type_) 

82 literal_specialization = is_literal(field_def.type_) 

83 

84 valid_specialization = False 

85 if enum_specialization: 

86 valid_specialization = isinstance(value, field_def.type_) 

87 elif literal_specialization: 

88 lit_const = Literal[value] # type: ignore 

89 valid_specialization = is_subtype(lit_const, field_def.type_) 

90 

91 if ( 

92 enum_specialization or literal_specialization 

93 ) and not valid_specialization: 

94 msg = f"{mcls.__name__}.{name} cannot be overriden with '{value}', " 

95 msg += f"because it is not a valid value of {field_def.type_}!" 

96 raise TypeError(msg) 

97 

98 # reject if not force override or allowed special cases 

99 if not (override or enum_specialization or literal_specialization): 

100 msg = f"{mcls.__name__} already has a field '{name}'!" 

101 msg += f" (override={override})" 

102 raise ValueError(msg) 

103 

104 else: # new field 

105 overridden.add(name) 

106 

107 # this would force the exact constant on load 

108 # but this breaks parent compatibility if consts overridden! 

109 # ---- 

110 # val = value.default if isinstance(value, FieldInfo) else value 

111 # ctype = Optional[make_literal(val)] # type: ignore 

112 # ---- 

113 # we simply ignore the constants as opaque somethings 

114 ctype = Optional[Any] # type: ignore 

115 

116 # configure pydantic field 

117 field = ModelField.infer( 

118 name=name, 

119 value=value, 

120 annotation=ctype, 

121 class_validators=None, 

122 config=mcls.__config__, 

123 ) 

124 mcls.__fields__[name] = field 

125 # add type hint (important for our field analysis!) 

126 mcls.__annotations__[name] = field.type_ 

127 ret = mcls 

128 

129 # dynamic subclass approach: 

130 # ret = create_model(mcls.__name__, __base__=mcls, __module__=mcls.__module__, **consts) 

131 # if hasattr(mcls, "Plugin"): 

132 # ret.Plugin = mcls.Plugin 

133 

134 # to later distinguish "const" fields from normal fields: 

135 ret.__constants__.update(consts) 

136 return ret 

137 

138 return add_fields 

139 

140 

141def override(*names: str): 

142 """Declare fields that are overridden (and not valid as subtypes). 

143 

144 These are checked during plugin loading, in order to catch accidental 

145 overridden fields in schemas. 

146 """ 

147 _check_names_public(names) 

148 

149 def add_overrides(mcls): 

150 _expect_schema_class(mcls) 

151 mcls.__overrides__.update(set(names)) 

152 return mcls 

153 

154 return add_overrides