PyType (Jython API documentation)
Date: 2022-09-10

org.python.core

## Class PyType

- java.lang.Object
- - org.python.core.PyObject
  - - org.python.core.PyType

- All Implemented Interfaces:
    java.io.Serializable, Traverseproc
  Direct Known Subclasses:
    PyJavaType, PyTypeDerived

      public class PyType
      extends PyObject
      implements java.io.Serializable, Traverseproc

  This class implements the Python `type` object and the static methods and data structures that support the Python type system in Jython (the type registry).

  The class `PyType` contains static data that describes Python types, that are consulted and modified through its static API (notably `fromClass(Class)`). The data structures are guarded against modification by concurrent threads (or consultation while being modified). They support construction of `type` objects that are visible to Python.

  Bootstrapping of the type system: The first attempt to construct or get a `PyObject` (or instance of a subclass of `PyObject`), to use the `Py` class utilities, or to call `fromClass(Class)`, causes the Jython type system to be initialised. By the time that call returns, the type system will be in working order: any `PyType`s the application sees will be fully valid. Also, provided that the static initialisation of the `PyObject` subclass in question is not obstructed for any other reason, the instance returned will also be fully functional. Note that it is possible to refer to `C.class`, and (if it is not an exposed type) to produce a `PyType` for it, without causing the static initialisation of `C`.

  This may be no less than the reader expected, but we mention it because, for classes encountered during the bootstrapping of the type system, this guarantee is not offered. The (static) initialisation of the type system is highly reentrant. Classes that are used by the type system itself, and their instances, do encounter defective `PyType` objects. Instances of these classes, which include mundane classes like `PyNone` and `PyString`, may exist before their class is statically initialised in the JVM sense. The type system has been implemented with this fact constantly in mind. The `PyType` encountered is always the "right" one — the unique instance representing the Python type of that class — but it may not be completely filled in. Debugging that enters these classes during bootstrapping will take surprising turns. Changes to these classes should also take this into account.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.python.core.PyObject

      `PyObject.ConversionException`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static PyType` | `TYPE` The `PyType` of `PyType` (or `type(type)`).

    - ### Fields inherited from class org.python.core.PyObject

      `gcMonitorGlobal`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `PyObject` | `__call__(PyObject[] args, java.lang.String[] keywords)` The basic method to override when implementing a callable object.
    `void` | `__delattr__(java.lang.String name)` A variant of the __delattr__ method which accepts a String as the key.
    `PyObject` | `__findattr_ex__(java.lang.String name)` Attribute lookup hook.
    `void` | `__setattr__(java.lang.String name, PyObject value)` A variant of the __setattr__ method which accepts a String as the key.
    `java.lang.Object` | `__tojava__(java.lang.Class<?> c)` Equivalent to the Jython __tojava__ method.
    `static void` | `addBuilder(java.lang.Class<?> c, org.python.expose.TypeBuilder builder)` Register the `TypeBuilder` for the given class.
    `void` | `addMethod(PyBuiltinMethod meth)` Adds the given method to this type's dict under its name in its descriptor.
    `void` | `compatibleForAssignment(PyType other, java.lang.String attribute)` Ensures that the physical layout between this type and `other` are compatible.
    `void` | `delBases()`
    `void` | `delDict()`
    `void` | `delModule()`
    `static boolean` | `ensureBootstrapped()` Attempt to ensure that the that the type system has fully constructed the types necessary to build a fully-working, exposed, `PyObject` (the "bootstrap types").
    `static void` | `ensureDoc(PyObject dict)` Ensure dict contains a __doc__.
    `static void` | `ensureModule(PyObject dict)` Ensure dict contains a __module__, retrieving it from the current frame if it doesn't exist.
    `PyObject` | `fastGetDict()` Returns the actual dict underlying this type instance.
    `java.lang.String` | `fastGetName()`
    `static PyType` | `fromClass(java.lang.Class<?> c)` Look up (create if necessary) the `PyType` for the given target Java class.
    `static PyType` | `fromClass(java.lang.Class<?> c, boolean hardRef)` Equivalent to `fromClass(Class)`, which is to be preferred.
    `PyObject` | `getAbstractmethods()`
    `PyObject` | `getBase()`
    `PyObject` | `getBases()`
    `PyObject` | `getDict()` xxx implements where meaningful
    `PyObject` | `getDoc()` Equivalent of CPython's typeobject.c::type_get_doc; handles __doc__ descriptors.
    `PyLong` | `getFlags()`
    `PyObject` | `getModule()`
    `PyTuple` | `getMro()`
    `java.lang.String` | `getName()`
    `int` | `getNumSlots()`
    `java.lang.Class<?>` | `getProxyType()` Returns the Java Class that this type inherits from, or null if this type is Python-only.
    `PyObject` | `getStatic()`
    `PyObject` | `instDict()`
    `boolean` | `isSubType(PyType supertype)`
    `PyObject` | `lookup_where(java.lang.String name, PyObject[] where)` Attribute lookup for name through mro objects' dicts.
    `PyObject` | `lookup(java.lang.String name)` Attribute lookup for name through mro objects' dicts.
    `boolean` | `needsFinalizer()` Offers public read-only access to the protected field needs_finalizer.
    `static PyObject` | `newType(PyNewWrapper new_, PyType metatype, java.lang.String name, PyTuple bases, PyObject dict)`
    `void` | `noAttributeError(java.lang.String name)` Raises AttributeError on type objects.
    `void` | `pyDelName()`
    `PyObject` | `pyGetName()`
    `void` | `pySetName(PyObject name)`
    `boolean` | `refersDirectlyTo(PyObject ob)` Optional operation.
    `void` | `removeMethod(PyBuiltinMethod meth)` Removes the given method from this type's dict or raises a KeyError.
    `void` | `setAbstractmethods(PyObject value)`
    `void` | `setBases(PyObject newBasesTuple)`
    `void` | `setDict(PyObject newDict)`
    `void` | `setName(java.lang.String name)`
    `PyObject` | `super_lookup(PyType ref, java.lang.String name)`
    `java.lang.String` | `toString()`
    `int` | `traverse(Visitproc visit, java.lang.Object arg)` Traverses all directly contained `PyObject`s.
    `PyObject` | `type___eq__(PyObject other)`
    `PyObject` | `type___ge__(PyObject other)`
    `PyObject` | `type___gt__(PyObject other)`
    `boolean` | `type___instancecheck__(PyObject inst)`
    `PyObject` | `type___le__(PyObject other)`
    `PyObject` | `type___lt__(PyObject other)`
    `PyObject` | `type___ne__(PyObject other)`
    `boolean` | `type___subclasscheck__(PyObject inst)`
    `PyObject` | `type___subclasses__()`

    - ### Methods inherited from class org.python.core.PyObject

      `__abs__, __add__, __and__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __cmp__, __coerce__, __coerce_ex__, __complex__, __contains__, __delattr__, __delete__, __delitem__, __delitem__, __delslice__, __delslice__, __dir__, __div__, __divmod__, __ensure_finalizer__, __eq__, __findattr__, __findattr__, __finditem__, __finditem__, __finditem__, __float__, __floordiv__, __format__, __ge__, __get__, __getattr__, __getattr__, __getitem__, __getitem__, __getnewargs__, __getslice__, __getslice__, __gt__, __hash__, __hex__, __iadd__, __iand__, __idiv__, __idivmod__, __ifloordiv__, __ilshift__, __imod__, __imul__, __index__, __int__, __invert__, __ior__, __ipow__, __irshift__, __isub__, __iter__, __iternext__, __itruediv__, __ixor__, __le__, __len__, __long__, __lshift__, __lt__, __mod__, __mul__, __ne__, __neg__, __nonzero__, __not__, __oct__, __or__, __pos__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce__, __reduce_ex__, __reduce_ex__, __repr__, __rfloordiv__, __rlshift__, __rmod__, __rmul__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setitem__, __setitem__, __setitem__, __setslice__, __setslice__, __str__, __sub__, __truediv__, __trunc__, __unicode__, __xor__, _add, _and, _callextra, _cmp, _div, _divmod, _doget, _doget, _doset, _eq, _floordiv, _ge, _gt, _iadd, _iand, _idiv, _idivmod, _ifloordiv, _ilshift, _imod, _imul, _in, _ior, _ipow, _irshift, _is, _isnot, _isub, _itruediv, _ixor, _jcall, _jcallexc, _jthrow, _le, _lshift, _lt, _mod, _mul, _ne, _notin, _or, _pow, _rshift, _sub, _truediv, _xor, asDouble, asIndex, asIndex, asInt, asInt, asIterable, asLong, asLong, asName, asName, asString, asString, asStringOrNull, asStringOrNull, bit_length, conjugate, delType, dispatch__init__, equals, fastGetClass, getType, hashCode, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, isMappingType, isNumberType, isSequenceType, object___subclasshook__, readonlyAttributeError, setType`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### TYPE

          public static final PyType TYPE

      The `PyType` of `PyType` (or `type(type)`).

  - ### Method Detail

    - #### newType

          public static PyObject newType(PyNewWrapper new_,
                                         PyType metatype,
                                         java.lang.String name,
                                         PyTuple bases,
                                         PyObject dict)

    - #### ensureDoc

          public static void ensureDoc(PyObject dict)

      Ensure dict contains a __doc__.
      Parameters:
        `dict` - a PyObject mapping

    - #### ensureModule

          public static void ensureModule(PyObject dict)

      Ensure dict contains a __module__, retrieving it from the current frame if it doesn't exist.
      Parameters:
        `dict` - a PyObject mapping

    - #### getStatic

          public PyObject getStatic()

    - #### needsFinalizer

          public final boolean needsFinalizer()

      Offers public read-only access to the protected field needs_finalizer.
      Returns:
        a boolean indicating whether the type implements __del__

    - #### compatibleForAssignment

          public void compatibleForAssignment(PyType other,
                                              java.lang.String attribute)

      Ensures that the physical layout between this type and `other` are compatible. Raises a TypeError if not.

    - #### type___eq__

          public PyObject type___eq__(PyObject other)

    - #### type___ne__

          public PyObject type___ne__(PyObject other)

    - #### type___le__

          public PyObject type___le__(PyObject other)

    - #### type___lt__

          public PyObject type___lt__(PyObject other)

    - #### type___ge__

          public PyObject type___ge__(PyObject other)

    - #### type___gt__

          public PyObject type___gt__(PyObject other)

    - #### getBase

          public PyObject getBase()

    - #### getBases

          public PyObject getBases()

    - #### delBases

          public void delBases()

    - #### setBases

          public void setBases(PyObject newBasesTuple)

    - #### instDict

          public PyObject instDict()

    - #### getMro

          public PyTuple getMro()

    - #### getFlags

          public PyLong getFlags()

    - #### type___subclasses__

          public final PyObject type___subclasses__()

    - #### type___subclasscheck__

          public final boolean type___subclasscheck__(PyObject inst)

    - #### type___instancecheck__

          public final boolean type___instancecheck__(PyObject inst)

    - #### getProxyType

          public java.lang.Class<?> getProxyType()

      Returns the Java Class that this type inherits from, or null if this type is Python-only.

    - #### isSubType

          public boolean isSubType(PyType supertype)

    - #### lookup

          public PyObject lookup(java.lang.String name)

      Attribute lookup for name through mro objects' dicts. Lookups are cached.
      Parameters:
        `name` - attribute name (must be interned)
      Returns:
        found object or null

    - #### lookup_where

          public PyObject lookup_where(java.lang.String name,
                                       PyObject[] where)

      Attribute lookup for name through mro objects' dicts. Lookups are cached. Returns where in the mro the attribute was found at where[0].
      Parameters:
        `name` - attribute name (must be interned)
        `where` - Where in the mro the attribute was found is written to index 0
      Returns:
        found object or null

    - #### super_lookup

          public PyObject super_lookup(PyType ref,
                                       java.lang.String name)

    - #### addBuilder

          public static void addBuilder(java.lang.Class<?> c,
                                        org.python.expose.TypeBuilder builder)

      Register the `TypeBuilder` for the given class. This only really makes sense for a `PyObject`. Initialising a properly-formed PyObject will usually result in a call to `addBuilder`, thanks to code inserted by the Jython type-exposer.
      Parameters:
        `c` - class for which this is the builder
        `builder` - to register

    - #### ensureBootstrapped

          public static boolean ensureBootstrapped()

      Attempt to ensure that the that the type system has fully constructed the types necessary to build a fully-working, exposed, `PyObject` (the "bootstrap types"). Produce a warning message if it does not seem to have worked. This is called at the end of the static initialisation of `PyObject`.
      Returns:
        whether bootstrapping was successful

    - #### fromClass

          public static PyType fromClass(java.lang.Class<?> c,
                                         boolean hardRef)

      Equivalent to `fromClass(Class)`, which is to be preferred.

      The boolean argument is ignored. Previously it controlled whether the returned `PyType` remained strongly-reachable through a reference the type registry would keep. The returned object is now reachable as long as the class `c` remains loaded.

      Parameters:
        `c` - for which the corresponding `PyType` is to be found
        `hardRef` - ignored
      Returns:
        the `PyType` found or created

    - #### fromClass

          public static PyType fromClass(java.lang.Class<?> c)

      Look up (create if necessary) the `PyType` for the given target Java class. If the target's `PyType` already exists, this is returned quickly. When a `PyType` must be created, the method updates the registry of type information internal to Jython, caching the answer for next time.

      Creating the `PyType` also looks up or creates any `PyType`s that the target depends upon, which results in re-entrant calls to `fromClass` for these classes and (if `PyType`s are created for `PyObject`s) calls to `addBuilder(Class, TypeBuilder)`.

      Look-up of existing types is non-blocking in the majority of cases.

      Parameters:
        `c` - for which the corresponding `PyType` is to be found
      Returns:
        the `PyType` found or created

    - #### __findattr_ex__

          public PyObject __findattr_ex__(java.lang.String name)

      Description copied from class: `PyObject`
      Attribute lookup hook. If the attribute is not found, null may be returned or a Py.AttributeError can be thrown, whatever is more correct, efficient and/or convenient for the implementing class. Client code should use `PyObject.__getattr__(String)` or `PyObject.__findattr__(String)`. Both methods have a clear policy for failed lookups.
      Overrides:
        `__findattr_ex__` in class `PyObject`
      Returns:
        The looked up value. May return null if the attribute is not found

    - #### __setattr__

          public void __setattr__(java.lang.String name,
                                  PyObject value)

      Description copied from class: `PyObject`
      A variant of the __setattr__ method which accepts a String as the key. This String must be interned.
      Overrides:
        `__setattr__` in class `PyObject`
      Parameters:
        `name` - the name whose value will be set - must be an interned string .
        `value` - the value to set this name to
      See Also:
        `PyObject.__setattr__(PyString, PyObject)`

    - #### addMethod

          public void addMethod(PyBuiltinMethod meth)

      Adds the given method to this type's dict under its name in its descriptor. If there's an existing item in the dict, it's replaced.

    - #### removeMethod

          public void removeMethod(PyBuiltinMethod meth)

      Removes the given method from this type's dict or raises a KeyError.

    - #### __delattr__

          public void __delattr__(java.lang.String name)

      Description copied from class: `PyObject`
      A variant of the __delattr__ method which accepts a String as the key. This String must be interned. By default, this will call `__delattr__(PyString name)` with the appropriate args. The only reason to override this method is for performance.
      Overrides:
        `__delattr__` in class `PyObject`
      Parameters:
        `name` - the name which will be removed - must be an interned string .
      See Also:
        `PyObject.__delattr__(PyString)`

    - #### __call__

          public PyObject __call__(PyObject[] args,
                                   java.lang.String[] keywords)

      Description copied from class: `PyObject`
      The basic method to override when implementing a callable object. The first len(args)-len(keywords) members of args[] are plain arguments. The last len(keywords) arguments are the values of the keyword arguments.
      Overrides:
        `__call__` in class `PyObject`
      Parameters:
        `args` - all arguments to the function (including keyword arguments).
        `keywords` - the keywords used for all keyword arguments.

    - #### fastGetName

          public java.lang.String fastGetName()

    - #### pyGetName

          public PyObject pyGetName()

    - #### getName

          public java.lang.String getName()

    - #### pySetName

          public void pySetName(PyObject name)

    - #### setName

          public void setName(java.lang.String name)

    - #### pyDelName

          public void pyDelName()

    - #### fastGetDict

          public PyObject fastGetDict()

      Returns the actual dict underlying this type instance. Changes to Java types should go through `addMethod(org.python.core.PyBuiltinMethod)` and `removeMethod(org.python.core.PyBuiltinMethod)`, or unexpected mro errors can occur.
      Overrides:
        `fastGetDict` in class `PyObject`
      Returns:
        internal object per instance dict or null

    - #### getDict

          public PyObject getDict()

      Description copied from class: `PyObject`
      xxx implements where meaningful
      Overrides:
        `getDict` in class `PyObject`
      Returns:
        internal object __dict__ or null

    - #### setDict

          public void setDict(PyObject newDict)

      Overrides:
        `setDict` in class `PyObject`

    - #### delDict

          public void delDict()

      Overrides:
        `delDict` in class `PyObject`

    - #### getDoc

          public PyObject getDoc()

      Equivalent of CPython's typeobject.c::type_get_doc; handles __doc__ descriptors.

    - #### __tojava__

          public java.lang.Object __tojava__(java.lang.Class<?> c)

      Description copied from class: `PyObject`
      Equivalent to the Jython __tojava__ method. Tries to coerce this object to an instance of the requested Java class. Returns the special object `Py.NoConversion` if this `PyObject` can not be converted to the desired Java class.
      Overrides:
        `__tojava__` in class `PyObject`
      Parameters:
        `c` - the Class to convert this `PyObject` to.

    - #### getModule

          public PyObject getModule()

    - #### delModule

          public void delModule()

    - #### getAbstractmethods

          public PyObject getAbstractmethods()

    - #### setAbstractmethods

          public void setAbstractmethods(PyObject value)

    - #### getNumSlots

          public int getNumSlots()

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `PyObject`

    - #### noAttributeError

          public void noAttributeError(java.lang.String name)

      Raises AttributeError on type objects. The message differs from PyObject#noAttributeError, to mimic CPython behaviour.
      Overrides:
        `noAttributeError` in class `PyObject`

    - #### traverse

          public int traverse(Visitproc visit,
                              java.lang.Object arg)

      Description copied from interface: `Traverseproc`
      Traverses all directly contained `PyObject`s. Like in CPython, `arg` must be passed unmodified to `visit` as its second parameter. If `Visitproc.visit(PyObject, Object)` returns nonzero, this return value must be returned immediately by traverse. `Visitproc.visit(PyObject, Object)` must not be called with a `null` PyObject-argument.
      Specified by:
        `traverse` in interface `Traverseproc`

    - #### refersDirectlyTo

          public boolean refersDirectlyTo(PyObject ob)
                                   throws java.lang.UnsupportedOperationException

      Description copied from interface: `Traverseproc`
      Optional operation. Should only be implemented if it is more efficient than calling `Traverseproc.traverse(Visitproc, Object)` with a visitproc that just watches out for `ob`. Must return `false` if `ob` is `null`.
      Specified by:
        `refersDirectlyTo` in interface `Traverseproc`
      Throws:
        `java.lang.UnsupportedOperationException`

Jython homepage