Georg Brandl | e5a32dc | 2007-12-21 08:16:54 +0000 | [diff] [blame] | 1 | """ |
| 2 | Define names for built-in types that aren't directly accessible as a builtin. |
Guido van Rossum | e7b146f | 2000-02-04 15:28:42 +0000 | [diff] [blame] | 3 | """ |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 4 | import sys |
| 5 | |
Tim Peters | 26991a7 | 2001-09-25 22:02:03 +0000 | [diff] [blame] | 6 | # Iterators in Python aren't a matter of type but of protocol. A large |
| 7 | # and changing number of builtin types implement *some* flavor of |
| 8 | # iterator. Don't check the type! Use hasattr to check for both |
Georg Brandl | a18af4e | 2007-04-21 15:47:16 +0000 | [diff] [blame] | 9 | # "__iter__" and "__next__" attributes instead. |
Tim Peters | 26991a7 | 2001-09-25 22:02:03 +0000 | [diff] [blame] | 10 | |
Guido van Rossum | adc940e | 1994-09-29 10:04:43 +0000 | [diff] [blame] | 11 | def _f(): pass |
| 12 | FunctionType = type(_f) |
Guido van Rossum | 45e2fbc | 1998-03-26 21:13:24 +0000 | [diff] [blame] | 13 | LambdaType = type(lambda: None) # Same as FunctionType |
Guido van Rossum | a8add0e | 2007-05-14 22:03:55 +0000 | [diff] [blame] | 14 | CodeType = type(_f.__code__) |
Victor Stinner | 0db176f | 2012-04-16 00:16:30 +0200 | [diff] [blame] | 15 | MappingProxyType = type(type.__dict__) |
Barry Warsaw | 409da15 | 2012-06-03 16:18:47 -0400 | [diff] [blame] | 16 | SimpleNamespace = type(sys.implementation) |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 17 | |
Pierre Glaser | df8d2cd | 2019-02-07 20:36:48 +0100 | [diff] [blame] | 18 | def _cell_factory(): |
| 19 | a = 1 |
| 20 | def f(): |
| 21 | nonlocal a |
| 22 | return f.__closure__[0] |
| 23 | CellType = type(_cell_factory()) |
| 24 | |
Tim Peters | 264c659 | 2004-07-18 00:08:11 +0000 | [diff] [blame] | 25 | def _g(): |
Tim Peters | 3e7b1a0 | 2001-06-25 19:46:25 +0000 | [diff] [blame] | 26 | yield 1 |
Tim Peters | 264c659 | 2004-07-18 00:08:11 +0000 | [diff] [blame] | 27 | GeneratorType = type(_g()) |
Tim Peters | 3e7b1a0 | 2001-06-25 19:46:25 +0000 | [diff] [blame] | 28 | |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 29 | async def _c(): pass |
| 30 | _c = _c() |
| 31 | CoroutineType = type(_c) |
| 32 | _c.close() # Prevent ResourceWarning |
| 33 | |
Yury Selivanov | eb63645 | 2016-09-08 22:01:51 -0700 | [diff] [blame] | 34 | async def _ag(): |
| 35 | yield |
| 36 | _ag = _ag() |
| 37 | AsyncGeneratorType = type(_ag) |
| 38 | |
Guido van Rossum | adc940e | 1994-09-29 10:04:43 +0000 | [diff] [blame] | 39 | class _C: |
Guido van Rossum | 898c915 | 1997-09-04 22:12:34 +0000 | [diff] [blame] | 40 | def _m(self): pass |
Guido van Rossum | 65810fe | 2006-05-26 19:12:38 +0000 | [diff] [blame] | 41 | MethodType = type(_C()._m) |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 42 | |
Guido van Rossum | adc940e | 1994-09-29 10:04:43 +0000 | [diff] [blame] | 43 | BuiltinFunctionType = type(len) |
Guido van Rossum | 45e2fbc | 1998-03-26 21:13:24 +0000 | [diff] [blame] | 44 | BuiltinMethodType = type([].append) # Same as BuiltinFunctionType |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 45 | |
Jim Fasarakis-Hilliard | 08c1601 | 2017-04-25 21:26:36 +0300 | [diff] [blame] | 46 | WrapperDescriptorType = type(object.__init__) |
Guido van Rossum | 934aba6 | 2017-02-01 10:55:58 -0800 | [diff] [blame] | 47 | MethodWrapperType = type(object().__str__) |
| 48 | MethodDescriptorType = type(str.join) |
Serhiy Storchaka | 3327a2d | 2017-12-15 14:13:41 +0200 | [diff] [blame] | 49 | ClassMethodDescriptorType = type(dict.__dict__['fromkeys']) |
Guido van Rossum | 934aba6 | 2017-02-01 10:55:58 -0800 | [diff] [blame] | 50 | |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 51 | ModuleType = type(sys) |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 52 | |
| 53 | try: |
Guido van Rossum | 898c915 | 1997-09-04 22:12:34 +0000 | [diff] [blame] | 54 | raise TypeError |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 55 | except TypeError: |
Guido van Rossum | a8add0e | 2007-05-14 22:03:55 +0000 | [diff] [blame] | 56 | tb = sys.exc_info()[2] |
| 57 | TracebackType = type(tb) |
| 58 | FrameType = type(tb.tb_frame) |
Guido van Rossum | f15d159 | 1997-09-29 23:22:12 +0000 | [diff] [blame] | 59 | tb = None; del tb |
Guido van Rossum | 85d8945 | 1994-06-23 11:53:27 +0000 | [diff] [blame] | 60 | |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 61 | # For Jython, the following two types are identical |
| 62 | GetSetDescriptorType = type(FunctionType.__code__) |
| 63 | MemberDescriptorType = type(FunctionType.__globals__) |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 64 | |
Henry Chen | 0a6a412 | 2019-03-03 06:35:24 -0800 | [diff] [blame] | 65 | del sys, _f, _g, _C, _c, _ag # Not for export |
Nick Coghlan | 7fc570a | 2012-05-20 02:34:13 +1000 | [diff] [blame] | 66 | |
| 67 | |
| 68 | # Provide a PEP 3115 compliant mechanism for class creation |
| 69 | def new_class(name, bases=(), kwds=None, exec_body=None): |
| 70 | """Create a class object dynamically using the appropriate metaclass.""" |
Ivan Levkivskyi | 2b5fd1e | 2017-12-14 23:32:56 +0100 | [diff] [blame] | 71 | resolved_bases = resolve_bases(bases) |
| 72 | meta, ns, kwds = prepare_class(name, resolved_bases, kwds) |
Nick Coghlan | 7fc570a | 2012-05-20 02:34:13 +1000 | [diff] [blame] | 73 | if exec_body is not None: |
| 74 | exec_body(ns) |
Ivan Levkivskyi | 2b5fd1e | 2017-12-14 23:32:56 +0100 | [diff] [blame] | 75 | if resolved_bases is not bases: |
| 76 | ns['__orig_bases__'] = bases |
| 77 | return meta(name, resolved_bases, ns, **kwds) |
| 78 | |
| 79 | def resolve_bases(bases): |
| 80 | """Resolve MRO entries dynamically as specified by PEP 560.""" |
| 81 | new_bases = list(bases) |
| 82 | updated = False |
| 83 | shift = 0 |
| 84 | for i, base in enumerate(bases): |
| 85 | if isinstance(base, type): |
| 86 | continue |
| 87 | if not hasattr(base, "__mro_entries__"): |
| 88 | continue |
| 89 | new_base = base.__mro_entries__(bases) |
| 90 | updated = True |
| 91 | if not isinstance(new_base, tuple): |
| 92 | raise TypeError("__mro_entries__ must return a tuple") |
| 93 | else: |
| 94 | new_bases[i+shift:i+shift+1] = new_base |
| 95 | shift += len(new_base) - 1 |
| 96 | if not updated: |
| 97 | return bases |
| 98 | return tuple(new_bases) |
Nick Coghlan | 7fc570a | 2012-05-20 02:34:13 +1000 | [diff] [blame] | 99 | |
| 100 | def prepare_class(name, bases=(), kwds=None): |
| 101 | """Call the __prepare__ method of the appropriate metaclass. |
| 102 | |
| 103 | Returns (metaclass, namespace, kwds) as a 3-tuple |
| 104 | |
| 105 | *metaclass* is the appropriate metaclass |
| 106 | *namespace* is the prepared class namespace |
| 107 | *kwds* is an updated copy of the passed in kwds argument with any |
| 108 | 'metaclass' entry removed. If no kwds argument is passed in, this will |
| 109 | be an empty dict. |
| 110 | """ |
| 111 | if kwds is None: |
| 112 | kwds = {} |
| 113 | else: |
| 114 | kwds = dict(kwds) # Don't alter the provided mapping |
| 115 | if 'metaclass' in kwds: |
| 116 | meta = kwds.pop('metaclass') |
| 117 | else: |
| 118 | if bases: |
| 119 | meta = type(bases[0]) |
| 120 | else: |
| 121 | meta = type |
| 122 | if isinstance(meta, type): |
| 123 | # when meta is a type, we first determine the most-derived metaclass |
| 124 | # instead of invoking the initial candidate directly |
| 125 | meta = _calculate_meta(meta, bases) |
| 126 | if hasattr(meta, '__prepare__'): |
| 127 | ns = meta.__prepare__(name, bases, **kwds) |
| 128 | else: |
Eric Snow | 4f29e75 | 2016-09-08 15:11:11 -0700 | [diff] [blame] | 129 | ns = {} |
Nick Coghlan | 7fc570a | 2012-05-20 02:34:13 +1000 | [diff] [blame] | 130 | return meta, ns, kwds |
| 131 | |
| 132 | def _calculate_meta(meta, bases): |
| 133 | """Calculate the most derived metaclass.""" |
| 134 | winner = meta |
| 135 | for base in bases: |
| 136 | base_meta = type(base) |
| 137 | if issubclass(winner, base_meta): |
| 138 | continue |
| 139 | if issubclass(base_meta, winner): |
| 140 | winner = base_meta |
| 141 | continue |
| 142 | # else: |
| 143 | raise TypeError("metaclass conflict: " |
| 144 | "the metaclass of a derived class " |
| 145 | "must be a (non-strict) subclass " |
| 146 | "of the metaclasses of all its bases") |
| 147 | return winner |
Ethan Furman | e03ea37 | 2013-09-25 07:14:41 -0700 | [diff] [blame] | 148 | |
| 149 | class DynamicClassAttribute: |
| 150 | """Route attribute access on a class to __getattr__. |
| 151 | |
| 152 | This is a descriptor, used to define attributes that act differently when |
| 153 | accessed through an instance and through a class. Instance access remains |
| 154 | normal, but access to an attribute through a class will be routed to the |
| 155 | class's __getattr__ method; this is done by raising AttributeError. |
| 156 | |
| 157 | This allows one to have properties active on an instance, and have virtual |
| 158 | attributes on the class with the same name (see Enum for an example). |
| 159 | |
| 160 | """ |
| 161 | def __init__(self, fget=None, fset=None, fdel=None, doc=None): |
| 162 | self.fget = fget |
| 163 | self.fset = fset |
| 164 | self.fdel = fdel |
| 165 | # next two lines make DynamicClassAttribute act the same as property |
Ethan Furman | 63c141c | 2013-10-18 00:27:39 -0700 | [diff] [blame] | 166 | self.__doc__ = doc or fget.__doc__ |
Ethan Furman | e03ea37 | 2013-09-25 07:14:41 -0700 | [diff] [blame] | 167 | self.overwrite_doc = doc is None |
| 168 | # support for abstract methods |
| 169 | self.__isabstractmethod__ = bool(getattr(fget, '__isabstractmethod__', False)) |
| 170 | |
| 171 | def __get__(self, instance, ownerclass=None): |
| 172 | if instance is None: |
| 173 | if self.__isabstractmethod__: |
| 174 | return self |
| 175 | raise AttributeError() |
| 176 | elif self.fget is None: |
| 177 | raise AttributeError("unreadable attribute") |
| 178 | return self.fget(instance) |
| 179 | |
| 180 | def __set__(self, instance, value): |
| 181 | if self.fset is None: |
| 182 | raise AttributeError("can't set attribute") |
| 183 | self.fset(instance, value) |
| 184 | |
| 185 | def __delete__(self, instance): |
| 186 | if self.fdel is None: |
| 187 | raise AttributeError("can't delete attribute") |
| 188 | self.fdel(instance) |
| 189 | |
| 190 | def getter(self, fget): |
| 191 | fdoc = fget.__doc__ if self.overwrite_doc else None |
| 192 | result = type(self)(fget, self.fset, self.fdel, fdoc or self.__doc__) |
| 193 | result.overwrite_doc = self.overwrite_doc |
| 194 | return result |
| 195 | |
| 196 | def setter(self, fset): |
| 197 | result = type(self)(self.fget, fset, self.fdel, self.__doc__) |
| 198 | result.overwrite_doc = self.overwrite_doc |
| 199 | return result |
| 200 | |
| 201 | def deleter(self, fdel): |
| 202 | result = type(self)(self.fget, self.fset, fdel, self.__doc__) |
| 203 | result.overwrite_doc = self.overwrite_doc |
| 204 | return result |
Serhiy Storchaka | 7beb4f9 | 2015-03-04 09:43:27 +0200 | [diff] [blame] | 205 | |
| 206 | |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 207 | class _GeneratorWrapper: |
| 208 | # TODO: Implement this in C. |
| 209 | def __init__(self, gen): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 210 | self.__wrapped = gen |
| 211 | self.__isgen = gen.__class__ is GeneratorType |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 212 | self.__name__ = getattr(gen, '__name__', None) |
| 213 | self.__qualname__ = getattr(gen, '__qualname__', None) |
| 214 | def send(self, val): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 215 | return self.__wrapped.send(val) |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 216 | def throw(self, tp, *rest): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 217 | return self.__wrapped.throw(tp, *rest) |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 218 | def close(self): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 219 | return self.__wrapped.close() |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 220 | @property |
| 221 | def gi_code(self): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 222 | return self.__wrapped.gi_code |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 223 | @property |
| 224 | def gi_frame(self): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 225 | return self.__wrapped.gi_frame |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 226 | @property |
| 227 | def gi_running(self): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 228 | return self.__wrapped.gi_running |
Yury Selivanov | 53e6230 | 2015-07-03 00:35:02 -0400 | [diff] [blame] | 229 | @property |
| 230 | def gi_yieldfrom(self): |
| 231 | return self.__wrapped.gi_yieldfrom |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 232 | cr_code = gi_code |
| 233 | cr_frame = gi_frame |
| 234 | cr_running = gi_running |
Yury Selivanov | 53e6230 | 2015-07-03 00:35:02 -0400 | [diff] [blame] | 235 | cr_await = gi_yieldfrom |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 236 | def __next__(self): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 237 | return next(self.__wrapped) |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 238 | def __iter__(self): |
Yury Selivanov | f847f1f | 2015-06-24 12:49:28 -0400 | [diff] [blame] | 239 | if self.__isgen: |
| 240 | return self.__wrapped |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 241 | return self |
| 242 | __await__ = __iter__ |
| 243 | |
Yury Selivanov | c565cd5 | 2015-05-29 09:06:05 -0400 | [diff] [blame] | 244 | def coroutine(func): |
| 245 | """Convert regular generator function to a coroutine.""" |
| 246 | |
Yury Selivanov | c565cd5 | 2015-05-29 09:06:05 -0400 | [diff] [blame] | 247 | if not callable(func): |
| 248 | raise TypeError('types.coroutine() expects a callable') |
| 249 | |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 250 | if (func.__class__ is FunctionType and |
| 251 | getattr(func, '__code__', None).__class__ is CodeType): |
Yury Selivanov | c565cd5 | 2015-05-29 09:06:05 -0400 | [diff] [blame] | 252 | |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 253 | co_flags = func.__code__.co_flags |
| 254 | |
| 255 | # Check if 'func' is a coroutine function. |
| 256 | # (0x180 == CO_COROUTINE | CO_ITERABLE_COROUTINE) |
| 257 | if co_flags & 0x180: |
| 258 | return func |
| 259 | |
| 260 | # Check if 'func' is a generator function. |
| 261 | # (0x20 == CO_GENERATOR) |
| 262 | if co_flags & 0x20: |
| 263 | # TODO: Implement this in C. |
| 264 | co = func.__code__ |
Victor Stinner | a9f05d6 | 2019-05-24 23:57:23 +0200 | [diff] [blame] | 265 | # 0x100 == CO_ITERABLE_COROUTINE |
| 266 | func.__code__ = co.replace(co_flags=co.co_flags | 0x100) |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 267 | return func |
Yury Selivanov | c565cd5 | 2015-05-29 09:06:05 -0400 | [diff] [blame] | 268 | |
Yury Selivanov | 13f7723 | 2015-05-29 16:19:18 -0400 | [diff] [blame] | 269 | # The following code is primarily to support functions that |
| 270 | # return generator-like objects (for instance generators |
| 271 | # compiled with Cython). |
| 272 | |
Serhiy Storchaka | 8110837 | 2017-09-26 00:55:55 +0300 | [diff] [blame] | 273 | # Delay functools and _collections_abc import for speeding up types import. |
| 274 | import functools |
| 275 | import _collections_abc |
| 276 | @functools.wraps(func) |
Yury Selivanov | c565cd5 | 2015-05-29 09:06:05 -0400 | [diff] [blame] | 277 | def wrapped(*args, **kwargs): |
| 278 | coro = func(*args, **kwargs) |
Yury Selivanov | fdbeb2b | 2015-07-03 13:11:35 -0400 | [diff] [blame] | 279 | if (coro.__class__ is CoroutineType or |
| 280 | coro.__class__ is GeneratorType and coro.gi_code.co_flags & 0x100): |
| 281 | # 'coro' is a native coroutine object or an iterable coroutine |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 282 | return coro |
Yury Selivanov | fdbeb2b | 2015-07-03 13:11:35 -0400 | [diff] [blame] | 283 | if (isinstance(coro, _collections_abc.Generator) and |
| 284 | not isinstance(coro, _collections_abc.Coroutine)): |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 285 | # 'coro' is either a pure Python generator iterator, or it |
| 286 | # implements collections.abc.Generator (and does not implement |
| 287 | # collections.abc.Coroutine). |
Yury Selivanov | 00e3372 | 2015-06-24 11:44:51 -0400 | [diff] [blame] | 288 | return _GeneratorWrapper(coro) |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 289 | # 'coro' is either an instance of collections.abc.Coroutine or |
| 290 | # some other object -- pass it through. |
Yury Selivanov | c565cd5 | 2015-05-29 09:06:05 -0400 | [diff] [blame] | 291 | return coro |
| 292 | |
| 293 | return wrapped |
| 294 | |
| 295 | |
Serhiy Storchaka | 7beb4f9 | 2015-03-04 09:43:27 +0200 | [diff] [blame] | 296 | __all__ = [n for n in globals() if n[:1] != '_'] |