From d387f82958806449c953cf8775cf90b5629f1d73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Sun, 24 Mar 2019 22:17:40 +0100 Subject: [PATCH 1/3] bpo-36347: Renaming the constants for the PyMemberDef.flags * Declaration of new constants for the PyMemberDef.flags with an enumeration and with the PY_ prefix (convention of the C-API for the public names). The redeclaration is for the backward compatibility. * Use __attribute__(deprecate) for the deprecation of the former constants. * Update the documentation about the new constants. --- Doc/c-api/structures.rst | 10 +++++----- Doc/extending/newtypes.rst | 29 ++++++++++++++++++----------- Include/structmember.h | 22 +++++++++++++++++----- 3 files changed, 40 insertions(+), 21 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index da45da1d3c70db..f1a76f33c2a079 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -290,11 +290,11 @@ definition with the same method name. handles use of the :keyword:`del` statement on that attribute more correctly than :c:macro:`T_OBJECT`. - :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for - read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies - :c:macro:`READONLY`. :c:macro:`T_STRING` data is interpreted as UTF-8. - Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` - members can be deleted. (They are set to *NULL*). + :attr:`flags` can be ``0`` for write and read access (also represented by the + :c:macro:`PY_READWRITE`) or or :c:macro:`PY_READONLY` for read-only access. + Using :c:macro:`T_STRING` for :attr:`type` implies :c:macro:`PY_READONLY`. + :c:macro:`T_STRING` data is interpreted as UTF-8. Only :c:macro:`T_OBJECT` + and :c:macro:`T_OBJECT_EX` members can be deleted. (They are set to *NULL*). .. c:type:: PyGetSetDef diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index 8b9549d7e39e2e..4080f6dd91b490 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -282,23 +282,30 @@ store flags which control how the attribute can be accessed. The following flag constants are defined in :file:`structmember.h`; they may be combined using bitwise-OR. -+---------------------------+----------------------------------------------+ -| Constant | Meaning | -+===========================+==============================================+ -| :const:`READONLY` | Never writable. | -+---------------------------+----------------------------------------------+ -| :const:`READ_RESTRICTED` | Not readable in restricted mode. | -+---------------------------+----------------------------------------------+ -| :const:`WRITE_RESTRICTED` | Not writable in restricted mode. | -+---------------------------+----------------------------------------------+ -| :const:`RESTRICTED` | Not readable or writable in restricted mode. | -+---------------------------+----------------------------------------------+ ++------------------------------+----------------------------------------------+---------------------------+ +| Constant | Meaning | Former Constant | ++==============================+==============================================+===========================+ +| :const:`PY_READWRITE` | Writable. | 0 | ++------------------------------+----------------------------------------------+---------------------------+ +| :const:`PY_READONLY` | Never writable. | :const:`READONLY` | ++------------------------------+----------------------------------------------+---------------------------+ +| :const:`PY_READ_RESTRICTED` | Not readable in restricted mode. | :const:`READ_RESTRICTED` | ++------------------------------+----------------------------------------------+---------------------------+ +| :const:`PY_WRITE_RESTRICTED` | Not writable in restricted mode. | :const:`WRITE_RESTRICTED` | ++------------------------------+----------------------------------------------+---------------------------+ +| :const:`PY_RESTRICTED` | Not readable or writable in restricted mode. | :const:`RESTRICTED` | ++------------------------------+----------------------------------------------+---------------------------+ .. index:: single: READONLY single: READ_RESTRICTED single: WRITE_RESTRICTED single: RESTRICTED + single: PY_READWRITE + single: PY_READONLY + single: PY_READ_RESTRICTED + single: PY_WRITE_RESTRICTED + single: PY_RESTRICTED An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table to build descriptors that are used at runtime is that any attribute defined this way can diff --git a/Include/structmember.h b/Include/structmember.h index b54f7081f458dd..725fcd2cb325a0 100644 --- a/Include/structmember.h +++ b/Include/structmember.h @@ -57,11 +57,23 @@ typedef struct PyMemberDef { /* Flags */ -#define READONLY 1 -#define READ_RESTRICTED 2 -#define PY_WRITE_RESTRICTED 4 -#define RESTRICTED (READ_RESTRICTED | PY_WRITE_RESTRICTED) - +enum PyMemberDefFlagEnum { + PY_READWRITE = 0, + PY_READONLY = 1, + PY_READ_RESTRICTED = 2, + PY_WRITE_RESTRICTED = 4, + PY_RESTRICTED = (PY_READ_RESTRICTED | PY_WRITE_RESTRICTED), + +#define DEPRECATED(attribute) \ + __attribute__((deprecated("use "#attribute))) = attribute + + // Flags for backward-compatibility + READONLY DEPRECATED(PY_READONLY), + READWRITE DEPRECATED(PY_READWRITE), + READ_RESTRICTED DEPRECATED(PY_READ_RESTRICTED), + RESTRICTED DEPRECATED(PY_RESTRICTED) +#undef DEPRECATED +}; /* Current API, use this */ PyAPI_FUNC(PyObject *) PyMember_GetOne(const char *, struct PyMemberDef *); From 7455640285cf88271271e88c5e436f5128a2eb63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Sun, 24 Mar 2019 23:31:03 +0100 Subject: [PATCH 2/3] Use Py_DEPRECATED macro --- Include/structmember.h | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/Include/structmember.h b/Include/structmember.h index 725fcd2cb325a0..2d712a3cc7cf6e 100644 --- a/Include/structmember.h +++ b/Include/structmember.h @@ -64,15 +64,11 @@ enum PyMemberDefFlagEnum { PY_WRITE_RESTRICTED = 4, PY_RESTRICTED = (PY_READ_RESTRICTED | PY_WRITE_RESTRICTED), -#define DEPRECATED(attribute) \ - __attribute__((deprecated("use "#attribute))) = attribute - // Flags for backward-compatibility - READONLY DEPRECATED(PY_READONLY), - READWRITE DEPRECATED(PY_READWRITE), - READ_RESTRICTED DEPRECATED(PY_READ_RESTRICTED), - RESTRICTED DEPRECATED(PY_RESTRICTED) -#undef DEPRECATED + READONLY Py_DEPRECATED(3.8) = PY_READONLY, + READWRITE Py_DEPRECATED(3.8) = PY_READWRITE, + READ_RESTRICTED Py_DEPRECATED(3.8) = PY_READ_RESTRICTED, + RESTRICTED Py_DEPRECATED(3.8) = PY_RESTRICTED }; /* Current API, use this */ From 234fba82db458cba2f510160110e5172ab8634fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Mon, 25 Mar 2019 11:37:59 +0100 Subject: [PATCH 3/3] Use an anonymous enumeration --- Include/structmember.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Include/structmember.h b/Include/structmember.h index 2d712a3cc7cf6e..55b70293b9ac8c 100644 --- a/Include/structmember.h +++ b/Include/structmember.h @@ -57,7 +57,7 @@ typedef struct PyMemberDef { /* Flags */ -enum PyMemberDefFlagEnum { +enum { PY_READWRITE = 0, PY_READONLY = 1, PY_READ_RESTRICTED = 2,