cpython/Objects/descrobject.c

/* Descriptors -- a new, flexible way to describe attributes */

#include "Python.h"
#include "pycore_abstract.h"      // _PyObject_RealIsSubclass()
#include "pycore_call.h"          // _PyStack_AsDict()
#include "pycore_ceval.h"         // _Py_EnterRecursiveCallTstate()
#include "pycore_emscripten_trampoline.h" // descr_set_trampoline_call(), descr_get_trampoline_call()
#include "pycore_descrobject.h"   // _PyMethodWrapper_Type
#include "pycore_modsupport.h"    // _PyArg_UnpackStack()
#include "pycore_object.h"        // _PyObject_GC_UNTRACK()
#include "pycore_pystate.h"       // _PyThreadState_GET()
#include "pycore_tuple.h"         // _PyTuple_ITEMS()


/*[clinic input]
class mappingproxy "mappingproxyobject *" "&PyDictProxy_Type"
class property "propertyobject *" "&PyProperty_Type"
[clinic start generated code]*/
/*[clinic end generated code: output=da39a3ee5e6b4b0d input=556352653fd4c02e]*/

static void
descr_dealloc(PyObject *self)
{ … }

static PyObject *
descr_name(PyDescrObject *descr)
{ … }

static PyObject *
descr_repr(PyDescrObject *descr, const char *format)
{ … }

static PyObject *
method_repr(PyObject *descr)
{ … }

static PyObject *
member_repr(PyObject *descr)
{ … }

static PyObject *
getset_repr(PyObject *descr)
{ … }

static PyObject *
wrapperdescr_repr(PyObject *descr)
{ … }

static int
descr_check(PyDescrObject *descr, PyObject *obj)
{ … }

static PyObject *
classmethod_get(PyObject *self, PyObject *obj, PyObject *type)
{ … }

static PyObject *
method_get(PyObject *self, PyObject *obj, PyObject *type)
{ … }

static PyObject *
member_get(PyObject *self, PyObject *obj, PyObject *type)
{ … }

static PyObject *
getset_get(PyObject *self, PyObject *obj, PyObject *type)
{ … }

static PyObject *
wrapperdescr_get(PyObject *self, PyObject *obj, PyObject *type)
{ … }

static int
descr_setcheck(PyDescrObject *descr, PyObject *obj, PyObject *value)
{ … }

static int
member_set(PyObject *self, PyObject *obj, PyObject *value)
{ … }

static int
getset_set(PyObject *self, PyObject *obj, PyObject *value)
{ … }


/* Vectorcall functions for each of the PyMethodDescr calling conventions.
 *
 * First, common helpers
 */
static inline int
method_check_args(PyObject *func, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
{ … }

funcptr;

static inline funcptr
method_enter_call(PyThreadState *tstate, PyObject *func)
{ … }

/* Now the actual vectorcall functions */
static PyObject *
method_vectorcall_VARARGS(
    PyObject *func, PyObject *const *args, size_t nargsf, PyObject *kwnames)
{ … }

static PyObject *
method_vectorcall_VARARGS_KEYWORDS(
    PyObject *func, PyObject *const *args, size_t nargsf, PyObject *kwnames)
{ … }

static PyObject *
method_vectorcall_FASTCALL_KEYWORDS_METHOD(
    PyObject *func, PyObject *const *args, size_t nargsf, PyObject *kwnames)
{ … }

static PyObject *
method_vectorcall_FASTCALL(
    PyObject *func, PyObject *const *args, size_t nargsf, PyObject *kwnames)
{ … }

static PyObject *
method_vectorcall_FASTCALL_KEYWORDS(
    PyObject *func, PyObject *const *args, size_t nargsf, PyObject *kwnames)
{ … }

static PyObject *
method_vectorcall_NOARGS(
    PyObject *func, PyObject *const *args, size_t nargsf, PyObject *kwnames)
{ … }

static PyObject *
method_vectorcall_O(
    PyObject *func, PyObject *const *args, size_t nargsf, PyObject *kwnames)
{ … }


/* Instances of classmethod_descriptor are unlikely to be called directly.
   For one, the analogous class "classmethod" (for Python classes) is not
   callable. Second, users are not likely to access a classmethod_descriptor
   directly, since it means pulling it from the class __dict__.

   This is just an excuse to say that this doesn't need to be optimized:
   we implement this simply by calling __get__ and then calling the result.
*/
static PyObject *
classmethoddescr_call(PyObject *_descr, PyObject *args,
                      PyObject *kwds)
{ … }

Py_LOCAL_INLINE(PyObject *)
wrapperdescr_raw_call(PyWrapperDescrObject *descr, PyObject *self,
                      PyObject *args, PyObject *kwds)
{ … }

static PyObject *
wrapperdescr_call(PyObject *_descr, PyObject *args, PyObject *kwds)
{ … }


static PyObject *
method_get_doc(PyObject *_descr, void *closure)
{ … }

static PyObject *
method_get_text_signature(PyObject *_descr, void *closure)
{ … }

static PyObject *
calculate_qualname(PyDescrObject *descr)
{ … }

static PyObject *
descr_get_qualname(PyObject *self, void *Py_UNUSED(ignored))
{ … }

static PyObject *
descr_reduce(PyObject *self, PyObject *Py_UNUSED(ignored))
{ … }

static PyMethodDef descr_methods[] = …;

static PyMemberDef descr_members[] = …;

static PyGetSetDef method_getset[] = …;

static PyObject *
member_get_doc(PyObject *_descr, void *closure)
{ … }

static PyGetSetDef member_getset[] = …;

static PyObject *
getset_get_doc(PyObject *self, void *closure)
{ … }

static PyGetSetDef getset_getset[] = …;

static PyObject *
wrapperdescr_get_doc(PyObject *self, void *closure)
{ … }

static PyObject *
wrapperdescr_get_text_signature(PyObject *self, void *closure)
{ … }

static PyGetSetDef wrapperdescr_getset[] = …;

static int
descr_traverse(PyObject *self, visitproc visit, void *arg)
{ … }

PyTypeObject PyMethodDescr_Type = …;

/* This is for METH_CLASS in C, not for "f = classmethod(f)" in Python! */
PyTypeObject PyClassMethodDescr_Type = …;

PyTypeObject PyMemberDescr_Type = …;

PyTypeObject PyGetSetDescr_Type = …;

PyTypeObject PyWrapperDescr_Type = …;

static PyDescrObject *
descr_new(PyTypeObject *descrtype, PyTypeObject *type, const char *name)
{ … }

PyObject *
PyDescr_NewMethod(PyTypeObject *type, PyMethodDef *method)
{ … }

PyObject *
PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
{ … }

PyObject *
PyDescr_NewMember(PyTypeObject *type, PyMemberDef *member)
{ … }

PyObject *
PyDescr_NewGetSet(PyTypeObject *type, PyGetSetDef *getset)
{ … }

PyObject *
PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
{ … }

int
PyDescr_IsData(PyObject *ob)
{ … }

/* --- mappingproxy: read-only proxy for mappings --- */

/* This has no reason to be in this file except that adding new files is a
   bit of a pain */

mappingproxyobject;

static Py_ssize_t
mappingproxy_len(PyObject *self)
{ … }

static PyObject *
mappingproxy_getitem(PyObject *self, PyObject *key)
{ … }

static PyMappingMethods mappingproxy_as_mapping = …;

static PyObject *
mappingproxy_or(PyObject *left, PyObject *right)
{ … }

static PyObject *
mappingproxy_ior(PyObject *self, PyObject *Py_UNUSED(other))
{ … }

static PyNumberMethods mappingproxy_as_number = …;

static int
mappingproxy_contains(PyObject *self, PyObject *key)
{ … }

static PySequenceMethods mappingproxy_as_sequence = …;

static PyObject *
mappingproxy_get(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
{ … }

static PyObject *
mappingproxy_keys(PyObject *self, PyObject *Py_UNUSED(ignored))
{ … }

static PyObject *
mappingproxy_values(PyObject *self, PyObject *Py_UNUSED(ignored))
{ … }

static PyObject *
mappingproxy_items(PyObject *self, PyObject *Py_UNUSED(ignored))
{ … }

static PyObject *
mappingproxy_copy(PyObject *self, PyObject *Py_UNUSED(ignored))
{ … }

static PyObject *
mappingproxy_reversed(PyObject *self, PyObject *Py_UNUSED(ignored))
{ … }

/* WARNING: mappingproxy methods must not give access
            to the underlying mapping */

static PyMethodDef mappingproxy_methods[] = …;

static void
mappingproxy_dealloc(PyObject *self)
{ … }

static PyObject *
mappingproxy_getiter(PyObject *self)
{ … }

static Py_hash_t
mappingproxy_hash(PyObject *self)
{ … }

static PyObject *
mappingproxy_str(PyObject *self)
{ … }

static PyObject *
mappingproxy_repr(PyObject *self)
{ … }

static int
mappingproxy_traverse(PyObject *self, visitproc visit, void *arg)
{ … }

static PyObject *
mappingproxy_richcompare(PyObject *self, PyObject *w, int op)
{ … }

static int
mappingproxy_check_mapping(PyObject *mapping)
{ … }

/*[clinic input]
@classmethod
mappingproxy.__new__ as mappingproxy_new

    mapping: object

Read-only proxy of a mapping.
[clinic start generated code]*/

static PyObject *
mappingproxy_new_impl(PyTypeObject *type, PyObject *mapping)
/*[clinic end generated code: output=65f27f02d5b68fa7 input=c156df096ef7590c]*/
{ … }

PyObject *
PyDictProxy_New(PyObject *mapping)
{ … }


/* --- Wrapper object for "slot" methods --- */

/* This has no reason to be in this file except that adding new files is a
   bit of a pain */

wrapperobject;

#define Wrapper_Check(v) …

static void
wrapper_dealloc(PyObject *self)
{ … }

static PyObject *
wrapper_richcompare(PyObject *a, PyObject *b, int op)
{ … }

static Py_hash_t
wrapper_hash(PyObject *self)
{ … }

static PyObject *
wrapper_repr(PyObject *self)
{ … }

static PyObject *
wrapper_reduce(PyObject *self, PyObject *Py_UNUSED(ignored))
{ … }

static PyMethodDef wrapper_methods[] = …;

static PyMemberDef wrapper_members[] = …;

static PyObject *
wrapper_objclass(PyObject *wp, void *Py_UNUSED(ignored))
{ … }

static PyObject *
wrapper_name(PyObject *wp, void *Py_UNUSED(ignored))
{ … }

static PyObject *
wrapper_doc(PyObject *self, void *Py_UNUSED(ignored))
{ … }

static PyObject *
wrapper_text_signature(PyObject *self, void *Py_UNUSED(ignored))
{ … }

static PyObject *
wrapper_qualname(PyObject *self, void *Py_UNUSED(ignored))
{ … }

static PyGetSetDef wrapper_getsets[] = …;

static PyObject *
wrapper_call(PyObject *self, PyObject *args, PyObject *kwds)
{ … }

static int
wrapper_traverse(PyObject *self, visitproc visit, void *arg)
{ … }

PyTypeObject _PyMethodWrapper_Type = …;

PyObject *
PyWrapper_New(PyObject *d, PyObject *self)
{ … }


/* A built-in 'property' type */

/*
class property(object):

    def __init__(self, fget=None, fset=None, fdel=None, doc=None):
        if doc is None and fget is not None and hasattr(fget, "__doc__"):
            doc = fget.__doc__
        self.__get = fget
        self.__set = fset
        self.__del = fdel
        try:
            self.__doc__ = doc
        except AttributeError:  # read-only or dict-less class
            pass
        self.__name = None

    def __set_name__(self, owner, name):
        self.__name = name

    @property
    def __name__(self):
        return self.__name if self.__name is not None else self.fget.__name__

    @__name__.setter
    def __name__(self, value):
        self.__name = value

    def __get__(self, inst, type=None):
        if inst is None:
            return self
        if self.__get is None:
            raise AttributeError("property has no getter")
        return self.__get(inst)

    def __set__(self, inst, value):
        if self.__set is None:
            raise AttributeError("property has no setter")
        return self.__set(inst, value)

    def __delete__(self, inst):
        if self.__del is None:
            raise AttributeError("property has no deleter")
        return self.__del(inst)

*/

static PyObject * property_copy(PyObject *, PyObject *, PyObject *,
                                  PyObject *);

static PyMemberDef property_members[] = …;


PyDoc_STRVAR(getter_doc,
             "Descriptor to obtain a copy of the property with a different getter.");

static PyObject *
property_getter(PyObject *self, PyObject *getter)
{ … }


PyDoc_STRVAR(setter_doc,
             "Descriptor to obtain a copy of the property with a different setter.");

static PyObject *
property_setter(PyObject *self, PyObject *setter)
{ … }


PyDoc_STRVAR(deleter_doc,
             "Descriptor to obtain a copy of the property with a different deleter.");

static PyObject *
property_deleter(PyObject *self, PyObject *deleter)
{ … }


PyDoc_STRVAR(set_name_doc,
             "__set_name__($self, owner, name, /)\n"
             "--\n"
             "\n"
             "Method to set name of a property.");

static PyObject *
property_set_name(PyObject *self, PyObject *args) { … }

static PyMethodDef property_methods[] = …;


static void
property_dealloc(PyObject *self)
{ … }

static int
property_name(propertyobject *prop, PyObject **name)
{ … }

static PyObject *
property_descr_get(PyObject *self, PyObject *obj, PyObject *type)
{ … }

static int
property_descr_set(PyObject *self, PyObject *obj, PyObject *value)
{ … }

static PyObject *
property_copy(PyObject *old, PyObject *get, PyObject *set, PyObject *del)
{ … }

/*[clinic input]
property.__init__ as property_init

    fget: object(c_default="NULL") = None
        function to be used for getting an attribute value
    fset: object(c_default="NULL") = None
        function to be used for setting an attribute value
    fdel: object(c_default="NULL") = None
        function to be used for del'ing an attribute
    doc: object(c_default="NULL") = None
        docstring

Property attribute.

Typical use is to define a managed attribute x:

class C(object):
    def getx(self): return self._x
    def setx(self, value): self._x = value
    def delx(self): del self._x
    x = property(getx, setx, delx, "I'm the 'x' property.")

Decorators make defining new properties or modifying existing ones easy:

class C(object):
    @property
    def x(self):
        "I am the 'x' property."
        return self._x
    @x.setter
    def x(self, value):
        self._x = value
    @x.deleter
    def x(self):
        del self._x
[clinic start generated code]*/

static int
property_init_impl(propertyobject *self, PyObject *fget, PyObject *fset,
                   PyObject *fdel, PyObject *doc)
/*[clinic end generated code: output=01a960742b692b57 input=dfb5dbbffc6932d5]*/
{ … }

static PyObject *
property_get__name__(propertyobject *prop, void *Py_UNUSED(ignored))
{ … }

static int
property_set__name__(propertyobject *prop, PyObject *value,
                     void *Py_UNUSED(ignored))
{ … }

static PyObject *
property_get___isabstractmethod__(propertyobject *prop, void *closure)
{ … }

static PyGetSetDef property_getsetlist[] = …;

static int
property_traverse(PyObject *self, visitproc visit, void *arg)
{ … }

static int
property_clear(PyObject *self)
{ … }

#include "clinic/descrobject.c.h"

PyTypeObject PyDictProxy_Type = …;

PyTypeObject PyProperty_Type = …;