Coverage for src/metador_core/plugin/metaclass.py: 100%

1"""This module defines a metaclass that should be used for all plugin types.""" 

2 

3from .types import to_semver_str 

4 

5 

6class MarkerMixin: 

7 """Base class for Metador-internal marker mixins. 

8 

9 It can be used to hand out copies of classes with markings, 

10 without actually modifying the original class. 

11 """ 

12 

13 @classmethod 

14 def _fieldname(cls): 

15 return f"__{cls.__name__}_unwrapped__" 

16 

17 @classmethod 

18 def _is_marked(cls, c) -> bool: 

19 """Return whether `c` is proper subclass of this marker.""" 

20 return c is not cls and issubclass(c, cls) 

21 

22 @classmethod 

23 def _mark_class(cls, c): 

24 """Mark a class with this marker mixin.""" 

25 if cls._is_marked(c): 

26 raise TypeError(f"{c} already marked by {cls}!") 

27 

28 ret = c.__class__(c.__name__, (cls, c), {}) 

29 # ret.__module__ = c.__module__ 

30 setattr(ret, cls._fieldname(), c) 

31 

32 # NOTE: discouraged! 

33 # https://docs.python.org/3/howto/annotations.html#annotations-howto 

34 # ---- 

35 # anns = getattr(ret, "__annotations__", {}) 

36 # anns[unw_field] = ClassVar[Type] 

37 # ret.__annotations__ = anns 

38 

39 return ret 

40 

41 @classmethod 

42 def _unwrap(cls, c): 

43 """Return the original class, or None if given argument is not marked.""" 

44 if issubclass(c, cls): 

45 return getattr(c, cls._fieldname()) 

46 else: 

47 return None 

48 

49 

50class UndefVersion(MarkerMixin): 

51 """Marker for a plugin class retrieved with no specified version. 

52 

53 We have to do this crazy thing, because wrapt.ObjectProxy-wrapped 

54 classes can be transparently derived, and what is even worse, 

55 the derived class is not wrapped anymore. 

56 

57 The mixin subclass approach therefore makes more sense here, as 

58 the metaclass then can check for its presence. 

59 """ 

60 

61 @classmethod 

62 def _mark_class(cls, c): 

63 # NOTE: we also want to mark nested non-plugins to prevent subclassing 

64 # so we do not assume that cls.Plugin is defined 

65 ret = super()._mark_class(c) 

66 # make sure that the Plugin section *is* actually inherited, 

67 # (normally this is prevented by the plugin metaclass) 

68 # that way we can use the marked class as if it was the real one 

69 if not ret.__dict__.get("Plugin"): 

70 ret.Plugin = c.Plugin 

71 

72 return ret 

73 

74 

75class PluginMetaclassMixin(type): 

76 """Metaclass mixin to be used with plugins of any group. 

77 

78 It provides an is_plugin property to classes to quickly check if they 

79 seem to be valid registered plugins. 

80 

81 It ensures that: 

82 * the `Plugin` inner class is not automatically inherited 

83 * registered Plugin classes cannot be subclassed if loaded without a fixed version 

84 

85 For the second part, this works together with the PluginGroup implementation, 

86 which makes sure that schemas requested without versions are not actually handed out, 

87 but instead users get a subclass with the `UndefVersion` mixin we can detect here. 

88 """ 

89 

90 def __repr__(self): 

91 # add plugin name and version to default class repr 

92 if c := UndefVersion._unwrap(self): 

93 # indicate the attached UndefVersion 

94 return f"{repr(c)} (version unspecified)" 

95 else: 

96 # indicate loaded plugin name and version 

97 pg_str = "" 

98 if pgi := self.__dict__.get("Plugin"): 

99 pgi = self.Plugin 

100 pg_str = f" ({pgi.name} {to_semver_str(pgi.version)})" 

101 

102 return f"{super().__repr__()}{pg_str}" 

103 

104 def __new__(cls, name, bases, dct): 

105 # prevent inheriting from a plugin accessed without stated version 

106 for b in bases: 

107 if UndefVersion._is_marked(b): 

108 if pgi := b.__dict__.get("Plugin"): 

109 ref = f"plugin '{pgi.name}'" 

110 else: 

111 ref = f"{UndefVersion._unwrap(b)} originating from a plugin" 

112 msg = f"{name}: Cannot inherit from {ref} of unspecified version!" 

113 raise TypeError(msg) 

114 

115 # prevent inheriting inner Plugin class by setting it to None 

116 if "Plugin" not in dct: 

117 dct["Plugin"] = None 

118 

119 # hide special marker base class from parent metaclass (if present) 

120 # so it does not have to know about any of this happening 

121 # (otherwise it could interfere with other checks) 

122 # NOTE: needed e.g. for schemas to work properly 

123 filt_bases = tuple(b for b in bases if b is not UndefVersion) 

124 ret = super().__new__(cls, name, filt_bases, dct) 

125 

126 # add marker back, as if it was present all along 

127 if len(filt_bases) < len(bases): 

128 ret.__bases__ = (UndefVersion, *ret.__bases__) 

129 

130 return ret