source: trunk/essentials/dev-lang/python/Include/abstract.h@ 3404

Last change on this file since 3404 was 3225, checked in by bird, 19 years ago

Python 2.5
File size: 38.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 PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
292
293 /*
294 Determine if the object, o, is callable. Return 1 if the
295 object is callable and 0 otherwise.
296
297 This function always succeeds.
298
299 */
300
301
302
303 PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
304 PyObject *args, PyObject *kw);
305
306 /*
307 Call a callable Python object, callable_object, with
308 arguments and keywords arguments. The 'args' argument can not be
309 NULL, but the 'kw' argument can be NULL.
310
311 */
312
313 PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
314 PyObject *args);
315
316 /*
317 Call a callable Python object, callable_object, with
318 arguments given by the tuple, args. If no arguments are
319 needed, then args may be NULL. Returns the result of the
320 call on success, or NULL on failure. This is the equivalent
321 of the Python expression: apply(o,args).
322
323 */
324
325 PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
326 char *format, ...);
327
328 /*
329 Call a callable Python object, callable_object, with a
330 variable number of C arguments. The C arguments are described
331 using a mkvalue-style format string. The format may be NULL,
332 indicating that no arguments are provided. Returns the
333 result of the call on success, or NULL on failure. This is
334 the equivalent of the Python expression: apply(o,args).
335
336 */
337
338
339 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o, char *m,
340 char *format, ...);
341
342 /*
343 Call the method named m of object o with a variable number of
344 C arguments. The C arguments are described by a mkvalue
345 format string. The format may be NULL, indicating that no
346 arguments are provided. Returns the result of the call on
347 success, or NULL on failure. This is the equivalent of the
348 Python expression: o.method(args).
349 */
350
351 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
352 char *format, ...);
353 PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
354 char *name,
355 char *format, ...);
356
357 PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
358 ...);
359
360 /*
361 Call a callable Python object, callable_object, with a
362 variable number of C arguments. The C arguments are provided
363 as PyObject * values, terminated by a NULL. Returns the
364 result of the call on success, or NULL on failure. This is
365 the equivalent of the Python expression: apply(o,args).
366 */
367
368
369 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
370 PyObject *m, ...);
371
372 /*
373 Call the method named m of object o with a variable number of
374 C arguments. The C arguments are provided as PyObject *
375 values, terminated by NULL. Returns the result of the call
376 on success, or NULL on failure. This is the equivalent of
377 the Python expression: o.method(args).
378 */
379
380
381 /* Implemented elsewhere:
382
383 long PyObject_Hash(PyObject *o);
384
385 Compute and return the hash, hash_value, of an object, o. On
386 failure, return -1. This is the equivalent of the Python
387 expression: hash(o).
388
389 */
390
391
392 /* Implemented elsewhere:
393
394 int PyObject_IsTrue(PyObject *o);
395
396 Returns 1 if the object, o, is considered to be true, 0 if o is
397 considered to be false and -1 on failure. This is equivalent to the
398 Python expression: not not o
399
400 */
401
402 /* Implemented elsewhere:
403
404 int PyObject_Not(PyObject *o);
405
406 Returns 0 if the object, o, is considered to be true, 1 if o is
407 considered to be false and -1 on failure. This is equivalent to the
408 Python expression: not o
409
410 */
411
412 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
413
414 /*
415 On success, returns a type object corresponding to the object
416 type of object o. On failure, returns NULL. This is
417 equivalent to the Python expression: type(o).
418 */
419
420 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
421
422 /*
423 Return the size of object o. If the object, o, provides
424 both sequence and mapping protocols, the sequence size is
425 returned. On error, -1 is returned. This is the equivalent
426 to the Python expression: len(o).
427
428 */
429
430 /* For DLL compatibility */
431#undef PyObject_Length
432 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
433#define PyObject_Length PyObject_Size
434
435 PyAPI_FUNC(Py_ssize_t) _PyObject_LengthHint(PyObject *o);
436
437 /*
438 Return the size of object o. If the object, o, provides
439 both sequence and mapping protocols, the sequence size is
440 returned. On error, -1 is returned. If the object provides
441 a __length_hint__() method, its value is returned. This is an
442 internal undocumented API provided for performance reasons;
443 for compatibility, don't use it outside the core. This is the
444 equivalent to the Python expression:
445 try:
446 return len(o)
447 except (AttributeError, TypeError):
448 exc_type, exc_value, exc_tb = sys.exc_info()
449 try:
450 return o.__length_hint__()
451 except:
452 pass
453 raise exc_type, exc_value, exc_tb
454 */
455
456 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
457
458 /*
459 Return element of o corresponding to the object, key, or NULL
460 on failure. This is the equivalent of the Python expression:
461 o[key].
462
463 */
464
465 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
466
467 /*
468 Map the object, key, to the value, v. Returns
469 -1 on failure. This is the equivalent of the Python
470 statement: o[key]=v.
471 */
472
473 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key);
474
475 /*
476 Remove the mapping for object, key, from the object *o.
477 Returns -1 on failure. This is equivalent to
478 the Python statement: del o[key].
479 */
480
481 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
482
483 /*
484 Delete the mapping for key from *o. Returns -1 on failure.
485 This is the equivalent of the Python statement: del o[key].
486 */
487
488 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
489 const char **buffer,
490 Py_ssize_t *buffer_len);
491
492 /*
493 Takes an arbitrary object which must support the (character,
494 single segment) buffer interface and returns a pointer to a
495 read-only memory location useable as character based input
496 for subsequent processing.
497
498 0 is returned on success. buffer and buffer_len are only
499 set in case no error occurs. Otherwise, -1 is returned and
500 an exception set.
501
502 */
503
504 PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
505
506 /*
507 Checks whether an arbitrary object supports the (character,
508 single segment) buffer interface. Returns 1 on success, 0
509 on failure.
510
511 */
512
513 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
514 const void **buffer,
515 Py_ssize_t *buffer_len);
516
517 /*
518 Same as PyObject_AsCharBuffer() except that this API expects
519 (readable, single segment) buffer interface and returns a
520 pointer to a read-only memory location which can contain
521 arbitrary data.
522
523 0 is returned on success. buffer and buffer_len are only
524 set in case no error occurrs. Otherwise, -1 is returned and
525 an exception set.
526
527 */
528
529 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
530 void **buffer,
531 Py_ssize_t *buffer_len);
532
533 /*
534 Takes an arbitrary object which must support the (writeable,
535 single segment) buffer interface and returns a pointer to a
536 writeable memory location in buffer of size buffer_len.
537
538 0 is returned on success. buffer and buffer_len are only
539 set in case no error occurrs. Otherwise, -1 is returned and
540 an exception set.
541
542 */
543
544/* Iterators */
545
546 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
547 /* Takes an object and returns an iterator for it.
548 This is typically a new iterator but if the argument
549 is an iterator, this returns itself. */
550
551#define PyIter_Check(obj) \
552 (PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_ITER) && \
553 (obj)->ob_type->tp_iternext != NULL)
554
555 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
556 /* Takes an iterator object and calls its tp_iternext slot,
557 returning the next value. If the iterator is exhausted,
558 this returns NULL without setting an exception.
559 NULL with an exception means an error occurred. */
560
561/* Number Protocol:*/
562
563 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
564
565 /*
566 Returns 1 if the object, o, provides numeric protocols, and
567 false otherwise.
568
569 This function always succeeds.
570
571 */
572
573 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
574
575 /*
576 Returns the result of adding o1 and o2, or null on failure.
577 This is the equivalent of the Python expression: o1+o2.
578
579
580 */
581
582 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
583
584 /*
585 Returns the result of subtracting o2 from o1, or null on
586 failure. This is the equivalent of the Python expression:
587 o1-o2.
588
589 */
590
591 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
592
593 /*
594 Returns the result of multiplying o1 and o2, or null on
595 failure. This is the equivalent of the Python expression:
596 o1*o2.
597
598
599 */
600
601 PyAPI_FUNC(PyObject *) PyNumber_Divide(PyObject *o1, PyObject *o2);
602
603 /*
604 Returns the result of dividing o1 by o2, or null on failure.
605 This is the equivalent of the Python expression: o1/o2.
606
607
608 */
609
610 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
611
612 /*
613 Returns the result of dividing o1 by o2 giving an integral result,
614 or null on failure.
615 This is the equivalent of the Python expression: o1//o2.
616
617
618 */
619
620 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
621
622 /*
623 Returns the result of dividing o1 by o2 giving a float result,
624 or null on failure.
625 This is the equivalent of the Python expression: o1/o2.
626
627
628 */
629
630 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
631
632 /*
633 Returns the remainder of dividing o1 by o2, or null on
634 failure. This is the equivalent of the Python expression:
635 o1%o2.
636
637
638 */
639
640 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
641
642 /*
643 See the built-in function divmod. Returns NULL on failure.
644 This is the equivalent of the Python expression:
645 divmod(o1,o2).
646
647
648 */
649
650 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
651 PyObject *o3);
652
653 /*
654 See the built-in function pow. Returns NULL on failure.
655 This is the equivalent of the Python expression:
656 pow(o1,o2,o3), where o3 is optional.
657
658 */
659
660 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
661
662 /*
663 Returns the negation of o on success, or null on failure.
664 This is the equivalent of the Python expression: -o.
665
666 */
667
668 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
669
670 /*
671 Returns the (what?) of o on success, or NULL on failure.
672 This is the equivalent of the Python expression: +o.
673
674 */
675
676 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
677
678 /*
679 Returns the absolute value of o, or null on failure. This is
680 the equivalent of the Python expression: abs(o).
681
682 */
683
684 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
685
686 /*
687 Returns the bitwise negation of o on success, or NULL on
688 failure. This is the equivalent of the Python expression:
689 ~o.
690
691
692 */
693
694 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
695
696 /*
697 Returns the result of left shifting o1 by o2 on success, or
698 NULL on failure. This is the equivalent of the Python
699 expression: o1 << o2.
700
701
702 */
703
704 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
705
706 /*
707 Returns the result of right shifting o1 by o2 on success, or
708 NULL on failure. This is the equivalent of the Python
709 expression: o1 >> o2.
710
711 */
712
713 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
714
715 /*
716 Returns the result of bitwise and of o1 and o2 on success, or
717 NULL on failure. This is the equivalent of the Python
718 expression: o1&o2.
719
720
721 */
722
723 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
724
725 /*
726 Returns the bitwise exclusive or of o1 by o2 on success, or
727 NULL on failure. This is the equivalent of the Python
728 expression: o1^o2.
729
730
731 */
732
733 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
734
735 /*
736 Returns the result of bitwise or on o1 and o2 on success, or
737 NULL on failure. This is the equivalent of the Python
738 expression: o1|o2.
739
740 */
741
742 /* Implemented elsewhere:
743
744 int PyNumber_Coerce(PyObject **p1, PyObject **p2);
745
746 This function takes the addresses of two variables of type
747 PyObject*.
748
749 If the objects pointed to by *p1 and *p2 have the same type,
750 increment their reference count and return 0 (success).
751 If the objects can be converted to a common numeric type,
752 replace *p1 and *p2 by their converted value (with 'new'
753 reference counts), and return 0.
754 If no conversion is possible, or if some other error occurs,
755 return -1 (failure) and don't increment the reference counts.
756 The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python
757 statement o1, o2 = coerce(o1, o2).
758
759 */
760
761#define PyIndex_Check(obj) \
762 ((obj)->ob_type->tp_as_number != NULL && \
763 PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_INDEX) && \
764 (obj)->ob_type->tp_as_number->nb_index != NULL)
765
766 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
767
768 /*
769 Returns the object converted to a Python long or int
770 or NULL with an error raised on failure.
771 */
772
773 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
774
775 /*
776 Returns the object converted to Py_ssize_t by going through
777 PyNumber_Index first. If an overflow error occurs while
778 converting the int-or-long to Py_ssize_t, then the second argument
779 is the error-type to return. If it is NULL, then the overflow error
780 is cleared and the value is clipped.
781 */
782
783 PyAPI_FUNC(PyObject *) PyNumber_Int(PyObject *o);
784
785 /*
786 Returns the o converted to an integer object on success, or
787 NULL on failure. This is the equivalent of the Python
788 expression: int(o).
789
790 */
791
792 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
793
794 /*
795 Returns the o converted to a long integer object on success,
796 or NULL on failure. This is the equivalent of the Python
797 expression: long(o).
798
799 */
800
801 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
802
803 /*
804 Returns the o converted to a float object on success, or NULL
805 on failure. This is the equivalent of the Python expression:
806 float(o).
807 */
808
809/* In-place variants of (some of) the above number protocol functions */
810
811 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
812
813 /*
814 Returns the result of adding o2 to o1, possibly in-place, or null
815 on failure. This is the equivalent of the Python expression:
816 o1 += o2.
817
818 */
819
820 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
821
822 /*
823 Returns the result of subtracting o2 from o1, possibly in-place or
824 null on failure. This is the equivalent of the Python expression:
825 o1 -= o2.
826
827 */
828
829 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
830
831 /*
832 Returns the result of multiplying o1 by o2, possibly in-place, or
833 null on failure. This is the equivalent of the Python expression:
834 o1 *= o2.
835
836 */
837
838 PyAPI_FUNC(PyObject *) PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2);
839
840 /*
841 Returns the result of dividing o1 by o2, possibly in-place, or null
842 on failure. This is the equivalent of the Python expression:
843 o1 /= o2.
844
845 */
846
847 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
848 PyObject *o2);
849
850 /*
851 Returns the result of dividing o1 by o2 giving an integral result,
852 possibly in-place, or null on failure.
853 This is the equivalent of the Python expression:
854 o1 /= o2.
855
856 */
857
858 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
859 PyObject *o2);
860
861 /*
862 Returns the result of dividing o1 by o2 giving a float result,
863 possibly in-place, or null on failure.
864 This is the equivalent of the Python expression:
865 o1 /= o2.
866
867 */
868
869 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
870
871 /*
872 Returns the remainder of dividing o1 by o2, possibly in-place, or
873 null on failure. This is the equivalent of the Python expression:
874 o1 %= o2.
875
876 */
877
878 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
879 PyObject *o3);
880
881 /*
882 Returns the result of raising o1 to the power of o2, possibly
883 in-place, or null on failure. This is the equivalent of the Python
884 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
885
886 */
887
888 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
889
890 /*
891 Returns the result of left shifting o1 by o2, possibly in-place, or
892 null on failure. This is the equivalent of the Python expression:
893 o1 <<= o2.
894
895 */
896
897 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
898
899 /*
900 Returns the result of right shifting o1 by o2, possibly in-place or
901 null on failure. This is the equivalent of the Python expression:
902 o1 >>= o2.
903
904 */
905
906 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
907
908 /*
909 Returns the result of bitwise and of o1 and o2, possibly in-place,
910 or null on failure. This is the equivalent of the Python
911 expression: o1 &= o2.
912
913 */
914
915 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
916
917 /*
918 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
919 null on failure. This is the equivalent of the Python expression:
920 o1 ^= o2.
921
922 */
923
924 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
925
926 /*
927 Returns the result of bitwise or of o1 and o2, possibly in-place,
928 or null on failure. This is the equivalent of the Python
929 expression: o1 |= o2.
930
931 */
932
933
934/* Sequence protocol:*/
935
936 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
937
938 /*
939 Return 1 if the object provides sequence protocol, and zero
940 otherwise.
941
942 This function always succeeds.
943
944 */
945
946 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
947
948 /*
949 Return the size of sequence object o, or -1 on failure.
950
951 */
952
953 /* For DLL compatibility */
954#undef PySequence_Length
955 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
956#define PySequence_Length PySequence_Size
957
958
959 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
960
961 /*
962 Return the concatenation of o1 and o2 on success, and NULL on
963 failure. This is the equivalent of the Python
964 expression: o1+o2.
965
966 */
967
968 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
969
970 /*
971 Return the result of repeating sequence object o count times,
972 or NULL on failure. This is the equivalent of the Python
973 expression: o1*count.
974
975 */
976
977 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
978
979 /*
980 Return the ith element of o, or NULL on failure. This is the
981 equivalent of the Python expression: o[i].
982 */
983
984 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
985
986 /*
987 Return the slice of sequence object o between i1 and i2, or
988 NULL on failure. This is the equivalent of the Python
989 expression: o[i1:i2].
990
991 */
992
993 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
994
995 /*
996 Assign object v to the ith element of o. Returns
997 -1 on failure. This is the equivalent of the Python
998 statement: o[i]=v.
999
1000 */
1001
1002 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
1003
1004 /*
1005 Delete the ith element of object v. Returns
1006 -1 on failure. This is the equivalent of the Python
1007 statement: del o[i].
1008 */
1009
1010 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
1011 PyObject *v);
1012
1013 /*
1014 Assign the sequence object, v, to the slice in sequence
1015 object, o, from i1 to i2. Returns -1 on failure. This is the
1016 equivalent of the Python statement: o[i1:i2]=v.
1017 */
1018
1019 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
1020
1021 /*
1022 Delete the slice in sequence object, o, from i1 to i2.
1023 Returns -1 on failure. This is the equivalent of the Python
1024 statement: del o[i1:i2].
1025 */
1026
1027 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
1028
1029 /*
1030 Returns the sequence, o, as a tuple on success, and NULL on failure.
1031 This is equivalent to the Python expression: tuple(o)
1032 */
1033
1034
1035 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
1036 /*
1037 Returns the sequence, o, as a list on success, and NULL on failure.
1038 This is equivalent to the Python expression: list(o)
1039 */
1040
1041 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
1042 /*
1043 Returns the sequence, o, as a tuple, unless it's already a
1044 tuple or list. Use PySequence_Fast_GET_ITEM to access the
1045 members of this list, and PySequence_Fast_GET_SIZE to get its length.
1046
1047 Returns NULL on failure. If the object does not support iteration,
1048 raises a TypeError exception with m as the message text.
1049 */
1050
1051#define PySequence_Fast_GET_SIZE(o) \
1052 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
1053 /*
1054 Return the size of o, assuming that o was returned by
1055 PySequence_Fast and is not NULL.
1056 */
1057
1058#define PySequence_Fast_GET_ITEM(o, i)\
1059 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
1060 /*
1061 Return the ith element of o, assuming that o was returned by
1062 PySequence_Fast, and that i is within bounds.
1063 */
1064
1065#define PySequence_ITEM(o, i)\
1066 ( o->ob_type->tp_as_sequence->sq_item(o, i) )
1067 /* Assume tp_as_sequence and sq_item exist and that i does not
1068 need to be corrected for a negative index
1069 */
1070
1071#define PySequence_Fast_ITEMS(sf) \
1072 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
1073 : ((PyTupleObject *)(sf))->ob_item)
1074 /* Return a pointer to the underlying item array for
1075 an object retured by PySequence_Fast */
1076
1077 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
1078
1079 /*
1080 Return the number of occurrences on value on o, that is,
1081 return the number of keys for which o[key]==value. On
1082 failure, return -1. This is equivalent to the Python
1083 expression: o.count(value).
1084 */
1085
1086 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
1087 /*
1088 Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
1089 Use __contains__ if possible, else _PySequence_IterSearch().
1090 */
1091
1092#define PY_ITERSEARCH_COUNT 1
1093#define PY_ITERSEARCH_INDEX 2
1094#define PY_ITERSEARCH_CONTAINS 3
1095 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
1096 PyObject *obj, int operation);
1097 /*
1098 Iterate over seq. Result depends on the operation:
1099 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if
1100 error.
1101 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of
1102 obj in seq; set ValueError and return -1 if none found;
1103 also return -1 on error.
1104 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on
1105 error.
1106 */
1107
1108/* For DLL-level backwards compatibility */
1109#undef PySequence_In
1110 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
1111
1112/* For source-level backwards compatibility */
1113#define PySequence_In PySequence_Contains
1114
1115 /*
1116 Determine if o contains value. If an item in o is equal to
1117 X, return 1, otherwise return 0. On error, return -1. This
1118 is equivalent to the Python expression: value in o.
1119 */
1120
1121 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
1122
1123 /*
1124 Return the first index for which o[i]=value. On error,
1125 return -1. This is equivalent to the Python
1126 expression: o.index(value).
1127 */
1128
1129/* In-place versions of some of the above Sequence functions. */
1130
1131 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
1132
1133 /*
1134 Append o2 to o1, in-place when possible. Return the resulting
1135 object, which could be o1, or NULL on failure. This is the
1136 equivalent of the Python expression: o1 += o2.
1137
1138 */
1139
1140 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
1141
1142 /*
1143 Repeat o1 by count, in-place when possible. Return the resulting
1144 object, which could be o1, or NULL on failure. This is the
1145 equivalent of the Python expression: o1 *= count.
1146
1147 */
1148
1149/* Mapping protocol:*/
1150
1151 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
1152
1153 /*
1154 Return 1 if the object provides mapping protocol, and zero
1155 otherwise.
1156
1157 This function always succeeds.
1158 */
1159
1160 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
1161
1162 /*
1163 Returns the number of keys in object o on success, and -1 on
1164 failure. For objects that do not provide sequence protocol,
1165 this is equivalent to the Python expression: len(o).
1166 */
1167
1168 /* For DLL compatibility */
1169#undef PyMapping_Length
1170 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
1171#define PyMapping_Length PyMapping_Size
1172
1173
1174 /* implemented as a macro:
1175
1176 int PyMapping_DelItemString(PyObject *o, char *key);
1177
1178 Remove the mapping for object, key, from the object *o.
1179 Returns -1 on failure. This is equivalent to
1180 the Python statement: del o[key].
1181 */
1182#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
1183
1184 /* implemented as a macro:
1185
1186 int PyMapping_DelItem(PyObject *o, PyObject *key);
1187
1188 Remove the mapping for object, key, from the object *o.
1189 Returns -1 on failure. This is equivalent to
1190 the Python statement: del o[key].
1191 */
1192#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
1193
1194 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, char *key);
1195
1196 /*
1197 On success, return 1 if the mapping object has the key, key,
1198 and 0 otherwise. This is equivalent to the Python expression:
1199 o.has_key(key).
1200
1201 This function always succeeds.
1202 */
1203
1204 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
1205
1206 /*
1207 Return 1 if the mapping object has the key, key,
1208 and 0 otherwise. This is equivalent to the Python expression:
1209 o.has_key(key).
1210
1211 This function always succeeds.
1212
1213 */
1214
1215 /* Implemented as macro:
1216
1217 PyObject *PyMapping_Keys(PyObject *o);
1218
1219 On success, return a list of the keys in object o. On
1220 failure, return NULL. This is equivalent to the Python
1221 expression: o.keys().
1222 */
1223#define PyMapping_Keys(O) PyObject_CallMethod(O,"keys",NULL)
1224
1225 /* Implemented as macro:
1226
1227 PyObject *PyMapping_Values(PyObject *o);
1228
1229 On success, return a list of the values in object o. On
1230 failure, return NULL. This is equivalent to the Python
1231 expression: o.values().
1232 */
1233#define PyMapping_Values(O) PyObject_CallMethod(O,"values",NULL)
1234
1235 /* Implemented as macro:
1236
1237 PyObject *PyMapping_Items(PyObject *o);
1238
1239 On success, return a list of the items in object o, where
1240 each item is a tuple containing a key-value pair. On
1241 failure, return NULL. This is equivalent to the Python
1242 expression: o.items().
1243
1244 */
1245#define PyMapping_Items(O) PyObject_CallMethod(O,"items",NULL)
1246
1247 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, char *key);
1248
1249 /*
1250 Return element of o corresponding to the object, key, or NULL
1251 on failure. This is the equivalent of the Python expression:
1252 o[key].
1253 */
1254
1255 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, char *key,
1256 PyObject *value);
1257
1258 /*
1259 Map the object, key, to the value, v. Returns
1260 -1 on failure. This is the equivalent of the Python
1261 statement: o[key]=v.
1262 */
1263
1264
1265PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
1266 /* isinstance(object, typeorclass) */
1267
1268PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
1269 /* issubclass(object, typeorclass) */
1270
1271
1272#ifdef __cplusplus
1273}
1274#endif
1275#endif /* Py_ABSTRACTOBJECT_H */
Note: See TracBrowser for help on using the repository browser.