source: python/vendor/Python-2.6.5/Include/abstract.h

Last change on this file was 2, checked in by Yuri Dario, 15 years ago

Initial import for vendor code.
  • Property svn:eol-style set to native
File size: 42.0 KB
Line 
1#ifndef Py_ABSTRACTOBJECT_H
2#define Py_ABSTRACTOBJECT_H
3#ifdef __cplusplus
4extern "C" {
5#endif
6
7#ifdef PY_SSIZE_T_CLEAN
8#define PyObject_CallFunction _PyObject_CallFunction_SizeT
9#define PyObject_CallMethod _PyObject_CallMethod_SizeT
10#endif
11
12/* Abstract Object Interface (many thanks to Jim Fulton) */
13
14/*
15 PROPOSAL: A Generic Python Object Interface for Python C Modules
16
17Problem
18
19 Python modules written in C that must access Python objects must do
20 so through routines whose interfaces are described by a set of
21 include files. Unfortunately, these routines vary according to the
22 object accessed. To use these routines, the C programmer must check
23 the type of the object being used and must call a routine based on
24 the object type. For example, to access an element of a sequence,
25 the programmer must determine whether the sequence is a list or a
26 tuple:
27
28 if(is_tupleobject(o))
29 e=gettupleitem(o,i)
30 else if(is_listitem(o))
31 e=getlistitem(o,i)
32
33 If the programmer wants to get an item from another type of object
34 that provides sequence behavior, there is no clear way to do it
35 correctly.
36
37 The persistent programmer may peruse object.h and find that the
38 _typeobject structure provides a means of invoking up to (currently
39 about) 41 special operators. So, for example, a routine can get an
40 item from any object that provides sequence behavior. However, to
41 use this mechanism, the programmer must make their code dependent on
42 the current Python implementation.
43
44 Also, certain semantics, especially memory management semantics, may
45 differ by the type of object being used. Unfortunately, these
46 semantics are not clearly described in the current include files.
47 An abstract interface providing more consistent semantics is needed.
48
49Proposal
50
51 I propose the creation of a standard interface (with an associated
52 library of routines and/or macros) for generically obtaining the
53 services of Python objects. This proposal can be viewed as one
54 components of a Python C interface consisting of several components.
55
56 From the viewpoint of C access to Python services, we have (as
57 suggested by Guido in off-line discussions):
58
59 - "Very high level layer": two or three functions that let you exec or
60 eval arbitrary Python code given as a string in a module whose name is
61 given, passing C values in and getting C values out using
62 mkvalue/getargs style format strings. This does not require the user
63 to declare any variables of type "PyObject *". This should be enough
64 to write a simple application that gets Python code from the user,
65 execs it, and returns the output or errors. (Error handling must also
66 be part of this API.)
67
68 - "Abstract objects layer": which is the subject of this proposal.
69 It has many functions operating on objects, and lest you do many
70 things from C that you can also write in Python, without going
71 through the Python parser.
72
73 - "Concrete objects layer": This is the public type-dependent
74 interface provided by the standard built-in types, such as floats,
75 strings, and lists. This interface exists and is currently
76 documented by the collection of include files provided with the
77 Python distributions.
78
79 From the point of view of Python accessing services provided by C
80 modules:
81
82 - "Python module interface": this interface consist of the basic
83 routines used to define modules and their members. Most of the
84 current extensions-writing guide deals with this interface.
85
86 - "Built-in object interface": this is the interface that a new
87 built-in type must provide and the mechanisms and rules that a
88 developer of a new built-in type must use and follow.
89
90 This proposal is a "first-cut" that is intended to spur
91 discussion. See especially the lists of notes.
92
93 The Python C object interface will provide four protocols: object,
94 numeric, sequence, and mapping. Each protocol consists of a
95 collection of related operations. If an operation that is not
96 provided by a particular type is invoked, then a standard exception,
97 NotImplementedError is raised with a operation name as an argument.
98 In addition, for convenience this interface defines a set of
99 constructors for building objects of built-in types. This is needed
100 so new objects can be returned from C functions that otherwise treat
101 objects generically.
102
103Memory Management
104
105 For all of the functions described in this proposal, if a function
106 retains a reference to a Python object passed as an argument, then the
107 function will increase the reference count of the object. It is
108 unnecessary for the caller to increase the reference count of an
109 argument in anticipation of the object's retention.
110
111 All Python objects returned from functions should be treated as new
112 objects. Functions that return objects assume that the caller will
113 retain a reference and the reference count of the object has already
114 been incremented to account for this fact. A caller that does not
115 retain a reference to an object that is returned from a function
116 must decrement the reference count of the object (using
117 DECREF(object)) to prevent memory leaks.
118
119 Note that the behavior mentioned here is different from the current
120 behavior for some objects (e.g. lists and tuples) when certain
121 type-specific routines are called directly (e.g. setlistitem). The
122 proposed abstraction layer will provide a consistent memory
123 management interface, correcting for inconsistent behavior for some
124 built-in types.
125
126Protocols
127
128xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
129
130/* Object Protocol: */
131
132 /* Implemented elsewhere:
133
134 int PyObject_Print(PyObject *o, FILE *fp, int flags);
135
136 Print an object, o, on file, fp. Returns -1 on
137 error. The flags argument is used to enable certain printing
138 options. The only option currently supported is Py_Print_RAW.
139
140 (What should be said about Py_Print_RAW?)
141
142 */
143
144 /* Implemented elsewhere:
145
146 int PyObject_HasAttrString(PyObject *o, char *attr_name);
147
148 Returns 1 if o has the attribute attr_name, and 0 otherwise.
149 This is equivalent to the Python expression:
150 hasattr(o,attr_name).
151
152 This function always succeeds.
153
154 */
155
156 /* Implemented elsewhere:
157
158 PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name);
159
160 Retrieve an attributed named attr_name form object o.
161 Returns the attribute value on success, or NULL on failure.
162 This is the equivalent of the Python expression: o.attr_name.
163
164 */
165
166 /* Implemented elsewhere:
167
168 int PyObject_HasAttr(PyObject *o, PyObject *attr_name);
169
170 Returns 1 if o has the attribute attr_name, and 0 otherwise.
171 This is equivalent to the Python expression:
172 hasattr(o,attr_name).
173
174 This function always succeeds.
175
176 */
177
178 /* Implemented elsewhere:
179
180 PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);
181
182 Retrieve an attributed named attr_name form object o.
183 Returns the attribute value on success, or NULL on failure.
184 This is the equivalent of the Python expression: o.attr_name.
185
186 */
187
188
189 /* Implemented elsewhere:
190
191 int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v);
192
193 Set the value of the attribute named attr_name, for object o,
194 to the value, v. Returns -1 on failure. This is
195 the equivalent of the Python statement: o.attr_name=v.
196
197 */
198
199 /* Implemented elsewhere:
200
201 int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
202
203 Set the value of the attribute named attr_name, for object o,
204 to the value, v. Returns -1 on failure. This is
205 the equivalent of the Python statement: o.attr_name=v.
206
207 */
208
209 /* implemented as a macro:
210
211 int PyObject_DelAttrString(PyObject *o, char *attr_name);
212
213 Delete attribute named attr_name, for object o. Returns
214 -1 on failure. This is the equivalent of the Python
215 statement: del o.attr_name.
216
217 */
218#define PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A),NULL)
219
220 /* implemented as a macro:
221
222 int PyObject_DelAttr(PyObject *o, PyObject *attr_name);
223
224 Delete attribute named attr_name, for object o. Returns -1
225 on failure. This is the equivalent of the Python
226 statement: del o.attr_name.
227
228 */
229#define PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A),NULL)
230
231 PyAPI_FUNC(int) PyObject_Cmp(PyObject *o1, PyObject *o2, int *result);
232
233 /*
234 Compare the values of o1 and o2 using a routine provided by
235 o1, if one exists, otherwise with a routine provided by o2.
236 The result of the comparison is returned in result. Returns
237 -1 on failure. This is the equivalent of the Python
238 statement: result=cmp(o1,o2).
239
240 */
241
242 /* Implemented elsewhere:
243
244 int PyObject_Compare(PyObject *o1, PyObject *o2);
245
246 Compare the values of o1 and o2 using a routine provided by
247 o1, if one exists, otherwise with a routine provided by o2.
248 Returns the result of the comparison on success. On error,
249 the value returned is undefined. This is equivalent to the
250 Python expression: cmp(o1,o2).
251
252 */
253
254 /* Implemented elsewhere:
255
256 PyObject *PyObject_Repr(PyObject *o);
257
258 Compute the string representation of object, o. Returns the
259 string representation on success, NULL on failure. This is
260 the equivalent of the Python expression: repr(o).
261
262 Called by the repr() built-in function and by reverse quotes.
263
264 */
265
266 /* Implemented elsewhere:
267
268 PyObject *PyObject_Str(PyObject *o);
269
270 Compute the string representation of object, o. Returns the
271 string representation on success, NULL on failure. This is
272 the equivalent of the Python expression: str(o).)
273
274 Called by the str() built-in function and by the print
275 statement.
276
277 */
278
279 /* Implemented elsewhere:
280
281 PyObject *PyObject_Unicode(PyObject *o);
282
283 Compute the unicode representation of object, o. Returns the
284 unicode representation on success, NULL on failure. This is
285 the equivalent of the Python expression: unistr(o).)
286
287 Called by the unistr() built-in function.
288
289 */
290
291 /* Declared elsewhere
292
293 PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
294
295 Determine if the object, o, is callable. Return 1 if the
296 object is callable and 0 otherwise.
297
298 This function always succeeds.
299
300 */
301
302
303
304 PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
305 PyObject *args, PyObject *kw);
306
307 /*
308 Call a callable Python object, callable_object, with
309 arguments and keywords arguments. The 'args' argument can not be
310 NULL, but the 'kw' argument can be NULL.
311
312 */
313
314 PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
315 PyObject *args);
316
317 /*
318 Call a callable Python object, callable_object, with
319 arguments given by the tuple, args. If no arguments are
320 needed, then args may be NULL. Returns the result of the
321 call on success, or NULL on failure. This is the equivalent
322 of the Python expression: apply(o,args).
323
324 */
325
326 PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
327 char *format, ...);
328
329 /*
330 Call a callable Python object, callable_object, with a
331 variable number of C arguments. The C arguments are described
332 using a mkvalue-style format string. The format may be NULL,
333 indicating that no arguments are provided. Returns the
334 result of the call on success, or NULL on failure. This is
335 the equivalent of the Python expression: apply(o,args).
336
337 */
338
339
340 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o, char *m,
341 char *format, ...);
342
343 /*
344 Call the method named m of object o with a variable number of
345 C arguments. The C arguments are described by a mkvalue
346 format string. The format may be NULL, indicating that no
347 arguments are provided. Returns the result of the call on
348 success, or NULL on failure. This is the equivalent of the
349 Python expression: o.method(args).
350 */
351
352 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
353 char *format, ...);
354 PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
355 char *name,
356 char *format, ...);
357
358 PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
359 ...);
360
361 /*
362 Call a callable Python object, callable_object, with a
363 variable number of C arguments. The C arguments are provided
364 as PyObject * values, terminated by a NULL. Returns the
365 result of the call on success, or NULL on failure. This is
366 the equivalent of the Python expression: apply(o,args).
367 */
368
369
370 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
371 PyObject *m, ...);
372
373 /*
374 Call the method named m of object o with a variable number of
375 C arguments. The C arguments are provided as PyObject *
376 values, terminated by NULL. Returns the result of the call
377 on success, or NULL on failure. This is the equivalent of
378 the Python expression: o.method(args).
379 */
380
381
382 /* Implemented elsewhere:
383
384 long PyObject_Hash(PyObject *o);
385
386 Compute and return the hash, hash_value, of an object, o. On
387 failure, return -1. This is the equivalent of the Python
388 expression: hash(o).
389
390 */
391
392
393 /* Implemented elsewhere:
394
395 int PyObject_IsTrue(PyObject *o);
396
397 Returns 1 if the object, o, is considered to be true, 0 if o is
398 considered to be false and -1 on failure. This is equivalent to the
399 Python expression: not not o
400
401 */
402
403 /* Implemented elsewhere:
404
405 int PyObject_Not(PyObject *o);
406
407 Returns 0 if the object, o, is considered to be true, 1 if o is
408 considered to be false and -1 on failure. This is equivalent to the
409 Python expression: not o
410
411 */
412
413 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
414
415 /*
416 On success, returns a type object corresponding to the object
417 type of object o. On failure, returns NULL. This is
418 equivalent to the Python expression: type(o).
419 */
420
421 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
422
423 /*
424 Return the size of object o. If the object, o, provides
425 both sequence and mapping protocols, the sequence size is
426 returned. On error, -1 is returned. This is the equivalent
427 to the Python expression: len(o).
428
429 */
430
431 /* For DLL compatibility */
432#undef PyObject_Length
433 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
434#define PyObject_Length PyObject_Size
435
436 PyAPI_FUNC(Py_ssize_t) _PyObject_LengthHint(PyObject *o, Py_ssize_t);
437
438 /*
439 Guess the size of object o using len(o) or o.__length_hint__().
440 If neither of those return a non-negative value, then return the
441 default value. If one of the calls fails, this function returns -1.
442 */
443
444 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
445
446 /*
447 Return element of o corresponding to the object, key, or NULL
448 on failure. This is the equivalent of the Python expression:
449 o[key].
450
451 */
452
453 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
454
455 /*
456 Map the object, key, to the value, v. Returns
457 -1 on failure. This is the equivalent of the Python
458 statement: o[key]=v.
459 */
460
461 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key);
462
463 /*
464 Remove the mapping for object, key, from the object *o.
465 Returns -1 on failure. This is equivalent to
466 the Python statement: del o[key].
467 */
468
469 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
470
471 /*
472 Delete the mapping for key from *o. Returns -1 on failure.
473 This is the equivalent of the Python statement: del o[key].
474 */
475
476 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
477 const char **buffer,
478 Py_ssize_t *buffer_len);
479
480 /*
481 Takes an arbitrary object which must support the (character,
482 single segment) buffer interface and returns a pointer to a
483 read-only memory location useable as character based input
484 for subsequent processing.
485
486 0 is returned on success. buffer and buffer_len are only
487 set in case no error occurs. Otherwise, -1 is returned and
488 an exception set.
489
490 */
491
492 PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
493
494 /*
495 Checks whether an arbitrary object supports the (character,
496 single segment) buffer interface. Returns 1 on success, 0
497 on failure.
498
499 */
500
501 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
502 const void **buffer,
503 Py_ssize_t *buffer_len);
504
505 /*
506 Same as PyObject_AsCharBuffer() except that this API expects
507 (readable, single segment) buffer interface and returns a
508 pointer to a read-only memory location which can contain
509 arbitrary data.
510
511 0 is returned on success. buffer and buffer_len are only
512 set in case no error occurrs. Otherwise, -1 is returned and
513 an exception set.
514
515 */
516
517 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
518 void **buffer,
519 Py_ssize_t *buffer_len);
520
521 /*
522 Takes an arbitrary object which must support the (writeable,
523 single segment) buffer interface and returns a pointer to a
524 writeable memory location in buffer of size buffer_len.
525
526 0 is returned on success. buffer and buffer_len are only
527 set in case no error occurrs. Otherwise, -1 is returned and
528 an exception set.
529
530 */
531
532 /* new buffer API */
533
534#define PyObject_CheckBuffer(obj) \
535 (((obj)->ob_type->tp_as_buffer != NULL) && \
536 (PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_NEWBUFFER)) && \
537 ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))
538
539 /* Return 1 if the getbuffer function is available, otherwise
540 return 0 */
541
542 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
543 int flags);
544
545 /* This is a C-API version of the getbuffer function call. It checks
546 to make sure object has the required function pointer and issues the
547 call. Returns -1 and raises an error on failure and returns 0 on
548 success
549 */
550
551
552 PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
553
554 /* Get the memory area pointed to by the indices for the buffer given.
555 Note that view->ndim is the assumed size of indices
556 */
557
558 PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);
559
560 /* Return the implied itemsize of the data-format area from a
561 struct-style description */
562
563
564
565 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
566 Py_ssize_t len, char fort);
567
568 PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
569 Py_ssize_t len, char fort);
570
571
572 /* Copy len bytes of data from the contiguous chunk of memory
573 pointed to by buf into the buffer exported by obj. Return
574 0 on success and return -1 and raise a PyBuffer_Error on
575 error (i.e. the object does not have a buffer interface or
576 it is not working).
577
578 If fort is 'F' and the object is multi-dimensional,
579 then the data will be copied into the array in
580 Fortran-style (first dimension varies the fastest). If
581 fort is 'C', then the data will be copied into the array
582 in C-style (last dimension varies the fastest). If fort
583 is 'A', then it does not matter and the copy will be made
584 in whatever way is more efficient.
585
586 */
587
588 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
589
590 /* Copy the data from the src buffer to the buffer of destination
591 */
592
593 PyAPI_FUNC(int) PyBuffer_IsContiguous(Py_buffer *view, char fort);
594
595
596 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
597 Py_ssize_t *shape,
598 Py_ssize_t *strides,
599 int itemsize,
600 char fort);
601
602 /* Fill the strides array with byte-strides of a contiguous
603 (Fortran-style if fort is 'F' or C-style otherwise)
604 array of the given shape with the given number of bytes
605 per element.
606 */
607
608 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
609 Py_ssize_t len, int readonly,
610 int flags);
611
612 /* Fills in a buffer-info structure correctly for an exporter
613 that can only share a contiguous chunk of memory of
614 "unsigned bytes" of the given length. Returns 0 on success
615 and -1 (with raising an error) on error.
616 */
617
618 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
619
620 /* Releases a Py_buffer obtained from getbuffer ParseTuple's s*.
621 */
622
623 PyAPI_FUNC(PyObject *) PyObject_Format(PyObject* obj,
624 PyObject *format_spec);
625 /*
626 Takes an arbitrary object and returns the result of
627 calling obj.__format__(format_spec).
628 */
629
630/* Iterators */
631
632 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
633 /* Takes an object and returns an iterator for it.
634 This is typically a new iterator but if the argument
635 is an iterator, this returns itself. */
636
637#define PyIter_Check(obj) \
638 (PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_ITER) && \
639 (obj)->ob_type->tp_iternext != NULL)
640
641 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
642 /* Takes an iterator object and calls its tp_iternext slot,
643 returning the next value. If the iterator is exhausted,
644 this returns NULL without setting an exception.
645 NULL with an exception means an error occurred. */
646
647/* Number Protocol:*/
648
649 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
650
651 /*
652 Returns 1 if the object, o, provides numeric protocols, and
653 false otherwise.
654
655 This function always succeeds.
656
657 */
658
659 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
660
661 /*
662 Returns the result of adding o1 and o2, or null on failure.
663 This is the equivalent of the Python expression: o1+o2.
664
665
666 */
667
668 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
669
670 /*
671 Returns the result of subtracting o2 from o1, or null on
672 failure. This is the equivalent of the Python expression:
673 o1-o2.
674
675 */
676
677 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
678
679 /*
680 Returns the result of multiplying o1 and o2, or null on
681 failure. This is the equivalent of the Python expression:
682 o1*o2.
683
684
685 */
686
687 PyAPI_FUNC(PyObject *) PyNumber_Divide(PyObject *o1, PyObject *o2);
688
689 /*
690 Returns the result of dividing o1 by o2, or null on failure.
691 This is the equivalent of the Python expression: o1/o2.
692
693
694 */
695
696 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
697
698 /*
699 Returns the result of dividing o1 by o2 giving an integral result,
700 or null on failure.
701 This is the equivalent of the Python expression: o1//o2.
702
703
704 */
705
706 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
707
708 /*
709 Returns the result of dividing o1 by o2 giving a float result,
710 or null on failure.
711 This is the equivalent of the Python expression: o1/o2.
712
713
714 */
715
716 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
717
718 /*
719 Returns the remainder of dividing o1 by o2, or null on
720 failure. This is the equivalent of the Python expression:
721 o1%o2.
722
723
724 */
725
726 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
727
728 /*
729 See the built-in function divmod. Returns NULL on failure.
730 This is the equivalent of the Python expression:
731 divmod(o1,o2).
732
733
734 */
735
736 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
737 PyObject *o3);
738
739 /*
740 See the built-in function pow. Returns NULL on failure.
741 This is the equivalent of the Python expression:
742 pow(o1,o2,o3), where o3 is optional.
743
744 */
745
746 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
747
748 /*
749 Returns the negation of o on success, or null on failure.
750 This is the equivalent of the Python expression: -o.
751
752 */
753
754 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
755
756 /*
757 Returns the (what?) of o on success, or NULL on failure.
758 This is the equivalent of the Python expression: +o.
759
760 */
761
762 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
763
764 /*
765 Returns the absolute value of o, or null on failure. This is
766 the equivalent of the Python expression: abs(o).
767
768 */
769
770 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
771
772 /*
773 Returns the bitwise negation of o on success, or NULL on
774 failure. This is the equivalent of the Python expression:
775 ~o.
776
777
778 */
779
780 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
781
782 /*
783 Returns the result of left shifting o1 by o2 on success, or
784 NULL on failure. This is the equivalent of the Python
785 expression: o1 << o2.
786
787
788 */
789
790 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
791
792 /*
793 Returns the result of right shifting o1 by o2 on success, or
794 NULL on failure. This is the equivalent of the Python
795 expression: o1 >> o2.
796
797 */
798
799 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
800
801 /*
802 Returns the result of bitwise and of o1 and o2 on success, or
803 NULL on failure. This is the equivalent of the Python
804 expression: o1&o2.
805
806
807 */
808
809 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
810
811 /*
812 Returns the bitwise exclusive or of o1 by o2 on success, or
813 NULL on failure. This is the equivalent of the Python
814 expression: o1^o2.
815
816
817 */
818
819 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
820
821 /*
822 Returns the result of bitwise or on o1 and o2 on success, or
823 NULL on failure. This is the equivalent of the Python
824 expression: o1|o2.
825
826 */
827
828 /* Implemented elsewhere:
829
830 int PyNumber_Coerce(PyObject **p1, PyObject **p2);
831
832 This function takes the addresses of two variables of type
833 PyObject*.
834
835 If the objects pointed to by *p1 and *p2 have the same type,
836 increment their reference count and return 0 (success).
837 If the objects can be converted to a common numeric type,
838 replace *p1 and *p2 by their converted value (with 'new'
839 reference counts), and return 0.
840 If no conversion is possible, or if some other error occurs,
841 return -1 (failure) and don't increment the reference counts.
842 The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python
843 statement o1, o2 = coerce(o1, o2).
844
845 */
846
847#define PyIndex_Check(obj) \
848 ((obj)->ob_type->tp_as_number != NULL && \
849 PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_INDEX) && \
850 (obj)->ob_type->tp_as_number->nb_index != NULL)
851
852 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
853
854 /*
855 Returns the object converted to a Python long or int
856 or NULL with an error raised on failure.
857 */
858
859 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
860
861 /*
862 Returns the Integral instance converted to an int. The
863 instance is expected to be int or long or have an __int__
864 method. Steals integral's reference. error_format will be
865 used to create the TypeError if integral isn't actually an
866 Integral instance. error_format should be a format string
867 that can accept a char* naming integral's type.
868 */
869
870 PyAPI_FUNC(PyObject *) _PyNumber_ConvertIntegralToInt(
871 PyObject *integral,
872 const char* error_format);
873
874 /*
875 Returns the object converted to Py_ssize_t by going through
876 PyNumber_Index first. If an overflow error occurs while
877 converting the int-or-long to Py_ssize_t, then the second argument
878 is the error-type to return. If it is NULL, then the overflow error
879 is cleared and the value is clipped.
880 */
881
882 PyAPI_FUNC(PyObject *) PyNumber_Int(PyObject *o);
883
884 /*
885 Returns the o converted to an integer object on success, or
886 NULL on failure. This is the equivalent of the Python
887 expression: int(o).
888
889 */
890
891 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
892
893 /*
894 Returns the o converted to a long integer object on success,
895 or NULL on failure. This is the equivalent of the Python
896 expression: long(o).
897
898 */
899
900 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
901
902 /*
903 Returns the o converted to a float object on success, or NULL
904 on failure. This is the equivalent of the Python expression:
905 float(o).
906 */
907
908/* In-place variants of (some of) the above number protocol functions */
909
910 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
911
912 /*
913 Returns the result of adding o2 to o1, possibly in-place, or null
914 on failure. This is the equivalent of the Python expression:
915 o1 += o2.
916
917 */
918
919 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
920
921 /*
922 Returns the result of subtracting o2 from o1, possibly in-place or
923 null on failure. This is the equivalent of the Python expression:
924 o1 -= o2.
925
926 */
927
928 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
929
930 /*
931 Returns the result of multiplying o1 by o2, possibly in-place, or
932 null on failure. This is the equivalent of the Python expression:
933 o1 *= o2.
934
935 */
936
937 PyAPI_FUNC(PyObject *) PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2);
938
939 /*
940 Returns the result of dividing o1 by o2, possibly in-place, or null
941 on failure. This is the equivalent of the Python expression:
942 o1 /= o2.
943
944 */
945
946 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
947 PyObject *o2);
948
949 /*
950 Returns the result of dividing o1 by o2 giving an integral result,
951 possibly in-place, or null on failure.
952 This is the equivalent of the Python expression:
953 o1 /= o2.
954
955 */
956
957 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
958 PyObject *o2);
959
960 /*
961 Returns the result of dividing o1 by o2 giving a float result,
962 possibly in-place, or null on failure.
963 This is the equivalent of the Python expression:
964 o1 /= o2.
965
966 */
967
968 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
969
970 /*
971 Returns the remainder of dividing o1 by o2, possibly in-place, or
972 null on failure. This is the equivalent of the Python expression:
973 o1 %= o2.
974
975 */
976
977 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
978 PyObject *o3);
979
980 /*
981 Returns the result of raising o1 to the power of o2, possibly
982 in-place, or null on failure. This is the equivalent of the Python
983 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
984
985 */
986
987 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
988
989 /*
990 Returns the result of left shifting o1 by o2, possibly in-place, or
991 null on failure. This is the equivalent of the Python expression:
992 o1 <<= o2.
993
994 */
995
996 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
997
998 /*
999 Returns the result of right shifting o1 by o2, possibly in-place or
1000 null on failure. This is the equivalent of the Python expression:
1001 o1 >>= o2.
1002
1003 */
1004
1005 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
1006
1007 /*
1008 Returns the result of bitwise and of o1 and o2, possibly in-place,
1009 or null on failure. This is the equivalent of the Python
1010 expression: o1 &= o2.
1011
1012 */
1013
1014 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
1015
1016 /*
1017 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
1018 null on failure. This is the equivalent of the Python expression:
1019 o1 ^= o2.
1020
1021 */
1022
1023 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
1024
1025 /*
1026 Returns the result of bitwise or of o1 and o2, possibly in-place,
1027 or null on failure. This is the equivalent of the Python
1028 expression: o1 |= o2.
1029
1030 */
1031
1032
1033 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
1034
1035 /*
1036 Returns the integer n converted to a string with a base, with a base
1037 marker of 0b, 0o or 0x prefixed if applicable.
1038 If n is not an int object, it is converted with PyNumber_Index first.
1039 */
1040
1041
1042/* Sequence protocol:*/
1043
1044 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
1045
1046 /*
1047 Return 1 if the object provides sequence protocol, and zero
1048 otherwise.
1049
1050 This function always succeeds.
1051
1052 */
1053
1054 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
1055
1056 /*
1057 Return the size of sequence object o, or -1 on failure.
1058
1059 */
1060
1061 /* For DLL compatibility */
1062#undef PySequence_Length
1063 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
1064#define PySequence_Length PySequence_Size
1065
1066
1067 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
1068
1069 /*
1070 Return the concatenation of o1 and o2 on success, and NULL on
1071 failure. This is the equivalent of the Python
1072 expression: o1+o2.
1073
1074 */
1075
1076 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
1077
1078 /*
1079 Return the result of repeating sequence object o count times,
1080 or NULL on failure. This is the equivalent of the Python
1081 expression: o1*count.
1082
1083 */
1084
1085 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
1086
1087 /*
1088 Return the ith element of o, or NULL on failure. This is the
1089 equivalent of the Python expression: o[i].
1090 */
1091
1092 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
1093
1094 /*
1095 Return the slice of sequence object o between i1 and i2, or
1096 NULL on failure. This is the equivalent of the Python
1097 expression: o[i1:i2].
1098
1099 */
1100
1101 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
1102
1103 /*
1104 Assign object v to the ith element of o. Returns
1105 -1 on failure. This is the equivalent of the Python
1106 statement: o[i]=v.
1107
1108 */
1109
1110 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
1111
1112 /*
1113 Delete the ith element of object v. Returns
1114 -1 on failure. This is the equivalent of the Python
1115 statement: del o[i].
1116 */
1117
1118 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
1119 PyObject *v);
1120
1121 /*
1122 Assign the sequence object, v, to the slice in sequence
1123 object, o, from i1 to i2. Returns -1 on failure. This is the
1124 equivalent of the Python statement: o[i1:i2]=v.
1125 */
1126
1127 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
1128
1129 /*
1130 Delete the slice in sequence object, o, from i1 to i2.
1131 Returns -1 on failure. This is the equivalent of the Python
1132 statement: del o[i1:i2].
1133 */
1134
1135 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
1136
1137 /*
1138 Returns the sequence, o, as a tuple on success, and NULL on failure.
1139 This is equivalent to the Python expression: tuple(o)
1140 */
1141
1142
1143 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
1144 /*
1145 Returns the sequence, o, as a list on success, and NULL on failure.
1146 This is equivalent to the Python expression: list(o)
1147 */
1148
1149 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
1150 /*
1151 Returns the sequence, o, as a tuple, unless it's already a
1152 tuple or list. Use PySequence_Fast_GET_ITEM to access the
1153 members of this list, and PySequence_Fast_GET_SIZE to get its length.
1154
1155 Returns NULL on failure. If the object does not support iteration,
1156 raises a TypeError exception with m as the message text.
1157 */
1158
1159#define PySequence_Fast_GET_SIZE(o) \
1160 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
1161 /*
1162 Return the size of o, assuming that o was returned by
1163 PySequence_Fast and is not NULL.
1164 */
1165
1166#define PySequence_Fast_GET_ITEM(o, i)\
1167 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
1168 /*
1169 Return the ith element of o, assuming that o was returned by
1170 PySequence_Fast, and that i is within bounds.
1171 */
1172
1173#define PySequence_ITEM(o, i)\
1174 ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
1175 /* Assume tp_as_sequence and sq_item exist and that i does not
1176 need to be corrected for a negative index
1177 */
1178
1179#define PySequence_Fast_ITEMS(sf) \
1180 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
1181 : ((PyTupleObject *)(sf))->ob_item)
1182 /* Return a pointer to the underlying item array for
1183 an object retured by PySequence_Fast */
1184
1185 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
1186
1187 /*
1188 Return the number of occurrences on value on o, that is,
1189 return the number of keys for which o[key]==value. On
1190 failure, return -1. This is equivalent to the Python
1191 expression: o.count(value).
1192 */
1193
1194 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
1195 /*
1196 Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
1197 Use __contains__ if possible, else _PySequence_IterSearch().
1198 */
1199
1200#define PY_ITERSEARCH_COUNT 1
1201#define PY_ITERSEARCH_INDEX 2
1202#define PY_ITERSEARCH_CONTAINS 3
1203 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
1204 PyObject *obj, int operation);
1205 /*
1206 Iterate over seq. Result depends on the operation:
1207 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if
1208 error.
1209 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of
1210 obj in seq; set ValueError and return -1 if none found;
1211 also return -1 on error.
1212 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on
1213 error.
1214 */
1215
1216/* For DLL-level backwards compatibility */
1217#undef PySequence_In
1218 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
1219
1220/* For source-level backwards compatibility */
1221#define PySequence_In PySequence_Contains
1222
1223 /*
1224 Determine if o contains value. If an item in o is equal to
1225 X, return 1, otherwise return 0. On error, return -1. This
1226 is equivalent to the Python expression: value in o.
1227 */
1228
1229 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
1230
1231 /*
1232 Return the first index for which o[i]=value. On error,
1233 return -1. This is equivalent to the Python
1234 expression: o.index(value).
1235 */
1236
1237/* In-place versions of some of the above Sequence functions. */
1238
1239 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
1240
1241 /*
1242 Append o2 to o1, in-place when possible. Return the resulting
1243 object, which could be o1, or NULL on failure. This is the
1244 equivalent of the Python expression: o1 += o2.
1245
1246 */
1247
1248 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
1249
1250 /*
1251 Repeat o1 by count, in-place when possible. Return the resulting
1252 object, which could be o1, or NULL on failure. This is the
1253 equivalent of the Python expression: o1 *= count.
1254
1255 */
1256
1257/* Mapping protocol:*/
1258
1259 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
1260
1261 /*
1262 Return 1 if the object provides mapping protocol, and zero
1263 otherwise.
1264
1265 This function always succeeds.
1266 */
1267
1268 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
1269
1270 /*
1271 Returns the number of keys in object o on success, and -1 on
1272 failure. For objects that do not provide sequence protocol,
1273 this is equivalent to the Python expression: len(o).
1274 */
1275
1276 /* For DLL compatibility */
1277#undef PyMapping_Length
1278 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
1279#define PyMapping_Length PyMapping_Size
1280
1281
1282 /* implemented as a macro:
1283
1284 int PyMapping_DelItemString(PyObject *o, char *key);
1285
1286 Remove the mapping for object, key, from the object *o.
1287 Returns -1 on failure. This is equivalent to
1288 the Python statement: del o[key].
1289 */
1290#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
1291
1292 /* implemented as a macro:
1293
1294 int PyMapping_DelItem(PyObject *o, PyObject *key);
1295
1296 Remove the mapping for object, key, from the object *o.
1297 Returns -1 on failure. This is equivalent to
1298 the Python statement: del o[key].
1299 */
1300#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
1301
1302 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, char *key);
1303
1304 /*
1305 On success, return 1 if the mapping object has the key, key,
1306 and 0 otherwise. This is equivalent to the Python expression:
1307 o.has_key(key).
1308
1309 This function always succeeds.
1310 */
1311
1312 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
1313
1314 /*
1315 Return 1 if the mapping object has the key, key,
1316 and 0 otherwise. This is equivalent to the Python expression:
1317 o.has_key(key).
1318
1319 This function always succeeds.
1320
1321 */
1322
1323 /* Implemented as macro:
1324
1325 PyObject *PyMapping_Keys(PyObject *o);
1326
1327 On success, return a list of the keys in object o. On
1328 failure, return NULL. This is equivalent to the Python
1329 expression: o.keys().
1330 */
1331#define PyMapping_Keys(O) PyObject_CallMethod(O,"keys",NULL)
1332
1333 /* Implemented as macro:
1334
1335 PyObject *PyMapping_Values(PyObject *o);
1336
1337 On success, return a list of the values in object o. On
1338 failure, return NULL. This is equivalent to the Python
1339 expression: o.values().
1340 */
1341#define PyMapping_Values(O) PyObject_CallMethod(O,"values",NULL)
1342
1343 /* Implemented as macro:
1344
1345 PyObject *PyMapping_Items(PyObject *o);
1346
1347 On success, return a list of the items in object o, where
1348 each item is a tuple containing a key-value pair. On
1349 failure, return NULL. This is equivalent to the Python
1350 expression: o.items().
1351
1352 */
1353#define PyMapping_Items(O) PyObject_CallMethod(O,"items",NULL)
1354
1355 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, char *key);
1356
1357 /*
1358 Return element of o corresponding to the object, key, or NULL
1359 on failure. This is the equivalent of the Python expression:
1360 o[key].
1361 */
1362
1363 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, char *key,
1364 PyObject *value);
1365
1366 /*
1367 Map the object, key, to the value, v. Returns
1368 -1 on failure. This is the equivalent of the Python
1369 statement: o[key]=v.
1370 */
1371
1372
1373PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
1374 /* isinstance(object, typeorclass) */
1375
1376PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
1377 /* issubclass(object, typeorclass) */
1378
1379
1380PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
1381
1382PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
1383
1384
1385#ifdef __cplusplus
1386}
1387#endif
1388#endif /* Py_ABSTRACTOBJECT_H */
Note: See TracBrowser for help on using the repository browser.