1 /* Implementation helper: a struct that looks like a tuple.
2 See timemodule and posixmodule for example uses.
3
4 The structseq helper is considered an internal CPython implementation
5 detail. Docs for modules using structseqs should call them
6 "named tuples" (be sure to include a space between the two
7 words and add a link back to the term in Docs/glossary.rst).
8 */
9
10 #include "Python.h"
11 #include "pycore_tupleobject.h"
12 #include "pycore_object.h"
13 #include "structmember.h" // PyMemberDef
14
15 static const char visible_length_key[] = "n_sequence_fields";
16 static const char real_length_key[] = "n_fields";
17 static const char unnamed_fields_key[] = "n_unnamed_fields";
18
19 /* Fields with this name have only a field index, not a field name.
20 They are only allowed for indices < n_visible_fields. */
21 const char * const PyStructSequence_UnnamedField = "unnamed field";
22 _Py_IDENTIFIER(n_sequence_fields);
23 _Py_IDENTIFIER(n_fields);
24 _Py_IDENTIFIER(n_unnamed_fields);
25
26 #define VISIBLE_SIZE(op) Py_SIZE(op)
27 #define VISIBLE_SIZE_TP(tp) PyLong_AsSsize_t( \
28 _PyDict_GetItemId((tp)->tp_dict, &PyId_n_sequence_fields))
29
30 #define REAL_SIZE_TP(tp) PyLong_AsSsize_t( \
31 _PyDict_GetItemId((tp)->tp_dict, &PyId_n_fields))
32 #define REAL_SIZE(op) REAL_SIZE_TP(Py_TYPE(op))
33
34 #define UNNAMED_FIELDS_TP(tp) PyLong_AsSsize_t( \
35 _PyDict_GetItemId((tp)->tp_dict, &PyId_n_unnamed_fields))
36 #define UNNAMED_FIELDS(op) UNNAMED_FIELDS_TP(Py_TYPE(op))
37
38
39 PyObject *
PyStructSequence_New(PyTypeObject * type)40 PyStructSequence_New(PyTypeObject *type)
41 {
42 PyStructSequence *obj;
43 Py_ssize_t size = REAL_SIZE_TP(type), i;
44
45 obj = PyObject_GC_NewVar(PyStructSequence, type, size);
46 if (obj == NULL)
47 return NULL;
48 /* Hack the size of the variable object, so invisible fields don't appear
49 to Python code. */
50 Py_SET_SIZE(obj, VISIBLE_SIZE_TP(type));
51 for (i = 0; i < size; i++)
52 obj->ob_item[i] = NULL;
53
54 return (PyObject*)obj;
55 }
56
57 void
PyStructSequence_SetItem(PyObject * op,Py_ssize_t i,PyObject * v)58 PyStructSequence_SetItem(PyObject* op, Py_ssize_t i, PyObject* v)
59 {
60 PyStructSequence_SET_ITEM(op, i, v);
61 }
62
63 PyObject*
PyStructSequence_GetItem(PyObject * op,Py_ssize_t i)64 PyStructSequence_GetItem(PyObject* op, Py_ssize_t i)
65 {
66 return PyStructSequence_GET_ITEM(op, i);
67 }
68
69
70 static int
structseq_traverse(PyStructSequence * obj,visitproc visit,void * arg)71 structseq_traverse(PyStructSequence *obj, visitproc visit, void *arg)
72 {
73 if (Py_TYPE(obj)->tp_flags & Py_TPFLAGS_HEAPTYPE) {
74 Py_VISIT(Py_TYPE(obj));
75 }
76 Py_ssize_t i, size;
77 size = REAL_SIZE(obj);
78 for (i = 0; i < size; ++i) {
79 Py_VISIT(obj->ob_item[i]);
80 }
81 return 0;
82 }
83
84 static void
structseq_dealloc(PyStructSequence * obj)85 structseq_dealloc(PyStructSequence *obj)
86 {
87 Py_ssize_t i, size;
88 PyTypeObject *tp;
89 PyObject_GC_UnTrack(obj);
90
91 tp = (PyTypeObject *) Py_TYPE(obj);
92 size = REAL_SIZE(obj);
93 for (i = 0; i < size; ++i) {
94 Py_XDECREF(obj->ob_item[i]);
95 }
96 PyObject_GC_Del(obj);
97 if (PyType_GetFlags(tp) & Py_TPFLAGS_HEAPTYPE) {
98 Py_DECREF(tp);
99 }
100 }
101
102 /*[clinic input]
103 class structseq "PyStructSequence *" "NULL"
104 [clinic start generated code]*/
105 /*[clinic end generated code: output=da39a3ee5e6b4b0d input=9d781c6922c77752]*/
106
107 #include "clinic/structseq.c.h"
108
109 /*[clinic input]
110 @classmethod
111 structseq.__new__ as structseq_new
112 sequence as arg: object
113 dict: object(c_default="NULL") = {}
114 [clinic start generated code]*/
115
116 static PyObject *
structseq_new_impl(PyTypeObject * type,PyObject * arg,PyObject * dict)117 structseq_new_impl(PyTypeObject *type, PyObject *arg, PyObject *dict)
118 /*[clinic end generated code: output=baa082e788b171da input=90532511101aa3fb]*/
119 {
120 PyObject *ob;
121 PyStructSequence *res = NULL;
122 Py_ssize_t len, min_len, max_len, i, n_unnamed_fields;
123
124 arg = PySequence_Fast(arg, "constructor requires a sequence");
125
126 if (!arg) {
127 return NULL;
128 }
129
130 if (dict && !PyDict_Check(dict)) {
131 PyErr_Format(PyExc_TypeError,
132 "%.500s() takes a dict as second arg, if any",
133 type->tp_name);
134 Py_DECREF(arg);
135 return NULL;
136 }
137
138 len = PySequence_Fast_GET_SIZE(arg);
139 min_len = VISIBLE_SIZE_TP(type);
140 max_len = REAL_SIZE_TP(type);
141 n_unnamed_fields = UNNAMED_FIELDS_TP(type);
142
143 if (min_len != max_len) {
144 if (len < min_len) {
145 PyErr_Format(PyExc_TypeError,
146 "%.500s() takes an at least %zd-sequence (%zd-sequence given)",
147 type->tp_name, min_len, len);
148 Py_DECREF(arg);
149 return NULL;
150 }
151
152 if (len > max_len) {
153 PyErr_Format(PyExc_TypeError,
154 "%.500s() takes an at most %zd-sequence (%zd-sequence given)",
155 type->tp_name, max_len, len);
156 Py_DECREF(arg);
157 return NULL;
158 }
159 }
160 else {
161 if (len != min_len) {
162 PyErr_Format(PyExc_TypeError,
163 "%.500s() takes a %zd-sequence (%zd-sequence given)",
164 type->tp_name, min_len, len);
165 Py_DECREF(arg);
166 return NULL;
167 }
168 }
169
170 res = (PyStructSequence*) PyStructSequence_New(type);
171 if (res == NULL) {
172 Py_DECREF(arg);
173 return NULL;
174 }
175 for (i = 0; i < len; ++i) {
176 PyObject *v = PySequence_Fast_GET_ITEM(arg, i);
177 Py_INCREF(v);
178 res->ob_item[i] = v;
179 }
180 for (; i < max_len; ++i) {
181 if (dict && (ob = PyDict_GetItemString(
182 dict, type->tp_members[i-n_unnamed_fields].name))) {
183 }
184 else {
185 ob = Py_None;
186 }
187 Py_INCREF(ob);
188 res->ob_item[i] = ob;
189 }
190
191 Py_DECREF(arg);
192 _PyObject_GC_TRACK(res);
193 return (PyObject*) res;
194 }
195
196
197 static PyObject *
structseq_repr(PyStructSequence * obj)198 structseq_repr(PyStructSequence *obj)
199 {
200 PyTypeObject *typ = Py_TYPE(obj);
201 _PyUnicodeWriter writer;
202
203 /* Write "typename(" */
204 PyObject *type_name = PyUnicode_DecodeUTF8(typ->tp_name,
205 strlen(typ->tp_name),
206 NULL);
207 if (type_name == NULL) {
208 return NULL;
209 }
210
211 _PyUnicodeWriter_Init(&writer);
212 writer.overallocate = 1;
213 /* count 5 characters per item: "x=1, " */
214 writer.min_length = (PyUnicode_GET_LENGTH(type_name) + 1
215 + VISIBLE_SIZE(obj) * 5 + 1);
216
217 if (_PyUnicodeWriter_WriteStr(&writer, type_name) < 0) {
218 Py_DECREF(type_name);
219 goto error;
220 }
221 Py_DECREF(type_name);
222
223 if (_PyUnicodeWriter_WriteChar(&writer, '(') < 0) {
224 goto error;
225 }
226
227 for (Py_ssize_t i=0; i < VISIBLE_SIZE(obj); i++) {
228 if (i > 0) {
229 /* Write ", " */
230 if (_PyUnicodeWriter_WriteASCIIString(&writer, ", ", 2) < 0) {
231 goto error;
232 }
233 }
234
235 /* Write "name=repr" */
236 const char *name_utf8 = typ->tp_members[i].name;
237 if (name_utf8 == NULL) {
238 PyErr_Format(PyExc_SystemError, "In structseq_repr(), member %zd name is NULL"
239 " for type %.500s", i, typ->tp_name);
240 goto error;
241 }
242
243 PyObject *name = PyUnicode_DecodeUTF8(name_utf8, strlen(name_utf8), NULL);
244 if (name == NULL) {
245 goto error;
246 }
247 if (_PyUnicodeWriter_WriteStr(&writer, name) < 0) {
248 Py_DECREF(name);
249 goto error;
250 }
251 Py_DECREF(name);
252
253 if (_PyUnicodeWriter_WriteChar(&writer, '=') < 0) {
254 goto error;
255 }
256
257 PyObject *value = PyStructSequence_GET_ITEM(obj, i);
258 assert(value != NULL);
259 PyObject *repr = PyObject_Repr(value);
260 if (repr == NULL) {
261 goto error;
262 }
263 if (_PyUnicodeWriter_WriteStr(&writer, repr) < 0) {
264 Py_DECREF(repr);
265 goto error;
266 }
267 Py_DECREF(repr);
268 }
269
270 if (_PyUnicodeWriter_WriteChar(&writer, ')') < 0) {
271 goto error;
272 }
273
274 return _PyUnicodeWriter_Finish(&writer);
275
276 error:
277 _PyUnicodeWriter_Dealloc(&writer);
278 return NULL;
279 }
280
281
282 static PyObject *
structseq_reduce(PyStructSequence * self,PyObject * Py_UNUSED (ignored))283 structseq_reduce(PyStructSequence* self, PyObject *Py_UNUSED(ignored))
284 {
285 PyObject* tup = NULL;
286 PyObject* dict = NULL;
287 PyObject* result;
288 Py_ssize_t n_fields, n_visible_fields, n_unnamed_fields, i;
289
290 n_fields = REAL_SIZE(self);
291 n_visible_fields = VISIBLE_SIZE(self);
292 n_unnamed_fields = UNNAMED_FIELDS(self);
293 tup = _PyTuple_FromArray(self->ob_item, n_visible_fields);
294 if (!tup)
295 goto error;
296
297 dict = PyDict_New();
298 if (!dict)
299 goto error;
300
301 for (i = n_visible_fields; i < n_fields; i++) {
302 const char *n = Py_TYPE(self)->tp_members[i-n_unnamed_fields].name;
303 if (PyDict_SetItemString(dict, n, self->ob_item[i]) < 0)
304 goto error;
305 }
306
307 result = Py_BuildValue("(O(OO))", Py_TYPE(self), tup, dict);
308
309 Py_DECREF(tup);
310 Py_DECREF(dict);
311
312 return result;
313
314 error:
315 Py_XDECREF(tup);
316 Py_XDECREF(dict);
317 return NULL;
318 }
319
320 static PyMethodDef structseq_methods[] = {
321 {"__reduce__", (PyCFunction)structseq_reduce, METH_NOARGS, NULL},
322 {NULL, NULL}
323 };
324
325 static Py_ssize_t
count_members(PyStructSequence_Desc * desc,Py_ssize_t * n_unnamed_members)326 count_members(PyStructSequence_Desc *desc, Py_ssize_t *n_unnamed_members) {
327 Py_ssize_t i;
328
329 *n_unnamed_members = 0;
330 for (i = 0; desc->fields[i].name != NULL; ++i) {
331 if (desc->fields[i].name == PyStructSequence_UnnamedField) {
332 (*n_unnamed_members)++;
333 }
334 }
335 return i;
336 }
337
338 static int
initialize_structseq_dict(PyStructSequence_Desc * desc,PyObject * dict,Py_ssize_t n_members,Py_ssize_t n_unnamed_members)339 initialize_structseq_dict(PyStructSequence_Desc *desc, PyObject* dict,
340 Py_ssize_t n_members, Py_ssize_t n_unnamed_members) {
341 PyObject *v;
342
343 #define SET_DICT_FROM_SIZE(key, value) \
344 do { \
345 v = PyLong_FromSsize_t(value); \
346 if (v == NULL) { \
347 return -1; \
348 } \
349 if (PyDict_SetItemString(dict, key, v) < 0) { \
350 Py_DECREF(v); \
351 return -1; \
352 } \
353 Py_DECREF(v); \
354 } while (0)
355
356 SET_DICT_FROM_SIZE(visible_length_key, desc->n_in_sequence);
357 SET_DICT_FROM_SIZE(real_length_key, n_members);
358 SET_DICT_FROM_SIZE(unnamed_fields_key, n_unnamed_members);
359 return 0;
360 }
361
362 static void
initialize_members(PyStructSequence_Desc * desc,PyMemberDef * members,Py_ssize_t n_members)363 initialize_members(PyStructSequence_Desc *desc, PyMemberDef* members,
364 Py_ssize_t n_members) {
365 Py_ssize_t i, k;
366
367 for (i = k = 0; i < n_members; ++i) {
368 if (desc->fields[i].name == PyStructSequence_UnnamedField) {
369 continue;
370 }
371
372 /* The names and docstrings in these MemberDefs are statically */
373 /* allocated so it is expected that they'll outlive the MemberDef */
374 members[k].name = desc->fields[i].name;
375 members[k].type = T_OBJECT;
376 members[k].offset = offsetof(PyStructSequence, ob_item)
377 + i * sizeof(PyObject*);
378 members[k].flags = READONLY;
379 members[k].doc = desc->fields[i].doc;
380 k++;
381 }
382 members[k].name = NULL;
383 }
384
385 int
PyStructSequence_InitType2(PyTypeObject * type,PyStructSequence_Desc * desc)386 PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
387 {
388 PyMemberDef *members;
389 Py_ssize_t n_members, n_unnamed_members;
390
391 #ifdef Py_TRACE_REFS
392 /* if the type object was chained, unchain it first
393 before overwriting its storage */
394 if (type->ob_base.ob_base._ob_next) {
395 _Py_ForgetReference((PyObject *)type);
396 }
397 #endif
398
399 /* PyTypeObject has already been initialized */
400 if (Py_REFCNT(type) != 0) {
401 PyErr_BadInternalCall();
402 return -1;
403 }
404
405 type->tp_name = desc->name;
406 type->tp_basicsize = sizeof(PyStructSequence) - sizeof(PyObject *);
407 type->tp_itemsize = sizeof(PyObject *);
408 type->tp_dealloc = (destructor)structseq_dealloc;
409 type->tp_repr = (reprfunc)structseq_repr;
410 type->tp_doc = desc->doc;
411 type->tp_base = &PyTuple_Type;
412 type->tp_methods = structseq_methods;
413 type->tp_new = structseq_new;
414 type->tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC;
415 type->tp_traverse = (traverseproc) structseq_traverse;
416
417 n_members = count_members(desc, &n_unnamed_members);
418 members = PyMem_NEW(PyMemberDef, n_members - n_unnamed_members + 1);
419 if (members == NULL) {
420 PyErr_NoMemory();
421 return -1;
422 }
423 initialize_members(desc, members, n_members);
424 type->tp_members = members;
425
426 if (PyType_Ready(type) < 0) {
427 PyMem_FREE(members);
428 return -1;
429 }
430 Py_INCREF(type);
431
432 if (initialize_structseq_dict(
433 desc, type->tp_dict, n_members, n_unnamed_members) < 0) {
434 PyMem_FREE(members);
435 Py_DECREF(type);
436 return -1;
437 }
438
439 return 0;
440 }
441
442 void
PyStructSequence_InitType(PyTypeObject * type,PyStructSequence_Desc * desc)443 PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
444 {
445 (void)PyStructSequence_InitType2(type, desc);
446 }
447
448 PyTypeObject *
PyStructSequence_NewType(PyStructSequence_Desc * desc)449 PyStructSequence_NewType(PyStructSequence_Desc *desc)
450 {
451 PyMemberDef *members;
452 PyObject *bases;
453 PyTypeObject *type;
454 PyType_Slot slots[8];
455 PyType_Spec spec;
456 Py_ssize_t n_members, n_unnamed_members;
457
458 /* Initialize MemberDefs */
459 n_members = count_members(desc, &n_unnamed_members);
460 members = PyMem_NEW(PyMemberDef, n_members - n_unnamed_members + 1);
461 if (members == NULL) {
462 PyErr_NoMemory();
463 return NULL;
464 }
465 initialize_members(desc, members, n_members);
466
467 /* Initialize Slots */
468 slots[0] = (PyType_Slot){Py_tp_dealloc, (destructor)structseq_dealloc};
469 slots[1] = (PyType_Slot){Py_tp_repr, (reprfunc)structseq_repr};
470 slots[2] = (PyType_Slot){Py_tp_doc, (void *)desc->doc};
471 slots[3] = (PyType_Slot){Py_tp_methods, structseq_methods};
472 slots[4] = (PyType_Slot){Py_tp_new, structseq_new};
473 slots[5] = (PyType_Slot){Py_tp_members, members};
474 slots[6] = (PyType_Slot){Py_tp_traverse, (traverseproc)structseq_traverse};
475 slots[7] = (PyType_Slot){0, 0};
476
477 /* Initialize Spec */
478 /* The name in this PyType_Spec is statically allocated so it is */
479 /* expected that it'll outlive the PyType_Spec */
480 spec.name = desc->name;
481 spec.basicsize = sizeof(PyStructSequence) - sizeof(PyObject *);
482 spec.itemsize = sizeof(PyObject *);
483 spec.flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC;
484 spec.slots = slots;
485
486 bases = PyTuple_Pack(1, &PyTuple_Type);
487 if (bases == NULL) {
488 PyMem_FREE(members);
489 return NULL;
490 }
491 type = (PyTypeObject *)PyType_FromSpecWithBases(&spec, bases);
492 Py_DECREF(bases);
493 PyMem_FREE(members);
494 if (type == NULL) {
495 return NULL;
496 }
497
498 if (initialize_structseq_dict(
499 desc, type->tp_dict, n_members, n_unnamed_members) < 0) {
500 Py_DECREF(type);
501 return NULL;
502 }
503
504 return type;
505 }
506
_PyStructSequence_Init(void)507 int _PyStructSequence_Init(void)
508 {
509 if (_PyUnicode_FromId(&PyId_n_sequence_fields) == NULL
510 || _PyUnicode_FromId(&PyId_n_fields) == NULL
511 || _PyUnicode_FromId(&PyId_n_unnamed_fields) == NULL)
512 return -1;
513
514 return 0;
515 }
516