rest25/c-api/concrete.rst => rest262/c-api/concrete.rst
24
25.. _fundamental:
26
27Fundamental Objects
28===================
29
30This section describes Python type objects and the singleton object ``None``.
31
n32+.. toctree::
32
n33-.. _typeobjects:
n34+   type.rst
34- 
35+   none.rst
35-Type Objects
36-------------
37- 
38-.. index:: object: type
39- 
40- 
41-.. ctype:: PyTypeObject
42- 
43-   The C structure of the objects used to describe built-in types.
44- 
45- 
46-.. cvar:: PyObject* PyType_Type
47- 
48-   .. index:: single: TypeType (in module types)
49- 
50-   This is the type object for type objects; it is the same object as ``type`` and
51-   ``types.TypeType`` in the Python layer.
52- 
53- 
54-.. cfunction:: int PyType_Check(PyObject *o)
55- 
56-   Return true if the object *o* is a type object, including instances of types
57-   derived from the standard type object.  Return false in all other cases.
58- 
59- 
60-.. cfunction:: int PyType_CheckExact(PyObject *o)
61- 
62-   Return true if the object *o* is a type object, but not a subtype of the
63-   standard type object.  Return false in all other cases.
64- 
65-   .. versionadded:: 2.2
66- 
67- 
68-.. cfunction:: int PyType_HasFeature(PyObject *o, int feature)
69- 
70-   Return true if the type object *o* sets the feature *feature*.  Type features
71-   are denoted by single bit flags.
72- 
73- 
74-.. cfunction:: int PyType_IS_GC(PyObject *o)
75- 
76-   Return true if the type object includes support for the cycle detector; this
77-   tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
78- 
79-   .. versionadded:: 2.0
80- 
81- 
82-.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
83- 
84-   Return true if *a* is a subtype of *b*.
85- 
86-   .. versionadded:: 2.2
87- 
88- 
89-.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
90- 
91-   .. versionadded:: 2.2
92- 
93- 
94-.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
95- 
96-   .. versionadded:: 2.2
97- 
98- 
99-.. cfunction:: int PyType_Ready(PyTypeObject *type)
100- 
101-   Finalize a type object.  This should be called on all type objects to finish
102-   their initialization.  This function is responsible for adding inherited slots
103-   from a type's base class.  Return ``0`` on success, or return ``-1`` and sets an
104-   exception on error.
105- 
106-   .. versionadded:: 2.2
107- 
108- 
109-.. _noneobject:
110- 
111-The None Object
112----------------
113- 
114-.. index:: object: None
115- 
116-Note that the :ctype:`PyTypeObject` for ``None`` is not directly exposed in the
117-Python/C API.  Since ``None`` is a singleton, testing for object identity (using
118-``==`` in C) is sufficient. There is no :cfunc:`PyNone_Check` function for the
119-same reason.
120- 
121- 
122-.. cvar:: PyObject* Py_None
123- 
124-   The Python ``None`` object, denoting lack of value.  This object has no methods.
125-   It needs to be treated just like any other object with respect to reference
126-   counts.
127- 
128- 
129-.. cmacro:: Py_RETURN_NONE
130- 
131-   Properly handle returning :cdata:`Py_None` from within a C function.
132
133
134.. _numericobjects:
135
136Numeric Objects
137===============
138
139.. index:: object: numeric
140
n45+.. toctree::
141
n142-.. _intobjects:
n47+   int.rst
143- 
48+   bool.rst
144-Plain Integer Objects
49+   long.rst
145----------------------
50+   float.rst
146- 
51+   complex.rst
147-.. index:: object: integer
148- 
149- 
150-.. ctype:: PyIntObject
151- 
152-   This subtype of :ctype:`PyObject` represents a Python integer object.
153- 
154- 
155-.. cvar:: PyTypeObject PyInt_Type
156- 
157-   .. index:: single: IntType (in modules types)
158- 
159-   This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
160-   This is the same object as ``int`` and ``types.IntType``.
161- 
162- 
163-.. cfunction:: int PyInt_Check(PyObject *o)
164- 
165-   Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
166-   :cdata:`PyInt_Type`.
167- 
168-   .. versionchanged:: 2.2
169-      Allowed subtypes to be accepted.
170- 
171- 
172-.. cfunction:: int PyInt_CheckExact(PyObject *o)
173- 
174-   Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
175-   :cdata:`PyInt_Type`.
176- 
177-   .. versionadded:: 2.2
178- 
179- 
180-.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)
181- 
182-   Return a new :ctype:`PyIntObject` or :ctype:`PyLongObject` based on the string
183-   value in *str*, which is interpreted according to the radix in *base*.  If
184-   *pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
185-   follows the representation of the number.  If *base* is ``0``, the radix will be
186-   determined based on the leading characters of *str*: if *str* starts with
187-   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
188-   8 will be used; otherwise radix 10 will be used.  If *base* is not ``0``, it
189-   must be between ``2`` and ``36``, inclusive.  Leading spaces are ignored.  If
190-   there are no digits, :exc:`ValueError` will be raised.  If the string represents
191-   a number too large to be contained within the machine's :ctype:`long int` type
192-   and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
193-   returned.  If overflow warnings are not being suppressed, *NULL* will be
194-   returned in this case.
195- 
196- 
197-.. cfunction:: PyObject* PyInt_FromLong(long ival)
198- 
199-   Create a new integer object with a value of *ival*.
200- 
201-   The current implementation keeps an array of integer objects for all integers
202-   between ``-5`` and ``256``, when you create an int in that range you actually
203-   just get back a reference to the existing object. So it should be possible to
204-   change the value of ``1``.  I suspect the behaviour of Python in this case is
205-   undefined. :-)
206- 
207- 
208-.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)
209- 
210-   Create a new integer object with a value of *ival*. If the value exceeds
211-   ``LONG_MAX``, a long integer object is returned.
212- 
213-   .. versionadded:: 2.5
214- 
215- 
216-.. cfunction:: long PyInt_AsLong(PyObject *io)
217- 
218-   Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
219-   already one, and then return its value. If there is an error, ``-1`` is
220-   returned, and the caller should check ``PyErr_Occurred()`` to find out whether
221-   there was an error, or whether the value just happened to be -1.
222- 
223- 
224-.. cfunction:: long PyInt_AS_LONG(PyObject *io)
225- 
226-   Return the value of the object *io*.  No error checking is performed.
227- 
228- 
229-.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
230- 
231-   Will first attempt to cast the object to a :ctype:`PyIntObject` or
232-   :ctype:`PyLongObject`, if it is not already one, and then return its value as
233-   unsigned long.  This function does not check for overflow.
234- 
235-   .. versionadded:: 2.3
236- 
237- 
238-.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
239- 
240-   Will first attempt to cast the object to a :ctype:`PyIntObject` or
241-   :ctype:`PyLongObject`, if it is not already one, and then return its value as
242-   unsigned long long, without checking for overflow.
243- 
244-   .. versionadded:: 2.3
245- 
246- 
247-.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
248- 
249-   Will first attempt to cast the object to a :ctype:`PyIntObject` or
250-   :ctype:`PyLongObject`, if it is not already one, and then return its value as
251-   :ctype:`Py_ssize_t`.
252- 
253-   .. versionadded:: 2.5
254- 
255- 
256-.. cfunction:: long PyInt_GetMax()
257- 
258-   .. index:: single: LONG_MAX
259- 
260-   Return the system's idea of the largest integer it can handle
261-   (:const:`LONG_MAX`, as defined in the system header files).
262- 
263- 
264-.. _boolobjects:
265- 
266-Boolean Objects
267----------------
268- 
269-Booleans in Python are implemented as a subclass of integers.  There are only
270-two booleans, :const:`Py_False` and :const:`Py_True`.  As such, the normal
271-creation and deletion functions don't apply to booleans.  The following macros
272-are available, however.
273- 
274- 
275-.. cfunction:: int PyBool_Check(PyObject *o)
276- 
277-   Return true if *o* is of type :cdata:`PyBool_Type`.
278- 
279-   .. versionadded:: 2.3
280- 
281- 
282-.. cvar:: PyObject* Py_False
283- 
284-   The Python ``False`` object.  This object has no methods.  It needs to be
285-   treated just like any other object with respect to reference counts.
286- 
287- 
288-.. cvar:: PyObject* Py_True
289- 
290-   The Python ``True`` object.  This object has no methods.  It needs to be treated
291-   just like any other object with respect to reference counts.
292- 
293- 
294-.. cmacro:: Py_RETURN_FALSE
295- 
296-   Return :const:`Py_False` from a function, properly incrementing its reference
297-   count.
298- 
299-   .. versionadded:: 2.4
300- 
301- 
302-.. cmacro:: Py_RETURN_TRUE
303- 
304-   Return :const:`Py_True` from a function, properly incrementing its reference
305-   count.
306- 
307-   .. versionadded:: 2.4
308- 
309- 
310-.. cfunction:: PyObject* PyBool_FromLong(long v)
311- 
312-   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
313-   truth value of *v*.
314- 
315-   .. versionadded:: 2.3
316- 
317- 
318-.. _longobjects:
319- 
320-Long Integer Objects
321---------------------
322- 
323-.. index:: object: long integer
324- 
325- 
326-.. ctype:: PyLongObject
327- 
328-   This subtype of :ctype:`PyObject` represents a Python long integer object.
329- 
330- 
331-.. cvar:: PyTypeObject PyLong_Type
332- 
333-   .. index:: single: LongType (in modules types)
334- 
335-   This instance of :ctype:`PyTypeObject` represents the Python long integer type.
336-   This is the same object as ``long`` and ``types.LongType``.
337- 
338- 
339-.. cfunction:: int PyLong_Check(PyObject *p)
340- 
341-   Return true if its argument is a :ctype:`PyLongObject` or a subtype of
342-   :ctype:`PyLongObject`.
343- 
344-   .. versionchanged:: 2.2
345-      Allowed subtypes to be accepted.
346- 
347- 
348-.. cfunction:: int PyLong_CheckExact(PyObject *p)
349- 
350-   Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
351-   :ctype:`PyLongObject`.
352- 
353-   .. versionadded:: 2.2
354- 
355- 
356-.. cfunction:: PyObject* PyLong_FromLong(long v)
357- 
358-   Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
359- 
360- 
361-.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
362- 
363-   Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
364-   *NULL* on failure.
365- 
366- 
367-.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
368- 
369-   Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
370-   on failure.
371- 
372- 
373-.. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
374- 
375-   Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`,
376-   or *NULL* on failure.
377- 
378- 
379-.. cfunction:: PyObject* PyLong_FromDouble(double v)
380- 
381-   Return a new :ctype:`PyLongObject` object from the integer part of *v*, or
382-   *NULL* on failure.
383- 
384- 
385-.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
386- 
387-   Return a new :ctype:`PyLongObject` based on the string value in *str*, which is
388-   interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
389-   ``*pend`` will point to the first character in *str* which follows the
390-   representation of the number.  If *base* is ``0``, the radix will be determined
391-   based on the leading characters of *str*: if *str* starts with ``'0x'`` or
392-   ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be
393-   used; otherwise radix 10 will be used.  If *base* is not ``0``, it must be
394-   between ``2`` and ``36``, inclusive.  Leading spaces are ignored.  If there are
395-   no digits, :exc:`ValueError` will be raised.
396- 
397- 
398-.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
399- 
400-   Convert a sequence of Unicode digits to a Python long integer value.  The first
401-   parameter, *u*, points to the first character of the Unicode string, *length*
402-   gives the number of characters, and *base* is the radix for the conversion.  The
403-   radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
404-   will be raised.
405- 
406-   .. versionadded:: 1.6
407- 
408- 
409-.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
410- 
411-   Create a Python integer or long integer from the pointer *p*. The pointer value
412-   can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
413- 
414-   .. versionadded:: 1.5.2
415- 
416-   .. versionchanged:: 2.5
417-      If the integer is larger than LONG_MAX, a positive long integer is returned.
418- 
419- 
420-.. cfunction:: long PyLong_AsLong(PyObject *pylong)
421- 
422-   .. index::
423-      single: LONG_MAX
424-      single: OverflowError (built-in exception)
425- 
426-   Return a C :ctype:`long` representation of the contents of *pylong*.  If
427-   *pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised.
428- 
429- 
430-.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
431- 
432-   .. index::
433-      single: ULONG_MAX
434-      single: OverflowError (built-in exception)
435- 
436-   Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
437-   If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
438-   raised.
439- 
440- 
441-.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
442- 
443-   Return a C :ctype:`long long` from a Python long integer.  If *pylong* cannot be
444-   represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
445- 
446-   .. versionadded:: 2.2
447- 
448- 
449-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
450- 
451-   Return a C :ctype:`unsigned long long` from a Python long integer. If *pylong*
452-   cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
453-   will be raised if the value is positive, or a :exc:`TypeError` will be raised if
454-   the value is negative.
455- 
456-   .. versionadded:: 2.2
457- 
458- 
459-.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
460- 
461-   Return a C :ctype:`unsigned long` from a Python long integer, without checking
462-   for overflow.
463- 
464-   .. versionadded:: 2.3
465- 
466- 
467-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
468- 
469-   Return a C :ctype:`unsigned long long` from a Python long integer, without
470-   checking for overflow.
471- 
472-   .. versionadded:: 2.3
473- 
474- 
475-.. cfunction:: double PyLong_AsDouble(PyObject *pylong)
476- 
477-   Return a C :ctype:`double` representation of the contents of *pylong*.  If
478-   *pylong* cannot be approximately represented as a :ctype:`double`, an
479-   :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
480- 
481- 
482-.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
483- 
484-   Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.
485-   If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This
486-   is only assured to produce a usable :ctype:`void` pointer for values created
487-   with :cfunc:`PyLong_FromVoidPtr`.
488- 
489-   .. versionadded:: 1.5.2
490- 
491-   .. versionchanged:: 2.5
492-      For values outside 0..LONG_MAX, both signed and unsigned integers are acccepted.
493- 
494- 
495-.. _floatobjects:
496- 
497-Floating Point Objects
498-----------------------
499- 
500-.. index:: object: floating point
501- 
502- 
503-.. ctype:: PyFloatObject
504- 
505-   This subtype of :ctype:`PyObject` represents a Python floating point object.
506- 
507- 
508-.. cvar:: PyTypeObject PyFloat_Type
509- 
510-   .. index:: single: FloatType (in modules types)
511- 
512-   This instance of :ctype:`PyTypeObject` represents the Python floating point
513-   type.  This is the same object as ``float`` and ``types.FloatType``.
514- 
515- 
516-.. cfunction:: int PyFloat_Check(PyObject *p)
517- 
518-   Return true if its argument is a :ctype:`PyFloatObject` or a subtype of
519-   :ctype:`PyFloatObject`.
520- 
521-   .. versionchanged:: 2.2
522-      Allowed subtypes to be accepted.
523- 
524- 
525-.. cfunction:: int PyFloat_CheckExact(PyObject *p)
526- 
527-   Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
528-   :ctype:`PyFloatObject`.
529- 
530-   .. versionadded:: 2.2
531- 
532- 
533-.. cfunction:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
534- 
535-   Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
536-   *NULL* on failure.  The *pend* argument is ignored.  It remains only for
537-   backward compatibility.
538- 
539- 
540-.. cfunction:: PyObject* PyFloat_FromDouble(double v)
541- 
542-   Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.
543- 
544- 
545-.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)
546- 
547-   Return a C :ctype:`double` representation of the contents of *pyfloat*.
548- 
549- 
550-.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
551- 
552-   Return a C :ctype:`double` representation of the contents of *pyfloat*, but
553-   without error checking.
554- 
555- 
556-.. _complexobjects:
557- 
558-Complex Number Objects
559-----------------------
560- 
561-.. index:: object: complex number
562- 
563-Python's complex number objects are implemented as two distinct types when
564-viewed from the C API:  one is the Python object exposed to Python programs, and
565-the other is a C structure which represents the actual complex number value.
566-The API provides functions for working with both.
567- 
568- 
569-Complex Numbers as C Structures
570-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
571- 
572-Note that the functions which accept these structures as parameters and return
573-them as results do so *by value* rather than dereferencing them through
574-pointers.  This is consistent throughout the API.
575- 
576- 
577-.. ctype:: Py_complex
578- 
579-   The C structure which corresponds to the value portion of a Python complex
580-   number object.  Most of the functions for dealing with complex number objects
581-   use structures of this type as input or output values, as appropriate.  It is
582-   defined as::
583- 
584-      typedef struct {
585-         double real;
586-         double imag;
587-      } Py_complex;
588- 
589- 
590-.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
591- 
592-   Return the sum of two complex numbers, using the C :ctype:`Py_complex`
593-   representation.
594- 
595- 
596-.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
597- 
598-   Return the difference between two complex numbers, using the C
599-   :ctype:`Py_complex` representation.
600- 
601- 
602-.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)
603- 
604-   Return the negation of the complex number *complex*, using the C
605-   :ctype:`Py_complex` representation.
606- 
607- 
608-.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
609- 
610-   Return the product of two complex numbers, using the C :ctype:`Py_complex`
611-   representation.
612- 
613- 
614-.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
615- 
616-   Return the quotient of two complex numbers, using the C :ctype:`Py_complex`
617-   representation.
618- 
619- 
620-.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
621- 
622-   Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
623-   representation.
624- 
625- 
626-Complex Numbers as Python Objects
627-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
628- 
629- 
630-.. ctype:: PyComplexObject
631- 
632-   This subtype of :ctype:`PyObject` represents a Python complex number object.
633- 
634- 
635-.. cvar:: PyTypeObject PyComplex_Type
636- 
637-   This instance of :ctype:`PyTypeObject` represents the Python complex number
638-   type. It is the same object as ``complex`` and ``types.ComplexType``.
639- 
640- 
641-.. cfunction:: int PyComplex_Check(PyObject *p)
642- 
643-   Return true if its argument is a :ctype:`PyComplexObject` or a subtype of
644-   :ctype:`PyComplexObject`.
645- 
646-   .. versionchanged:: 2.2
647-      Allowed subtypes to be accepted.
648- 
649- 
650-.. cfunction:: int PyComplex_CheckExact(PyObject *p)
651- 
652-   Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
653-   :ctype:`PyComplexObject`.
654- 
655-   .. versionadded:: 2.2
656- 
657- 
658-.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)
659- 
660-   Create a new Python complex number object from a C :ctype:`Py_complex` value.
661- 
662- 
663-.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)
664- 
665-   Return a new :ctype:`PyComplexObject` object from *real* and *imag*.
666- 
667- 
668-.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)
669- 
670-   Return the real part of *op* as a C :ctype:`double`.
671- 
672- 
673-.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)
674- 
675-   Return the imaginary part of *op* as a C :ctype:`double`.
676- 
677- 
678-.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
679- 
680-   Return the :ctype:`Py_complex` value of the complex number *op*.
681
682
683.. _sequenceobjects:
684
685Sequence Objects
686================
687
688.. index:: object: sequence
689
690Generic operations on sequence objects were discussed in the previous chapter;
691this section deals with the specific kinds of sequence objects that are
692intrinsic to the Python language.
693
n65+.. toctree::
694
n695-.. _stringobjects:
n67+   bytearray.rst
696- 
68+   string.rst
697-String Objects
69+   unicode.rst
698---------------
70+   buffer.rst
699- 
71+   tuple.rst
700-These functions raise :exc:`TypeError` when expecting a string parameter and are
72+   list.rst
701-called with a non-string parameter.
702- 
703-.. index:: object: string
704- 
705- 
706-.. ctype:: PyStringObject
707- 
708-   This subtype of :ctype:`PyObject` represents a Python string object.
709- 
710- 
711-.. cvar:: PyTypeObject PyString_Type
712- 
713-   .. index:: single: StringType (in module types)
714- 
715-   This instance of :ctype:`PyTypeObject` represents the Python string type; it is
716-   the same object as ``str`` and ``types.StringType`` in the Python layer. .
717- 
718- 
719-.. cfunction:: int PyString_Check(PyObject *o)
720- 
721-   Return true if the object *o* is a string object or an instance of a subtype of
722-   the string type.
723- 
724-   .. versionchanged:: 2.2
725-      Allowed subtypes to be accepted.
726- 
727- 
728-.. cfunction:: int PyString_CheckExact(PyObject *o)
729- 
730-   Return true if the object *o* is a string object, but not an instance of a
731-   subtype of the string type.
732- 
733-   .. versionadded:: 2.2
734- 
735- 
736-.. cfunction:: PyObject* PyString_FromString(const char *v)
737- 
738-   Return a new string object with the value *v* on success, and *NULL* on failure.
739-   The parameter *v* must not be *NULL*; it will not be checked.
740- 
741- 
742-.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
743- 
744-   Return a new string object with the value *v* and length *len* on success, and
745-   *NULL* on failure.  If *v* is *NULL*, the contents of the string are
746-   uninitialized.
747- 
748- 
749-.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
750- 
751-   Take a C :cfunc:`printf`\ -style *format* string and a variable number of
752-   arguments, calculate the size of the resulting Python string and return a string
753-   with the values formatted into it.  The variable arguments must be C types and
754-   must correspond exactly to the format characters in the *format* string.  The
755-   following format characters are allowed:
756- 
757-   .. % This should be exactly the same as the table in PyErr_Format.
758-   .. % One should just refer to the other.
759-   .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
760-   .. % because not all compilers support the %z width modifier -- we fake it
761-   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
762-   .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
763- 
764-   +-------------------+---------------+--------------------------------+
765-   | Format Characters | Type          | Comment                        |
766-   +===================+===============+================================+
767-   | :attr:`%%`        | *n/a*         | The literal % character.       |
768-   +-------------------+---------------+--------------------------------+
769-   | :attr:`%c`        | int           | A single character,            |
770-   |                   |               | represented as an C int.       |
771-   +-------------------+---------------+--------------------------------+
772-   | :attr:`%d`        | int           | Exactly equivalent to          |
773-   |                   |               | ``printf("%d")``.              |
774-   +-------------------+---------------+--------------------------------+
775-   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
776-   |                   |               | ``printf("%u")``.              |
777-   +-------------------+---------------+--------------------------------+
778-   | :attr:`%ld`       | long          | Exactly equivalent to          |
779-   |                   |               | ``printf("%ld")``.             |
780-   +-------------------+---------------+--------------------------------+
781-   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
782-   |                   |               | ``printf("%lu")``.             |
783-   +-------------------+---------------+--------------------------------+
784-   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
785-   |                   |               | ``printf("%zd")``.             |
786-   +-------------------+---------------+--------------------------------+
787-   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
788-   |                   |               | ``printf("%zu")``.             |
789-   +-------------------+---------------+--------------------------------+
790-   | :attr:`%i`        | int           | Exactly equivalent to          |
791-   |                   |               | ``printf("%i")``.              |
792-   +-------------------+---------------+--------------------------------+
793-   | :attr:`%x`        | int           | Exactly equivalent to          |
794-   |                   |               | ``printf("%x")``.              |
795-   +-------------------+---------------+--------------------------------+
796-   | :attr:`%s`        | char\*        | A null-terminated C character  |
797-   |                   |               | array.                         |
798-   +-------------------+---------------+--------------------------------+
799-   | :attr:`%p`        | void\*        | The hex representation of a C  |
800-   |                   |               | pointer. Mostly equivalent to  |
801-   |                   |               | ``printf("%p")`` except that   |
802-   |                   |               | it is guaranteed to start with |
803-   |                   |               | the literal ``0x`` regardless  |
804-   |                   |               | of what the platform's         |
805-   |                   |               | ``printf`` yields.             |
806-   +-------------------+---------------+--------------------------------+
807- 
808-   An unrecognized format character causes all the rest of the format string to be
809-   copied as-is to the result string, and any extra arguments discarded.
810- 
811- 
812-.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
813- 
814-   Identical to :func:`PyString_FromFormat` except that it takes exactly two
815-   arguments.
816- 
817- 
818-.. cfunction:: Py_ssize_t PyString_Size(PyObject *string)
819- 
820-   Return the length of the string in string object *string*.
821- 
822- 
823-.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
824- 
825-   Macro form of :cfunc:`PyString_Size` but without error checking.
826- 
827- 
828-.. cfunction:: char* PyString_AsString(PyObject *string)
829- 
830-   Return a NUL-terminated representation of the contents of *string*.  The pointer
831-   refers to the internal buffer of *string*, not a copy.  The data must not be
832-   modified in any way, unless the string was just created using
833-   ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
834-   *string* is a Unicode object, this function computes the default encoding of
835-   *string* and operates on that.  If *string* is not a string object at all,
836-   :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
837- 
838- 
839-.. cfunction:: char* PyString_AS_STRING(PyObject *string)
840- 
841-   Macro form of :cfunc:`PyString_AsString` but without error checking.  Only
842-   string objects are supported; no Unicode objects should be passed.
843- 
844- 
845-.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
846- 
847-   Return a NUL-terminated representation of the contents of the object *obj*
848-   through the output variables *buffer* and *length*.
849- 
850-   The function accepts both string and Unicode objects as input. For Unicode
851-   objects it returns the default encoded version of the object.  If *length* is
852-   *NULL*, the resulting buffer may not contain NUL characters; if it does, the
853-   function returns ``-1`` and a :exc:`TypeError` is raised.
854- 
855-   The buffer refers to an internal string buffer of *obj*, not a copy. The data
856-   must not be modified in any way, unless the string was just created using
857-   ``PyString_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
858-   *string* is a Unicode object, this function computes the default encoding of
859-   *string* and operates on that.  If *string* is not a string object at all,
860-   :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
861- 
862- 
863-.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
864- 
865-   Create a new string object in *\*string* containing the contents of *newpart*
866-   appended to *string*; the caller will own the new reference.  The reference to
867-   the old value of *string* will be stolen.  If the new string cannot be created,
868-   the old reference to *string* will still be discarded and the value of
869-   *\*string* will be set to *NULL*; the appropriate exception will be set.
870- 
871- 
872-.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
873- 
874-   Create a new string object in *\*string* containing the contents of *newpart*
875-   appended to *string*.  This version decrements the reference count of *newpart*.
876- 
877- 
878-.. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
879- 
880-   A way to resize a string object even though it is "immutable". Only use this to
881-   build up a brand new string object; don't use this if the string may already be
882-   known in other parts of the code.  It is an error to call this function if the
883-   refcount on the input string object is not one. Pass the address of an existing
884-   string object as an lvalue (it may be written into), and the new size desired.
885-   On success, *\*string* holds the resized string object and ``0`` is returned;
886-   the address in *\*string* may differ from its input value.  If the reallocation
887-   fails, the original string object at *\*string* is deallocated, *\*string* is
888-   set to *NULL*, a memory exception is set, and ``-1`` is returned.
889- 
890- 
891-.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
892- 
893-   Return a new string object from *format* and *args*. Analogous to ``format %
894-   args``.  The *args* argument must be a tuple.
895- 
896- 
897-.. cfunction:: void PyString_InternInPlace(PyObject **string)
898- 
899-   Intern the argument *\*string* in place.  The argument must be the address of a
900-   pointer variable pointing to a Python string object.  If there is an existing
901-   interned string that is the same as *\*string*, it sets *\*string* to it
902-   (decrementing the reference count of the old string object and incrementing the
903-   reference count of the interned string object), otherwise it leaves *\*string*
904-   alone and interns it (incrementing its reference count).  (Clarification: even
905-   though there is a lot of talk about reference counts, think of this function as
906-   reference-count-neutral; you own the object after the call if and only if you
907-   owned it before the call.)
908- 
909- 
910-.. cfunction:: PyObject* PyString_InternFromString(const char *v)
911- 
912-   A combination of :cfunc:`PyString_FromString` and
913-   :cfunc:`PyString_InternInPlace`, returning either a new string object that has
914-   been interned, or a new ("owned") reference to an earlier interned string object
915-   with the same value.
916- 
917- 
918-.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
919- 
920-   Create an object by decoding *size* bytes of the encoded buffer *s* using the
921-   codec registered for *encoding*.  *encoding* and *errors* have the same meaning
922-   as the parameters of the same name in the :func:`unicode` built-in function.
923-   The codec to be used is looked up using the Python codec registry.  Return
924-   *NULL* if an exception was raised by the codec.
925- 
926- 
927-.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
928- 
929-   Decode a string object by passing it to the codec registered for *encoding* and
930-   return the result as Python object. *encoding* and *errors* have the same
931-   meaning as the parameters of the same name in the string :meth:`encode` method.
932-   The codec to be used is looked up using the Python codec registry. Return *NULL*
933-   if an exception was raised by the codec.
934- 
935- 
936-.. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
937- 
938-   Encode the :ctype:`char` buffer of the given size by passing it to the codec
939-   registered for *encoding* and return a Python object. *encoding* and *errors*
940-   have the same meaning as the parameters of the same name in the string
941-   :meth:`encode` method. The codec to be used is looked up using the Python codec
942-   registry.  Return *NULL* if an exception was raised by the codec.
943- 
944- 
945-.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
946- 
947-   Encode a string object using the codec registered for *encoding* and return the
948-   result as Python object. *encoding* and *errors* have the same meaning as the
949-   parameters of the same name in the string :meth:`encode` method. The codec to be
950-   used is looked up using the Python codec registry. Return *NULL* if an exception
951-   was raised by the codec.
952- 
953- 
954-.. _unicodeobjects:
955- 
956-Unicode Objects
957----------------
958- 
959-.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
960- 
961- 
962-These are the basic Unicode object types used for the Unicode implementation in
963-Python:
964- 
965-.. % --- Unicode Type -------------------------------------------------------
966- 
967- 
968-.. ctype:: Py_UNICODE
969- 
970-   This type represents the storage type which is used by Python internally as
971-   basis for holding Unicode ordinals.  Python's default builds use a 16-bit type
972-   for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
973-   possible to build a UCS4 version of Python (most recent Linux distributions come
974-   with UCS4 builds of Python). These builds then use a 32-bit type for
975-   :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
976-   where :ctype:`wchar_t` is available and compatible with the chosen Python
977-   Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for
978-   :ctype:`wchar_t` to enhance native platform compatibility. On all other
979-   platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned
980-   short` (UCS2) or :ctype:`unsigned long` (UCS4).
981- 
982-Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
983-this in mind when writing extensions or interfaces.
984- 
985- 
986-.. ctype:: PyUnicodeObject
987- 
988-   This subtype of :ctype:`PyObject` represents a Python Unicode object.
989- 
990- 
991-.. cvar:: PyTypeObject PyUnicode_Type
992- 
993-   This instance of :ctype:`PyTypeObject` represents the Python Unicode type.  It
994-   is exposed to Python code as ``unicode`` and ``types.UnicodeType``.
995- 
996-The following APIs are really C macros and can be used to do fast checks and to
997-access internal read-only data of Unicode objects:
998- 
999- 
1000-.. cfunction:: int PyUnicode_Check(PyObject *o)
1001- 
1002-   Return true if the object *o* is a Unicode object or an instance of a Unicode
1003-   subtype.
1004- 
1005-   .. versionchanged:: 2.2
1006-      Allowed subtypes to be accepted.
1007- 
1008- 
1009-.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
1010- 
1011-   Return true if the object *o* is a Unicode object, but not an instance of a
1012-   subtype.
1013- 
1014-   .. versionadded:: 2.2
1015- 
1016- 
1017-.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
1018- 
1019-   Return the size of the object.  *o* has to be a :ctype:`PyUnicodeObject` (not
1020-   checked).
1021- 
1022- 
1023-.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
1024- 
1025-   Return the size of the object's internal buffer in bytes.  *o* has to be a
1026-   :ctype:`PyUnicodeObject` (not checked).
1027- 
1028- 
1029-.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
1030- 
1031-   Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object.  *o*
1032-   has to be a :ctype:`PyUnicodeObject` (not checked).
1033- 
1034- 
1035-.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)
1036- 
1037-   Return a pointer to the internal buffer of the object. *o* has to be a
1038-   :ctype:`PyUnicodeObject` (not checked).
1039- 
1040-Unicode provides many different character properties. The most often needed ones
1041-are available through these macros which are mapped to C functions depending on
1042-the Python configuration.
1043- 
1044-.. % --- Unicode character properties ---------------------------------------
1045- 
1046- 
1047-.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
1048- 
1049-   Return 1 or 0 depending on whether *ch* is a whitespace character.
1050- 
1051- 
1052-.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
1053- 
1054-   Return 1 or 0 depending on whether *ch* is a lowercase character.
1055- 
1056- 
1057-.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
1058- 
1059-   Return 1 or 0 depending on whether *ch* is an uppercase character.
1060- 
1061- 
1062-.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
1063- 
1064-   Return 1 or 0 depending on whether *ch* is a titlecase character.
1065- 
1066- 
1067-.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
1068- 
1069-   Return 1 or 0 depending on whether *ch* is a linebreak character.
1070- 
1071- 
1072-.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
1073- 
1074-   Return 1 or 0 depending on whether *ch* is a decimal character.
1075- 
1076- 
1077-.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
1078- 
1079-   Return 1 or 0 depending on whether *ch* is a digit character.
1080- 
1081- 
1082-.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
1083- 
1084-   Return 1 or 0 depending on whether *ch* is a numeric character.
1085- 
1086- 
1087-.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
1088- 
1089-   Return 1 or 0 depending on whether *ch* is an alphabetic character.
1090- 
1091- 
1092-.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
1093- 
1094-   Return 1 or 0 depending on whether *ch* is an alphanumeric character.
1095- 
1096-These APIs can be used for fast direct character conversions:
1097- 
1098- 
1099-.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
1100- 
1101-   Return the character *ch* converted to lower case.
1102- 
1103- 
1104-.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
1105- 
1106-   Return the character *ch* converted to upper case.
1107- 
1108- 
1109-.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
1110- 
1111-   Return the character *ch* converted to title case.
1112- 
1113- 
1114-.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
1115- 
1116-   Return the character *ch* converted to a decimal positive integer.  Return
1117-   ``-1`` if this is not possible.  This macro does not raise exceptions.
1118- 
1119- 
1120-.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
1121- 
1122-   Return the character *ch* converted to a single digit integer. Return ``-1`` if
1123-   this is not possible.  This macro does not raise exceptions.
1124- 
1125- 
1126-.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
1127- 
1128-   Return the character *ch* converted to a double. Return ``-1.0`` if this is not
1129-   possible.  This macro does not raise exceptions.
1130- 
1131-To create Unicode objects and access their basic sequence properties, use these
1132-APIs:
1133- 
1134-.. % --- Plain Py_UNICODE ---------------------------------------------------
1135- 
1136- 
1137-.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
1138- 
1139-   Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u*
1140-   may be *NULL* which causes the contents to be undefined. It is the user's
1141-   responsibility to fill in the needed data.  The buffer is copied into the new
1142-   object. If the buffer is not *NULL*, the return value might be a shared object.
1143-   Therefore, modification of the resulting Unicode object is only allowed when *u*
1144-   is *NULL*.
1145- 
1146- 
1147-.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
1148- 
1149-   Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`
1150-   buffer, *NULL* if *unicode* is not a Unicode object.
1151- 
1152- 
1153-.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
1154- 
1155-   Return the length of the Unicode object.
1156- 
1157- 
1158-.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
1159- 
1160-   Coerce an encoded object *obj* to an Unicode object and return a reference with
1161-   incremented refcount.
1162- 
1163-   String and other char buffer compatible objects are decoded according to the
1164-   given encoding and using the error handling defined by errors.  Both can be
1165-   *NULL* to have the interface use the default values (see the next section for
1166-   details).
1167- 
1168-   All other objects, including Unicode objects, cause a :exc:`TypeError` to be
1169-   set.
1170- 
1171-   The API returns *NULL* if there was an error.  The caller is responsible for
1172-   decref'ing the returned objects.
1173- 
1174- 
1175-.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)
1176- 
1177-   Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
1178-   throughout the interpreter whenever coercion to Unicode is needed.
1179- 
1180-If the platform supports :ctype:`wchar_t` and provides a header file wchar.h,
1181-Python can interface directly to this type using the following functions.
1182-Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to
1183-the system's :ctype:`wchar_t`.
1184- 
1185-.. % --- wchar_t support for platforms which support it ---------------------
1186- 
1187- 
1188-.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
1189- 
1190-   Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size.
1191-   Return *NULL* on failure.
1192- 
1193- 
1194-.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
1195- 
1196-   Copy the Unicode object contents into the :ctype:`wchar_t` buffer *w*.  At most
1197-   *size* :ctype:`wchar_t` characters are copied (excluding a possibly trailing
1198-   0-termination character).  Return the number of :ctype:`wchar_t` characters
1199-   copied or -1 in case of an error.  Note that the resulting :ctype:`wchar_t`
1200-   string may or may not be 0-terminated.  It is the responsibility of the caller
1201-   to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is
1202-   required by the application.
1203- 
1204- 
1205-.. _builtincodecs:
1206- 
1207-Built-in Codecs
1208-^^^^^^^^^^^^^^^
1209- 
1210-Python provides a set of builtin codecs which are written in C for speed. All of
1211-these codecs are directly usable via the following functions.
1212- 
1213-Many of the following APIs take two arguments encoding and errors. These
1214-parameters encoding and errors have the same semantics as the ones of the
1215-builtin unicode() Unicode object constructor.
1216- 
1217-Setting encoding to *NULL* causes the default encoding to be used which is
1218-ASCII.  The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`
1219-as the encoding for file names. This variable should be treated as read-only: On
1220-some systems, it will be a pointer to a static string, on others, it will change
1221-at run-time (such as when the application invokes setlocale).
1222- 
1223-Error handling is set by errors which may also be set to *NULL* meaning to use
1224-the default handling defined for the codec.  Default error handling for all
1225-builtin codecs is "strict" (:exc:`ValueError` is raised).
1226- 
1227-The codecs all use a similar interface.  Only deviation from the following
1228-generic ones are documented for simplicity.
1229- 
1230-These are the generic codec APIs:
1231- 
1232-.. % --- Generic Codecs -----------------------------------------------------
1233- 
1234- 
1235-.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
1236- 
1237-   Create a Unicode object by decoding *size* bytes of the encoded string *s*.
1238-   *encoding* and *errors* have the same meaning as the parameters of the same name
1239-   in the :func:`unicode` builtin function.  The codec to be used is looked up
1240-   using the Python codec registry.  Return *NULL* if an exception was raised by
1241-   the codec.
1242- 
1243- 
1244-.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
1245- 
1246-   Encode the :ctype:`Py_UNICODE` buffer of the given size and return a Python
1247-   string object.  *encoding* and *errors* have the same meaning as the parameters
1248-   of the same name in the Unicode :meth:`encode` method.  The codec to be used is
1249-   looked up using the Python codec registry.  Return *NULL* if an exception was
1250-   raised by the codec.
1251- 
1252- 
1253-.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
1254- 
1255-   Encode a Unicode object and return the result as Python string object.
1256-   *encoding* and *errors* have the same meaning as the parameters of the same name
1257-   in the Unicode :meth:`encode` method. The codec to be used is looked up using
1258-   the Python codec registry. Return *NULL* if an exception was raised by the
1259-   codec.
1260- 
1261-These are the UTF-8 codec APIs:
1262- 
1263-.. % --- UTF-8 Codecs -------------------------------------------------------
1264- 
1265- 
1266-.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
1267- 
1268-   Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
1269-   *s*. Return *NULL* if an exception was raised by the codec.
1270- 
1271- 
1272-.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
1273- 
1274-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If
1275-   *consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be
1276-   treated as an error. Those bytes will not be decoded and the number of bytes
1277-   that have been decoded will be stored in *consumed*.
1278- 
1279-   .. versionadded:: 2.4
1280- 
1281- 
1282-.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
1283- 
1284-   Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and return a
1285-   Python string object.  Return *NULL* if an exception was raised by the codec.
1286- 
1287- 
1288-.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
1289- 
1290-   Encode a Unicode objects using UTF-8 and return the result as Python string
1291-   object.  Error handling is "strict".  Return *NULL* if an exception was raised
1292-   by the codec.
1293- 
1294-These are the UTF-16 codec APIs:
1295- 
1296-.. % --- UTF-16 Codecs ------------------------------------------------------ */
1297- 
1298- 
1299-.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
1300- 
1301-   Decode *length* bytes from a UTF-16 encoded buffer string and return the
1302-   corresponding Unicode object.  *errors* (if non-*NULL*) defines the error
1303-   handling. It defaults to "strict".
1304- 
1305-   If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
1306-   order::
1307- 
1308-      *byteorder == -1: little endian
1309-      *byteorder == 0:  native order
1310-      *byteorder == 1:  big endian
1311- 
1312-   and then switches according to all byte order marks (BOM) it finds in the input
1313-   data.  BOMs are not copied into the resulting Unicode string.  After completion,
1314-   *\*byteorder* is set to the current byte order at the end of input data.
1315- 
1316-   If *byteorder* is *NULL*, the codec starts in native order mode.
1317- 
1318-   Return *NULL* if an exception was raised by the codec.
1319- 
1320- 
1321-.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
1322- 
1323-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If
1324-   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat
1325-   trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
1326-   split surrogate pair) as an error. Those bytes will not be decoded and the
1327-   number of bytes that have been decoded will be stored in *consumed*.
1328- 
1329-   .. versionadded:: 2.4
1330- 
1331- 
1332-.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
1333- 
1334-   Return a Python string object holding the UTF-16 encoded value of the Unicode
1335-   data in *s*.  If *byteorder* is not ``0``, output is written according to the
1336-   following byte order::
1337- 
1338-      byteorder == -1: little endian
1339-      byteorder == 0:  native byte order (writes a BOM mark)
1340-      byteorder == 1:  big endian
1341- 
1342-   If byteorder is ``0``, the output string will always start with the Unicode BOM
1343-   mark (U+FEFF). In the other two modes, no BOM mark is prepended.
1344- 
1345-   If *Py_UNICODE_WIDE* is defined, a single :ctype:`Py_UNICODE` value may get
1346-   represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE`
1347-   values is interpreted as an UCS-2 character.
1348- 
1349-   Return *NULL* if an exception was raised by the codec.
1350- 
1351- 
1352-.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
1353- 
1354-   Return a Python string using the UTF-16 encoding in native byte order. The
1355-   string always starts with a BOM mark.  Error handling is "strict".  Return
1356-   *NULL* if an exception was raised by the codec.
1357- 
1358-These are the "Unicode Escape" codec APIs:
1359- 
1360-.. % --- Unicode-Escape Codecs ----------------------------------------------
1361- 
1362- 
1363-.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
1364- 
1365-   Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
1366-   string *s*.  Return *NULL* if an exception was raised by the codec.
1367- 
1368- 
1369-.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
1370- 
1371-   Encode the :ctype:`Py_UNICODE` buffer of the given size using Unicode-Escape and
1372-   return a Python string object.  Return *NULL* if an exception was raised by the
1373-   codec.
1374- 
1375- 
1376-.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
1377- 
1378-   Encode a Unicode objects using Unicode-Escape and return the result as Python
1379-   string object.  Error handling is "strict". Return *NULL* if an exception was
1380-   raised by the codec.
1381- 
1382-These are the "Raw Unicode Escape" codec APIs:
1383- 
1384-.. % --- Raw-Unicode-Escape Codecs ------------------------------------------
1385- 
1386- 
1387-.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
1388- 
1389-   Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
1390-   encoded string *s*.  Return *NULL* if an exception was raised by the codec.
1391- 
1392- 
1393-.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
1394- 
1395-   Encode the :ctype:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape
1396-   and return a Python string object.  Return *NULL* if an exception was raised by
1397-   the codec.
1398- 
1399- 
1400-.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
1401- 
1402-   Encode a Unicode objects using Raw-Unicode-Escape and return the result as
1403-   Python string object. Error handling is "strict". Return *NULL* if an exception
1404-   was raised by the codec.
1405- 
1406-These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode
1407-ordinals and only these are accepted by the codecs during encoding.
1408- 
1409-.. % --- Latin-1 Codecs -----------------------------------------------------
1410- 
1411- 
1412-.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
1413- 
1414-   Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
1415-   *s*.  Return *NULL* if an exception was raised by the codec.
1416- 
1417- 
1418-.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
1419- 
1420-   Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and return
1421-   a Python string object.  Return *NULL* if an exception was raised by the codec.
1422- 
1423- 
1424-.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
1425- 
1426-   Encode a Unicode objects using Latin-1 and return the result as Python string
1427-   object.  Error handling is "strict".  Return *NULL* if an exception was raised
1428-   by the codec.
1429- 
1430-These are the ASCII codec APIs.  Only 7-bit ASCII data is accepted. All other
1431-codes generate errors.
1432- 
1433-.. % --- ASCII Codecs -------------------------------------------------------
1434- 
1435- 
1436-.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
1437- 
1438-   Create a Unicode object by decoding *size* bytes of the ASCII encoded string
1439-   *s*.  Return *NULL* if an exception was raised by the codec.
1440- 
1441- 
1442-.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
1443- 
1444-   Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and return a
1445-   Python string object.  Return *NULL* if an exception was raised by the codec.
1446- 
1447- 
1448-.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
1449- 
1450-   Encode a Unicode objects using ASCII and return the result as Python string
1451-   object.  Error handling is "strict".  Return *NULL* if an exception was raised
1452-   by the codec.
1453- 
1454-These are the mapping codec APIs:
1455- 
1456-.. % --- Character Map Codecs -----------------------------------------------
1457- 
1458-This codec is special in that it can be used to implement many different codecs
1459-(and this is in fact what was done to obtain most of the standard codecs
1460-included in the :mod:`encodings` package). The codec uses mapping to encode and
1461-decode characters.
1462- 
1463-Decoding mappings must map single string characters to single Unicode
1464-characters, integers (which are then interpreted as Unicode ordinals) or None
1465-(meaning "undefined mapping" and causing an error).
1466- 
1467-Encoding mappings must map single Unicode characters to single string
1468-characters, integers (which are then interpreted as Latin-1 ordinals) or None
1469-(meaning "undefined mapping" and causing an error).
1470- 
1471-The mapping objects provided must only support the __getitem__ mapping
1472-interface.
1473- 
1474-If a character lookup fails with a LookupError, the character is copied as-is
1475-meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal
1476-resp. Because of this, mappings only need to contain those mappings which map
1477-characters to different code points.
1478- 
1479- 
1480-.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
1481- 
1482-   Create a Unicode object by decoding *size* bytes of the encoded string *s* using
1483-   the given *mapping* object.  Return *NULL* if an exception was raised by the
1484-   codec. If *mapping* is *NULL* latin-1 decoding will be done. Else it can be a
1485-   dictionary mapping byte or a unicode string, which is treated as a lookup table.
1486-   Byte values greater that the length of the string and U+FFFE "characters" are
1487-   treated as "undefined mapping".
1488- 
1489-   .. versionchanged:: 2.4
1490-      Allowed unicode string as mapping argument.
1491- 
1492- 
1493-.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
1494- 
1495-   Encode the :ctype:`Py_UNICODE` buffer of the given size using the given
1496-   *mapping* object and return a Python string object. Return *NULL* if an
1497-   exception was raised by the codec.
1498- 
1499- 
1500-.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
1501- 
1502-   Encode a Unicode objects using the given *mapping* object and return the result
1503-   as Python string object.  Error handling is "strict".  Return *NULL* if an
1504-   exception was raised by the codec.
1505- 
1506-The following codec API is special in that maps Unicode to Unicode.
1507- 
1508- 
1509-.. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
1510- 
1511-   Translate a :ctype:`Py_UNICODE` buffer of the given length by applying a
1512-   character mapping *table* to it and return the resulting Unicode object.  Return
1513-   *NULL* when an exception was raised by the codec.
1514- 
1515-   The *mapping* table must map Unicode ordinal integers to Unicode ordinal
1516-   integers or None (causing deletion of the character).
1517- 
1518-   Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
1519-   and sequences work well.  Unmapped character ordinals (ones which cause a
1520-   :exc:`LookupError`) are left untouched and are copied as-is.
1521- 
1522-These are the MBCS codec APIs. They are currently only available on Windows and
1523-use the Win32 MBCS converters to implement the conversions.  Note that MBCS (or
1524-DBCS) is a class of encodings, not just one.  The target encoding is defined by
1525-the user settings on the machine running the codec.
1526- 
1527-.. % --- MBCS codecs for Windows --------------------------------------------
1528- 
1529- 
1530-.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
1531- 
1532-   Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
1533-   Return *NULL* if an exception was raised by the codec.
1534- 
1535- 
1536-.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
1537- 
1538-   If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If
1539-   *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode
1540-   trailing lead byte and the number of bytes that have been decoded will be stored
1541-   in *consumed*.
1542- 
1543-   .. versionadded:: 2.5
1544- 
1545- 
1546-.. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
1547- 
1548-   Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return a
1549-   Python string object.  Return *NULL* if an exception was raised by the codec.
1550- 
1551- 
1552-.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
1553- 
1554-   Encode a Unicode objects using MBCS and return the result as Python string
1555-   object.  Error handling is "strict".  Return *NULL* if an exception was raised
1556-   by the codec.
1557- 
1558-.. % --- Methods & Slots ----------------------------------------------------
1559- 
1560- 
1561-.. _unicodemethodsandslots:
1562- 
1563-Methods and Slot Functions
1564-^^^^^^^^^^^^^^^^^^^^^^^^^^
1565- 
1566-The following APIs are capable of handling Unicode objects and strings on input
1567-(we refer to them as strings in the descriptions) and return Unicode objects or
1568-integers as appropriate.
1569- 
1570-They all return *NULL* or ``-1`` if an exception occurs.
1571- 
1572- 
1573-.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
1574- 
1575-   Concat two strings giving a new Unicode string.
1576- 
1577- 
1578-.. cfunction:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
1579- 
1580-   Split a string giving a list of Unicode strings.  If sep is *NULL*, splitting
1581-   will be done at all whitespace substrings.  Otherwise, splits occur at the given
1582-   separator.  At most *maxsplit* splits will be done.  If negative, no limit is
1583-   set.  Separators are not included in the resulting list.
1584- 
1585- 
1586-.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
1587- 
1588-   Split a Unicode string at line breaks, returning a list of Unicode strings.
1589-   CRLF is considered to be one line break.  If *keepend* is 0, the Line break
1590-   characters are not included in the resulting strings.
1591- 
1592- 
1593-.. cfunction:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
1594- 
1595-   Translate a string by applying a character mapping table to it and return the
1596-   resulting Unicode object.
1597- 
1598-   The mapping table must map Unicode ordinal integers to Unicode ordinal integers
1599-   or None (causing deletion of the character).
1600- 
1601-   Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
1602-   and sequences work well.  Unmapped character ordinals (ones which cause a
1603-   :exc:`LookupError`) are left untouched and are copied as-is.
1604- 
1605-   *errors* has the usual meaning for codecs. It may be *NULL* which indicates to
1606-   use the default error handling.
1607- 
1608- 
1609-.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
1610- 
1611-   Join a sequence of strings using the given separator and return the resulting
1612-   Unicode string.
1613- 
1614- 
1615-.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
1616- 
1617-   Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end
1618-   (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
1619-   0 otherwise. Return ``-1`` if an error occurred.
1620- 
1621- 
1622-.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
1623- 
1624-   Return the first position of *substr* in *str*[*start*:*end*] using the given
1625-   *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
1626-   backward search).  The return value is the index of the first match; a value of
1627-   ``-1`` indicates that no match was found, and ``-2`` indicates that an error
1628-   occurred and an exception has been set.
1629- 
1630- 
1631-.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
1632- 
1633-   Return the number of non-overlapping occurrences of *substr* in
1634-   ``str[start:end]``.  Return ``-1`` if an error occurred.
1635- 
1636- 
1637-.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
1638- 
1639-   Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
1640-   return the resulting Unicode object. *maxcount* == -1 means replace all
1641-   occurrences.
1642- 
1643- 
1644-.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)
1645- 
1646-   Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
1647-   respectively.
1648- 
1649- 
1650-.. cfunction:: int PyUnicode_RichCompare(PyObject *left,  PyObject *right,  int op)
1651- 
1652-   Rich compare two unicode strings and return one of the following:
1653- 
1654-* ``NULL`` in case an exception was raised
1655- 
1656-* :const:`Py_True` or :const:`Py_False` for successful comparisons
1657- 
1658-* :const:`Py_NotImplemented` in case the type combination is unknown
1659- 
1660-   Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a
1661-   :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails
1662-   with a :exc:`UnicodeDecodeError`.
1663- 
1664-   Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
1665-   :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
1666- 
1667- 
1668-.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
1669- 
1670-   Return a new string object from *format* and *args*; this is analogous to
1671-   ``format % args``.  The *args* argument must be a tuple.
1672- 
1673- 
1674-.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element)
1675- 
1676-   Check whether *element* is contained in *container* and return true or false
1677-   accordingly.
1678- 
1679-   *element* has to coerce to a one element Unicode string. ``-1`` is returned if
1680-   there was an error.
1681- 
1682- 
1683-.. _bufferobjects:
1684- 
1685-Buffer Objects
1686---------------
1687- 
1688-.. sectionauthor:: Greg Stein <gstein@lyra.org>
1689- 
1690- 
1691-.. index::
1692-   object: buffer
1693-   single: buffer interface
1694- 
1695-Python objects implemented in C can export a group of functions called the
1696-"buffer interface."  These functions can be used by an object to expose its data
1697-in a raw, byte-oriented format. Clients of the object can use the buffer
1698-interface to access the object data directly, without needing to copy it first.
1699- 
1700-Two examples of objects that support the buffer interface are strings and
1701-arrays. The string object exposes the character contents in the buffer
1702-interface's byte-oriented form. An array can also expose its contents, but it
1703-should be noted that array elements may be multi-byte values.
1704- 
1705-An example user of the buffer interface is the file object's :meth:`write`
1706-method. Any object that can export a series of bytes through the buffer
1707-interface can be written to a file. There are a number of format codes to
1708-:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
1709-returning data from the target object.
1710- 
1711-.. index:: single: PyBufferProcs
1712- 
1713-More information on the buffer interface is provided in the section "Buffer
1714-Object Structures" (section :ref:`buffer-structs`), under the description for
1715-:ctype:`PyBufferProcs`.
1716- 
1717-A "buffer object" is defined in the :file:`bufferobject.h` header (included by
1718-:file:`Python.h`). These objects look very similar to string objects at the
1719-Python programming level: they support slicing, indexing, concatenation, and
1720-some other standard string operations. However, their data can come from one of
1721-two sources: from a block of memory, or from another object which exports the
1722-buffer interface.
1723- 
1724-Buffer objects are useful as a way to expose the data from another object's
1725-buffer interface to the Python programmer. They can also be used as a zero-copy
1726-slicing mechanism. Using their ability to reference a block of memory, it is
1727-possible to expose any data to the Python programmer quite easily. The memory
1728-could be a large, constant array in a C extension, it could be a raw block of
1729-memory for manipulation before passing to an operating system library, or it
1730-could be used to pass around structured data in its native, in-memory format.
1731- 
1732- 
1733-.. ctype:: PyBufferObject
1734- 
1735-   This subtype of :ctype:`PyObject` represents a buffer object.
1736- 
1737- 
1738-.. cvar:: PyTypeObject PyBuffer_Type
1739- 
1740-   .. index:: single: BufferType (in module types)
1741- 
1742-   The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
1743-   it is the same object as ``buffer`` and  ``types.BufferType`` in the Python
1744-   layer. .
1745- 
1746- 
1747-.. cvar:: int Py_END_OF_BUFFER
1748- 
1749-   This constant may be passed as the *size* parameter to
1750-   :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`.  It
1751-   indicates that the new :ctype:`PyBufferObject` should refer to *base* object
1752-   from the specified *offset* to the end of its exported buffer.  Using this
1753-   enables the caller to avoid querying the *base* object for its length.
1754- 
1755- 
1756-.. cfunction:: int PyBuffer_Check(PyObject *p)
1757- 
1758-   Return true if the argument has type :cdata:`PyBuffer_Type`.
1759- 
1760- 
1761-.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
1762- 
1763-   Return a new read-only buffer object.  This raises :exc:`TypeError` if *base*
1764-   doesn't support the read-only buffer protocol or doesn't provide exactly one
1765-   buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero.
1766-   The buffer will hold a reference to the *base* object, and the buffer's contents
1767-   will refer to the *base* object's buffer interface, starting as position
1768-   *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,
1769-   then the new buffer's contents extend to the length of the *base* object's
1770-   exported buffer data.
1771- 
1772- 
1773-.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
1774- 
1775-   Return a new writable buffer object.  Parameters and exceptions are similar to
1776-   those for :cfunc:`PyBuffer_FromObject`.  If the *base* object does not export
1777-   the writeable buffer protocol, then :exc:`TypeError` is raised.
1778- 
1779- 
1780-.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
1781- 
1782-   Return a new read-only buffer object that reads from a specified location in
1783-   memory, with a specified size.  The caller is responsible for ensuring that the
1784-   memory buffer, passed in as *ptr*, is not deallocated while the returned buffer
1785-   object exists.  Raises :exc:`ValueError` if *size* is less than zero.  Note that
1786-   :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
1787-   :exc:`ValueError` will be raised in that case.
1788- 
1789- 
1790-.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
1791- 
1792-   Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
1793- 
1794- 
1795-.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
1796- 
1797-   Return a new writable buffer object that maintains its own memory buffer of
1798-   *size* bytes.  :exc:`ValueError` is returned if *size* is not zero or positive.
1799-   Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
1800-   not specifically aligned.
1801- 
1802- 
1803-.. _tupleobjects:
1804- 
1805-Tuple Objects
1806--------------
1807- 
1808-.. index:: object: tuple
1809- 
1810- 
1811-.. ctype:: PyTupleObject
1812- 
1813-   This subtype of :ctype:`PyObject` represents a Python tuple object.
1814- 
1815- 
1816-.. cvar:: PyTypeObject PyTuple_Type
1817- 
1818-   .. index:: single: TupleType (in module types)
1819- 
1820-   This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
1821-   the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
1822- 
1823- 
1824-.. cfunction:: int PyTuple_Check(PyObject *p)
1825- 
1826-   Return true if *p* is a tuple object or an instance of a subtype of the tuple
1827-   type.
1828- 
1829-   .. versionchanged:: 2.2
1830-      Allowed subtypes to be accepted.
1831- 
1832- 
1833-.. cfunction:: int PyTuple_CheckExact(PyObject *p)
1834- 
1835-   Return true if *p* is a tuple object, but not an instance of a subtype of the
1836-   tuple type.
1837- 
1838-   .. versionadded:: 2.2
1839- 
1840- 
1841-.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len)
1842- 
1843-   Return a new tuple object of size *len*, or *NULL* on failure.
1844- 
1845- 
1846-.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
1847- 
1848-   Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
1849-   are initialized to the subsequent *n* C arguments pointing to Python objects.
1850-   ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
1851- 
1852-   .. versionadded:: 2.4
1853- 
1854- 
1855-.. cfunction:: int PyTuple_Size(PyObject *p)
1856- 
1857-   Take a pointer to a tuple object, and return the size of that tuple.
1858- 
1859- 
1860-.. cfunction:: int PyTuple_GET_SIZE(PyObject *p)
1861- 
1862-   Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
1863-   no error checking is performed.
1864- 
1865- 
1866-.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
1867- 
1868-   Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
1869-   out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
1870- 
1871- 
1872-.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
1873- 
1874-   Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
1875- 
1876- 
1877-.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
1878- 
1879-   Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
1880-   as a new tuple.
1881- 
1882- 
1883-.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
1884- 
1885-   Insert a reference to object *o* at position *pos* of the tuple pointed to by
1886-   *p*. Return ``0`` on success.
1887- 
1888-   .. note::
1889- 
1890-      This function "steals" a reference to *o*.
1891- 
1892- 
1893-.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
1894- 
1895-   Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be
1896-   used to fill in brand new tuples.
1897- 
1898-   .. note::
1899- 
1900-      This function "steals" a reference to *o*.
1901- 
1902- 
1903-.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
1904- 
1905-   Can be used to resize a tuple.  *newsize* will be the new length of the tuple.
1906-   Because tuples are *supposed* to be immutable, this should only be used if there
1907-   is only one reference to the object.  Do *not* use this if the tuple may already
1908-   be known to some other part of the code.  The tuple will always grow or shrink
1909-   at the end.  Think of this as destroying the old tuple and creating a new one,
1910-   only more efficiently.  Returns ``0`` on success. Client code should never
1911-   assume that the resulting value of ``*p`` will be the same as before calling
1912-   this function. If the object referenced by ``*p`` is replaced, the original
1913-   ``*p`` is destroyed.  On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
1914-   raises :exc:`MemoryError` or :exc:`SystemError`.
1915- 
1916-   .. versionchanged:: 2.2
1917-      Removed unused third parameter, *last_is_sticky*.
1918- 
1919- 
1920-.. _listobjects:
1921- 
1922-List Objects
1923-------------
1924- 
1925-.. index:: object: list
1926- 
1927- 
1928-.. ctype:: PyListObject
1929- 
1930-   This subtype of :ctype:`PyObject` represents a Python list object.
1931- 
1932- 
1933-.. cvar:: PyTypeObject PyList_Type
1934- 
1935-   .. index:: single: ListType (in module types)
1936- 
1937-   This instance of :ctype:`PyTypeObject` represents the Python list type.  This is
1938-   the same object as ``list`` and ``types.ListType`` in the Python layer.
1939- 
1940- 
1941-.. cfunction:: int PyList_Check(PyObject *p)
1942- 
1943-   Return true if *p* is a list object or an instance of a subtype of the list
1944-   type.
1945- 
1946-   .. versionchanged:: 2.2
1947-      Allowed subtypes to be accepted.
1948- 
1949- 
1950-.. cfunction:: int PyList_CheckExact(PyObject *p)
1951- 
1952-   Return true if *p* is a list object, but not an instance of a subtype of the
1953-   list type.
1954- 
1955-   .. versionadded:: 2.2
1956- 
1957- 
1958-.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
1959- 
1960-   Return a new list of length *len* on success, or *NULL* on failure.
1961- 
1962-   .. note::
1963- 
1964-      If *length* is greater than zero, the returned list object's items are set to
1965-      ``NULL``.  Thus you cannot use abstract API functions such as
1966-      :cfunc:`PySequence_SetItem`  or expose the object to Python code before setting
1967-      all items to a real object with :cfunc:`PyList_SetItem`.
1968- 
1969- 
1970-.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
1971- 
1972-   .. index:: builtin: len
1973- 
1974-   Return the length of the list object in *list*; this is equivalent to
1975-   ``len(list)`` on a list object.
1976- 
1977- 
1978-.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
1979- 
1980-   Macro form of :cfunc:`PyList_Size` without error checking.
1981- 
1982- 
1983-.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
1984- 
1985-   Return the object at position *pos* in the list pointed to by *p*.  The position
1986-   must be positive, indexing from the end of the list is not supported.  If *pos*
1987-   is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
1988- 
1989- 
1990-.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
1991- 
1992-   Macro form of :cfunc:`PyList_GetItem` without error checking.
1993- 
1994- 
1995-.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
1996- 
1997-   Set the item at index *index* in list to *item*.  Return ``0`` on success or
1998-   ``-1`` on failure.
1999- 
2000-   .. note::
2001- 
2002-      This function "steals" a reference to *item* and discards a reference to an item
2003-      already in the list at the affected position.
2004- 
2005- 
2006-.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
2007- 
2008-   Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally
2009-   only used to fill in new lists where there is no previous content.
2010- 
2011-   .. note::
2012- 
2013-      This function "steals" a reference to *item*, and, unlike
2014-      :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
2015-      being replaced; any reference in *list* at position *i* will be leaked.
2016- 
2017- 
2018-.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
2019- 
2020-   Insert the item *item* into list *list* in front of index *index*.  Return ``0``
2021-   if successful; return ``-1`` and set an exception if unsuccessful.  Analogous to
2022-   ``list.insert(index, item)``.
2023- 
2024- 
2025-.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
2026- 
2027-   Append the object *item* at the end of list *list*. Return ``0`` if successful;
2028-   return ``-1`` and set an exception if unsuccessful.  Analogous to
2029-   ``list.append(item)``.
2030- 
2031- 
2032-.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
2033- 
2034-   Return a list of the objects in *list* containing the objects *between* *low*
2035-   and *high*.  Return *NULL* and set an exception if unsuccessful. Analogous to
2036-   ``list[low:high]``.
2037- 
2038- 
2039-.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
2040- 
2041-   Set the slice of *list* between *low* and *high* to the contents of *itemlist*.
2042-   Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*,
2043-   indicating the assignment of an empty list (slice deletion). Return ``0`` on
2044-   success, ``-1`` on failure.
2045- 
2046- 
2047-.. cfunction:: int PyList_Sort(PyObject *list)
2048- 
2049-   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on failure.
2050-   This is equivalent to ``list.sort()``.
2051- 
2052- 
2053-.. cfunction:: int PyList_Reverse(PyObject *list)
2054- 
2055-   Reverse the items of *list* in place.  Return ``0`` on success, ``-1`` on
2056-   failure.  This is the equivalent of ``list.reverse()``.
2057- 
2058- 
2059-.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
2060- 
2061-   .. index:: builtin: tuple
2062- 
2063-   Return a new tuple object containing the contents of *list*; equivalent to
2064-   ``tuple(list)``.
2065
2066
2067.. _mapobjects:
2068
2069Mapping Objects
2070===============
2071
2072.. index:: object: mapping
2073
n82+.. toctree::
2074
n2075-.. _dictobjects:
n84+   dict.rst
2076- 
2077-Dictionary Objects
2078-------------------
2079- 
2080-.. index:: object: dictionary
2081- 
2082- 
2083-.. ctype:: PyDictObject
2084- 
2085-   This subtype of :ctype:`PyObject` represents a Python dictionary object.
2086- 
2087- 
2088-.. cvar:: PyTypeObject PyDict_Type
2089- 
2090-   .. index::
2091-      single: DictType (in module types)
2092-      single: DictionaryType (in module types)
2093- 
2094-   This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
2095-   This is exposed to Python programs as ``dict`` and ``types.DictType``.
2096- 
2097- 
2098-.. cfunction:: int PyDict_Check(PyObject *p)
2099- 
2100-   Return true if *p* is a dict object or an instance of a subtype of the dict
2101-   type.
2102- 
2103-   .. versionchanged:: 2.2
2104-      Allowed subtypes to be accepted.
2105- 
2106- 
2107-.. cfunction:: int PyDict_CheckExact(PyObject *p)
2108- 
2109-   Return true if *p* is a dict object, but not an instance of a subtype of the
2110-   dict type.
2111- 
2112-   .. versionadded:: 2.4
2113- 
2114- 
2115-.. cfunction:: PyObject* PyDict_New()
2116- 
2117-   Return a new empty dictionary, or *NULL* on failure.
2118- 
2119- 
2120-.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)
2121- 
2122-   Return a proxy object for a mapping which enforces read-only behavior.  This is
2123-   normally used to create a proxy to prevent modification of the dictionary for
2124-   non-dynamic class types.
2125- 
2126-   .. versionadded:: 2.2
2127- 
2128- 
2129-.. cfunction:: void PyDict_Clear(PyObject *p)
2130- 
2131-   Empty an existing dictionary of all key-value pairs.
2132- 
2133- 
2134-.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
2135- 
2136-   Determine if dictionary *p* contains *key*.  If an item in *p* is matches *key*,
2137-   return ``1``, otherwise return ``0``.  On error, return ``-1``.  This is
2138-   equivalent to the Python expression ``key in p``.
2139- 
2140-   .. versionadded:: 2.4
2141- 
2142- 
2143-.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
2144- 
2145-   Return a new dictionary that contains the same key-value pairs as *p*.
2146- 
2147-   .. versionadded:: 1.6
2148- 
2149- 
2150-.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
2151- 
2152-   Insert *value* into the dictionary *p* with a key of *key*.  *key* must be
2153-   hashable; if it isn't, :exc:`TypeError` will be raised. Return ``0`` on success
2154-   or ``-1`` on failure.
2155- 
2156- 
2157-.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
2158- 
2159-   .. index:: single: PyString_FromString()
2160- 
2161-   Insert *value* into the dictionary *p* using *key* as a key. *key* should be a
2162-   :ctype:`char\*`.  The key object is created using ``PyString_FromString(key)``.
2163-   Return ``0`` on success or ``-1`` on failure.
2164- 
2165- 
2166-.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
2167- 
2168-   Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it
2169-   isn't, :exc:`TypeError` is raised.  Return ``0`` on success or ``-1`` on
2170-   failure.
2171- 
2172- 
2173-.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
2174- 
2175-   Remove the entry in dictionary *p* which has a key specified by the string
2176-   *key*.  Return ``0`` on success or ``-1`` on failure.
2177- 
2178- 
2179-.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
2180- 
2181-   Return the object from dictionary *p* which has a key *key*.  Return *NULL* if
2182-   the key *key* is not present, but *without* setting an exception.
2183- 
2184- 
2185-.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
2186- 
2187-   This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a
2188-   :ctype:`char\*`, rather than a :ctype:`PyObject\*`.
2189- 
2190- 
2191-.. cfunction:: PyObject* PyDict_Items(PyObject *p)
2192- 
2193-   Return a :ctype:`PyListObject` containing all the items from the dictionary, as
2194-   in the dictionary method :meth:`items` (see the Python Library Reference (XXX
2195-   reference: ../lib/lib.html)).
2196- 
2197- 
2198-.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
2199- 
2200-   Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
2201-   in the dictionary method :meth:`keys` (see the Python Library Reference (XXX
2202-   reference: ../lib/lib.html)).
2203- 
2204- 
2205-.. cfunction:: PyObject* PyDict_Values(PyObject *p)
2206- 
2207-   Return a :ctype:`PyListObject` containing all the values from the dictionary
2208-   *p*, as in the dictionary method :meth:`values` (see the Python Library
2209-   Reference (XXX reference: ../lib/lib.html)).
2210- 
2211- 
2212-.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
2213- 
2214-   .. index:: builtin: len
2215- 
2216-   Return the number of items in the dictionary.  This is equivalent to ``len(p)``
2217-   on a dictionary.
2218- 
2219- 
2220-.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
2221- 
2222-   Iterate over all key-value pairs in the dictionary *p*.  The :ctype:`int`
2223-   referred to by *ppos* must be initialized to ``0`` prior to the first call to
2224-   this function to start the iteration; the function returns true for each pair in
2225-   the dictionary, and false once all pairs have been reported.  The parameters
2226-   *pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that
2227-   will be filled in with each key and value, respectively, or may be *NULL*.  Any
2228-   references returned through them are borrowed.  *ppos* should not be altered
2229-   during iteration. Its value represents offsets within the internal dictionary
2230-   structure, and since the structure is sparse, the offsets are not consecutive.
2231- 
2232-   For example::
2233- 
2234-      PyObject *key, *value;
2235-      int pos = 0;
2236- 
2237-      while (PyDict_Next(self->dict, &pos, &key, &value)) {
2238-          /* do something interesting with the values... */
2239-          ...
2240-      }
2241- 
2242-   The dictionary *p* should not be mutated during iteration.  It is safe (since
2243-   Python 2.1) to modify the values of the keys as you iterate over the dictionary,
2244-   but only so long as the set of keys does not change.  For example::
2245- 
2246-      PyObject *key, *value;
2247-      int pos = 0;
2248- 
2249-      while (PyDict_Next(self->dict, &pos, &key, &value)) {
2250-          int i = PyInt_AS_LONG(value) + 1;
2251-          PyObject *o = PyInt_FromLong(i);
2252-          if (o == NULL)
2253-              return -1;
2254-          if (PyDict_SetItem(self->dict, key, o) < 0) {
2255-              Py_DECREF(o);
2256-              return -1;
2257-          }
2258-          Py_DECREF(o);
2259-      }
2260- 
2261- 
2262-.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
2263- 
2264-   Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*
2265-   may be a dictionary, or any object supporting :func:`PyMapping_Keys` and
2266-   :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be
2267-   replaced if a matching key is found in *b*, otherwise pairs will only be added
2268-   if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an
2269-   exception was raised.
2270- 
2271-   .. versionadded:: 2.2
2272- 
2273- 
2274-.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
2275- 
2276-   This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in
2277-   Python.  Return ``0`` on success or ``-1`` if an exception was raised.
2278- 
2279-   .. versionadded:: 2.2
2280- 
2281- 
2282-.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
2283- 
2284-   Update or merge into dictionary *a*, from the key-value pairs in *seq2*.  *seq2*
2285-   must be an iterable object producing iterable objects of length 2, viewed as
2286-   key-value pairs.  In case of duplicate keys, the last wins if *override* is
2287-   true, else the first wins. Return ``0`` on success or ``-1`` if an exception was
2288-   raised. Equivalent Python (except for the return value)::
2289- 
2290-      def PyDict_MergeFromSeq2(a, seq2, override):
2291-          for key, value in seq2:
2292-              if override or key not in a:
2293-                  a[key] = value
2294- 
2295-   .. versionadded:: 2.2
2296
2297
2298.. _otherobjects:
2299
2300Other Objects
2301=============
2302
n92+.. toctree::
2303
t2304-.. _fileobjects:
t94+   class.rst
2305- 
95+   function.rst
2306-File Objects
96+   method.rst
2307-------------
97+   file.rst
2308- 
98+   module.rst
2309-.. index:: object: file
99+   iterator.rst
2310- 
100+   descriptor.rst
2311-Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
101+   slice.rst
2312-support from the C standard library.  This is an implementation detail and may
102+   weakref.rst
2313-change in future releases of Python.
2314- 
2315- 
2316-.. ctype:: PyFileObject
2317- 
2318-   This subtype of :ctype:`PyObject` represents a Python file object.
2319- 
2320- 
2321-.. cvar:: PyTypeObject PyFile_Type
2322- 
2323-   .. index:: single: FileType (in module types)
2324- 
2325-   This instance of :ctype:`PyTypeObject` represents the Python file type.  This is
2326-   exposed to Python programs as ``file`` and ``types.FileType``.
2327- 
2328- 
2329-.. cfunction:: int PyFile_Check(PyObject *p)
2330- 
2331-   Return true if its argument is a :ctype:`PyFileObject` or a subtype of
2332-   :ctype:`PyFileObject`.
2333- 
2334-   .. versionchanged:: 2.2
2335-      Allowed subtypes to be accepted.
2336- 
2337- 
2338-.. cfunction:: int PyFile_CheckExact(PyObject *p)
2339- 
2340-   Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
2341-   :ctype:`PyFileObject`.
2342- 
2343-   .. versionadded:: 2.2
2344- 
2345- 
2346-.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
2347- 
2348-   .. index:: single: fopen()
2349- 
2350-   On success, return a new file object that is opened on the file given by
2351-   *filename*, with a file mode given by *mode*, where *mode* has the same
2352-   semantics as the standard C routine :cfunc:`fopen`.  On failure, return *NULL*.
2353- 
2354- 
2355-.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
2356- 
2357-   Create a new :ctype:`PyFileObject` from the already-open standard C file
2358-   pointer, *fp*.  The function *close* will be called when the file should be
2359-   closed.  Return *NULL* on failure.
2360- 
2361- 
2362-.. cfunction:: FILE* PyFile_AsFile(PyObject *p)
2363- 
2364-   Return the file object associated with *p* as a :ctype:`FILE\*`.
2365- 
2366- 
2367-.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
2368- 
2369-   .. index:: single: EOFError (built-in exception)
2370- 
2371-   Equivalent to ``p.readline([*n*])``, this function reads one line from the
2372-   object *p*.  *p* may be a file object or any object with a :meth:`readline`
2373-   method.  If *n* is ``0``, exactly one line is read, regardless of the length of
2374-   the line.  If *n* is greater than ``0``, no more than *n* bytes will be read
2375-   from the file; a partial line can be returned.  In both cases, an empty string
2376-   is returned if the end of the file is reached immediately.  If *n* is less than
2377-   ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
2378-   raised if the end of the file is reached immediately.
2379- 
2380- 
2381-.. cfunction:: PyObject* PyFile_Name(PyObject *p)
2382- 
2383-   Return the name of the file specified by *p* as a string object.
2384- 
2385- 
2386-.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
2387- 
2388-   .. index:: single: setvbuf()
2389- 
2390-   Available on systems with :cfunc:`setvbuf` only.  This should only be called
2391-   immediately after file object creation.
2392- 
2393- 
2394-.. cfunction:: int PyFile_Encoding(PyFileObject *p, char *enc)
2395- 
2396-   Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
2397-   on failure.
2398- 
2399-   .. versionadded:: 2.3
2400- 
2401- 
2402-.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
2403- 
2404-   .. index:: single: softspace (file attribute)
2405- 
2406-   This function exists for internal use by the interpreter.  Set the
2407-   :attr:`softspace` attribute of *p* to *newflag* and return the previous value.
2408-   *p* does not have to be a file object for this function to work properly; any
2409-   object is supported (thought its only interesting if the :attr:`softspace`
2410-   attribute can be set).  This function clears any errors, and will return ``0``
2411-   as the previous value if the attribute either does not exist or if there were
2412-   errors in retrieving it.  There is no way to detect errors from this function,
2413-   but doing so should not be needed.
2414- 
2415- 
2416-.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
2417- 
2418-   .. index:: single: Py_PRINT_RAW
2419- 
2420-   Write object *obj* to file object *p*.  The only supported flag for *flags* is
2421-   :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
2422-   instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
2423-   appropriate exception will be set.
2424- 
2425- 
2426-.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
2427- 
2428-   Write string *s* to file object *p*.  Return ``0`` on success or ``-1`` on
2429-   failure; the appropriate exception will be set.
2430- 
2431- 
2432-.. _instanceobjects:
2433- 
2434-Instance Objects
2435-----------------
2436- 
2437-.. index:: object: instance
2438- 
2439-There are very few functions specific to instance objects.
2440- 
2441- 
2442-.. cvar:: PyTypeObject PyInstance_Type
2443- 
2444-   Type object for class instances.
2445- 
2446- 
2447-.. cfunction:: int PyInstance_Check(PyObject *obj)
2448- 
2449-   Return true if *obj* is an instance.
2450- 
2451- 
2452-.. cfunction:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)
2453- 
2454-   Create a new instance of a specific class.  The parameters *arg* and *kw* are
2455-   used as the positional and keyword parameters to the object's constructor.
2456- 
2457- 
2458-.. cfunction:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)
2459- 
2460-   Create a new instance of a specific class without calling its constructor.
2461-   *class* is the class of new object.  The *dict* parameter will be used as the
2462-   object's :attr:`__dict__`; if *NULL*, a new dictionary will be created for the
2463-   instance.
2464- 
2465- 
2466-.. _function-objects:
2467- 
2468-Function Objects
2469-----------------
2470- 
2471-.. index:: object: function
2472- 
2473-There are a few functions specific to Python functions.
2474- 
2475- 
2476-.. ctype:: PyFunctionObject
2477- 
2478-   The C structure used for functions.
2479- 
2480- 
2481-.. cvar:: PyTypeObject PyFunction_Type
2482- 
2483-   .. index:: single: MethodType (in module types)
2484- 
2485-   This is an instance of :ctype:`PyTypeObject` and represents the Python function
2486-   type.  It is exposed to Python programmers as ``types.FunctionType``.
2487- 
2488- 
2489-.. cfunction:: int PyFunction_Check(PyObject *o)
2490- 
2491-   Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).
2492-   The parameter must not be *NULL*.
2493- 
2494- 
2495-.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
2496- 
2497-   Return a new function object associated with the code object *code*. *globals*
2498-   must be a dictionary with the global variables accessible to the function.
2499- 
2500-   The function's docstring, name and *__module__* are retrieved from the code
2501-   object, the argument defaults and closure are set to *NULL*.
2502- 
2503- 
2504-.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)
2505- 
2506-   Return the code object associated with the function object *op*.
2507- 
2508- 
2509-.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)
2510- 
2511-   Return the globals dictionary associated with the function object *op*.
2512- 
2513- 
2514-.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op)
2515- 
2516-   Return the *__module__* attribute of the function object *op*. This is normally
2517-   a string containing the module name, but can be set to any other object by
2518-   Python code.
2519- 
2520- 
2521-.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)
2522- 
2523-   Return the argument default values of the function object *op*. This can be a
2524-   tuple of arguments or *NULL*.
2525- 
2526- 
2527-.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
2528- 
2529-   Set the argument default values for the function object *op*. *defaults* must be
2530-   *Py_None* or a tuple.
2531- 
2532-   Raises :exc:`SystemError` and returns ``-1`` on failure.
2533- 
2534- 
2535-.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)
2536- 
2537-   Return the closure associated with the function object *op*. This can be *NULL*
2538-   or a tuple of cell objects.
2539- 
2540- 
2541-.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
2542- 
2543-   Set the closure associated with the function object *op*. *closure* must be
2544-   *Py_None* or a tuple of cell objects.
2545- 
2546-   Raises :exc:`SystemError` and returns ``-1`` on failure.
2547- 
2548- 
2549-.. _method-objects:
2550- 
2551-Method Objects
2552---------------
2553- 
2554-.. index:: object: method
2555- 
2556-There are some useful functions that are useful for working with method objects.
2557- 
2558- 
2559-.. cvar:: PyTypeObject PyMethod_Type
2560- 
2561-   .. index:: single: MethodType (in module types)
2562- 
2563-   This instance of :ctype:`PyTypeObject` represents the Python method type.  This
2564-   is exposed to Python programs as ``types.MethodType``.
2565- 
2566- 
2567-.. cfunction:: int PyMethod_Check(PyObject *o)
2568- 
2569-   Return true if *o* is a method object (has type :cdata:`PyMethod_Type`).  The
2570-   parameter must not be *NULL*.
2571- 
2572- 
2573-.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self, PyObject *class)
2574- 
2575-   Return a new method object, with *func* being any callable object; this is the
2576-   function that will be called when the method is called.  If this method should
2577-   be bound to an instance, *self* should be the instance and *class* should be the
2578-   class of *self*, otherwise *self* should be *NULL* and *class* should be the
2579-   class which provides the unbound method..
2580- 
2581- 
2582-.. cfunction:: PyObject* PyMethod_Class(PyObject *meth)
2583- 
2584-   Return the class object from which the method *meth* was created; if this was
2585-   created from an instance, it will be the class of the instance.
2586- 
2587- 
2588-.. cfunction:: PyObject* PyMethod_GET_CLASS(PyObject *meth)
2589- 
2590-   Macro version of :cfunc:`PyMethod_Class` which avoids error checking.
2591- 
2592- 
2593-.. cfunction:: PyObject* PyMethod_Function(PyObject *meth)
2594- 
2595-   Return the function object associated with the method *meth*.
2596- 
2597- 
2598-.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
2599- 
2600-   Macro version of :cfunc:`PyMethod_Function` which avoids error checking.
2601- 
2602- 
2603-.. cfunction:: PyObject* PyMethod_Self(PyObject *meth)
2604- 
2605-   Return the instance associated with the method *meth* if it is bound, otherwise
2606-   return *NULL*.
2607- 
2608- 
2609-.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)
2610- 
2611-   Macro version of :cfunc:`PyMethod_Self` which avoids error checking.
2612- 
2613- 
2614-.. _moduleobjects:
2615- 
2616-Module Objects
2617---------------
2618- 
2619-.. index:: object: module
2620- 
2621-There are only a few functions special to module objects.
2622- 
2623- 
2624-.. cvar:: PyTypeObject PyModule_Type
2625- 
2626-   .. index:: single: ModuleType (in module types)
2627- 
2628-   This instance of :ctype:`PyTypeObject` represents the Python module type.  This
2629-   is exposed to Python programs as ``types.ModuleType``.
2630- 
2631- 
2632-.. cfunction:: int PyModule_Check(PyObject *p)
2633- 
2634-   Return true if *p* is a module object, or a subtype of a module object.
2635- 
2636-   .. versionchanged:: 2.2
2637-      Allowed subtypes to be accepted.
2638- 
2639- 
2640-.. cfunction:: int PyModule_CheckExact(PyObject *p)
2641- 
2642-   Return true if *p* is a module object, but not a subtype of
2643-   :cdata:`PyModule_Type`.
2644- 
2645-   .. versionadded:: 2.2
2646- 
2647- 
2648-.. cfunction:: PyObject* PyModule_New(const char *name)
2649- 
2650-   .. index::
2651-      single: __name__ (module attribute)
2652-      single: __doc__ (module attribute)
2653-      single: __file__ (module attribute)
2654- 
2655-   Return a new module object with the :attr:`__name__` attribute set to *name*.
2656-   Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
2657-   the caller is responsible for providing a :attr:`__file__` attribute.
2658- 
2659- 
2660-.. cfunction:: PyObject* PyModule_GetDict(PyObject *module)
2661- 
2662-   .. index:: single: __dict__ (module attribute)
2663- 
2664-   Return the dictionary object that implements *module*'s namespace; this object
2665-   is the same as the :attr:`__dict__` attribute of the module object.  This
2666-   function never fails.  It is recommended extensions use other
2667-   :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly
2668-   manipulate a module's :attr:`__dict__`.
2669- 
2670- 
2671-.. cfunction:: char* PyModule_GetName(PyObject *module)
2672- 
2673-   .. index::
2674-      single: __name__ (module attribute)
2675-      single: SystemError (built-in exception)
2676- 
2677-   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
2678-   or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
2679- 
2680- 
2681-.. cfunction:: char* PyModule_GetFilename(PyObject *module)
2682- 
2683-   .. index::
2684-      single: __file__ (module attribute)
2685-      single: SystemError (built-in exception)
2686- 
2687-   Return the name of the file from which *module* was loaded using *module*'s
2688-   :attr:`__file__` attribute.  If this is not defined, or if it is not a string,
2689-   raise :exc:`SystemError` and return *NULL*.
2690- 
2691- 
2692-.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
2693- 
2694-   Add an object to *module* as *name*.  This is a convenience function which can
2695-   be used from the module's initialization function.  This steals a reference to
2696-   *value*.  Return ``-1`` on error, ``0`` on success.
2697- 
2698-   .. versionadded:: 2.0
2699- 
2700- 
2701-.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
2702- 
2703-   Add an integer constant to *module* as *name*.  This convenience function can be
2704-   used from the module's initialization function. Return ``-1`` on error, ``0`` on
2705-   success.
2706- 
2707-   .. versionadded:: 2.0
2708- 
2709- 
2710-.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
2711- 
2712-   Add a string constant to *module* as *name*.  This convenience function can be
2713-   used from the module's initialization function.  The string *value* must be
2714-   null-terminated.  Return ``-1`` on error, ``0`` on success.
2715- 
2716-   .. versionadded:: 2.0
2717- 
2718- 
2719-.. _iterator-objects:
2720- 
2721-Iterator Objects
2722-----------------
2723- 
2724-Python provides two general-purpose iterator objects.  The first, a sequence
2725-iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
2726-method.  The second works with a callable object and a sentinel value, calling
2727-the callable for each item in the sequence, and ending the iteration when the
2728-sentinel value is returned.
2729- 
2730- 
2731-.. cvar:: PyTypeObject PySeqIter_Type
2732- 
2733-   Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the one-
2734-   argument form of the :func:`iter` built-in function for built-in sequence types.
2735- 
2736-   .. versionadded:: 2.2
2737- 
2738- 
2739-.. cfunction:: int PySeqIter_Check(op)
2740- 
2741-   Return true if the type of *op* is :cdata:`PySeqIter_Type`.
2742- 
2743-   .. versionadded:: 2.2
2744- 
2745- 
2746-.. cfunction:: PyObject* PySeqIter_New(PyObject *seq)
2747- 
2748-   Return an iterator that works with a general sequence object, *seq*.  The
2749-   iteration ends when the sequence raises :exc:`IndexError` for the subscripting
2750-   operation.
2751- 
2752-   .. versionadded:: 2.2
2753- 
2754- 
2755-.. cvar:: PyTypeObject PyCallIter_Type
2756- 
2757-   Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the
2758-   two-argument form of the :func:`iter` built-in function.
2759- 
2760-   .. versionadded:: 2.2
2761- 
2762- 
2763-.. cfunction:: int PyCallIter_Check(op)
2764- 
2765-   Return true if the type of *op* is :cdata:`PyCallIter_Type`.
2766- 
2767-   .. versionadded:: 2.2
2768- 
2769- 
2770-.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
2771- 
2772-   Return a new iterator.  The first parameter, *callable*, can be any Python
2773-   callable object that can be called with no parameters; each call to it should
2774-   return the next item in the iteration.  When *callable* returns a value equal to
2775-   *sentinel*, the iteration will be terminated.
2776- 
2777-   .. versionadded:: 2.2
2778- 
2779- 
2780-.. _descriptor-objects:
2781- 
2782-Descriptor Objects
2783-------------------
2784- 
2785-"Descriptors" are objects that describe some attribute of an object. They are
2786-found in the dictionary of type objects.
2787- 
2788- 
2789-.. cvar:: PyTypeObject PyProperty_Type
2790- 
2791-   The type object for the built-in descriptor types.
2792- 
2793-   .. versionadded:: 2.2
2794- 
2795- 
2796-.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
2797- 
2798-   .. versionadded:: 2.2
2799- 
2800- 
2801-.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
2802- 
2803-   .. versionadded:: 2.2
2804- 
2805- 
2806-.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
2807- 
2808-   .. versionadded:: 2.2
2809- 
2810- 
2811-.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
2812- 
2813-   .. versionadded:: 2.2
2814- 
2815- 
2816-.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
2817- 
2818-   .. versionadded:: 2.3
2819- 
2820- 
2821-.. cfunction:: int PyDescr_IsData(PyObject *descr)
2822- 
2823-   Return true if the descriptor objects *descr* describes a data attribute, or
2824-   false if it describes a method.  *descr* must be a descriptor object; there is
2825-   no error checking.
2826- 
2827-   .. versionadded:: 2.2
2828- 
2829- 
2830-.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)
2831- 
2832-   .. versionadded:: 2.2
2833- 
2834- 
2835-.. _slice-objects:
2836- 
2837-Slice Objects
2838--------------
2839- 
2840- 
2841-.. cvar:: PyTypeObject PySlice_Type
2842- 
2843-   .. index:: single: SliceType (in module types)
2844- 
2845-   The type object for slice objects.  This is the same as ``slice`` and
2846-   ``types.SliceType``.
2847- 
2848- 
2849-.. cfunction:: int PySlice_Check(PyObject *ob)
2850- 
2851-   Return true if *ob* is a slice object; *ob* must not be *NULL*.
2852- 
2853- 
2854-.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
2855- 
2856-   Return a new slice object with the given values.  The *start*, *stop*, and
2857-   *step* parameters are used as the values of the slice object attributes of the
2858-   same names.  Any of the values may be *NULL*, in which case the ``None`` will be
2859-   used for the corresponding attribute.  Return *NULL* if the new object could not
2860-   be allocated.
2861- 
2862- 
2863-.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
2864- 
2865-   Retrieve the start, stop and step indices from the slice object *slice*,
2866-   assuming a sequence of length *length*. Treats indices greater than *length* as
2867-   errors.
2868- 
2869-   Returns 0 on success and -1 on error with no exception set (unless one of the
2870-   indices was not :const:`None` and failed to be converted to an integer, in which
2871-   case -1 is returned with an exception set).
2872- 
2873-   You probably do not want to use this function.  If you want to use slice objects
2874-   in versions of Python prior to 2.3, you would probably do well to incorporate
2875-   the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
2876-   your extension.
2877- 
2878- 
2879-.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
2880- 
2881-   Usable replacement for :cfunc:`PySlice_GetIndices`.  Retrieve the start, stop,
2882-   and step indices from the slice object *slice* assuming a sequence of length
2883-   *length*, and store the length of the slice in *slicelength*.  Out of bounds
2884-   indices are clipped in a manner consistent with the handling of normal slices.
2885- 
2886-   Returns 0 on success and -1 on error with exception set.
2887- 
2888-   .. versionadded:: 2.3
2889- 
2890- 
2891-.. _weakref-objects:
2892- 
2893-Weak Reference Objects
2894-----------------------
2895- 
2896-Python supports *weak references* as first-class objects.  There are two
2897-specific object types which directly implement weak references.  The first is a
2898-simple reference object, and the second acts as a proxy for the original object
2899-as much as it can.
2900- 
2901- 
2902-.. cfunction:: int PyWeakref_Check(ob)
2903- 
2904-   Return true if *ob* is either a reference or proxy object.
2905- 
2906-   .. versionadded:: 2.2
2907- 
2908- 
2909-.. cfunction:: int PyWeakref_CheckRef(ob)
2910- 
2911-   Return true if *ob* is a reference object.
2912- 
2913-   .. versionadded:: 2.2
2914- 
2915- 
2916-.. cfunction:: int PyWeakref_CheckProxy(ob)
2917- 
2918-   Return true if *ob* is a proxy object.
2919- 
2920-   .. versionadded:: 2.2
2921- 
2922- 
2923-.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
2924- 
2925-   Return a weak reference object for the object *ob*.  This will always return a
2926-   new reference, but is not guaranteed to create a new object; an existing
2927-   reference object may be returned.  The second parameter, *callback*, can be a
2928-   callable object that receives notification when *ob* is garbage collected; it
2929-   should accept a single parameter, which will be the weak reference object
2930-   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a weakly-
2931-   referencable object, or if *callback* is not callable, ``None``, or *NULL*, this
2932-   will return *NULL* and raise :exc:`TypeError`.
2933- 
2934-   .. versionadded:: 2.2
2935- 
2936- 
2937-.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
2938- 
2939-   Return a weak reference proxy object for the object *ob*.  This will always
2940-   return a new reference, but is not guaranteed to create a new object; an
2941-   existing proxy object may be returned.  The second parameter, *callback*, can be
2942-   a callable object that receives notification when *ob* is garbage collected; it
2943-   should accept a single parameter, which will be the weak reference object
2944-   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a weakly-
2945-   referencable object, or if *callback* is not callable, ``None``, or *NULL*, this
2946-   will return *NULL* and raise :exc:`TypeError`.
2947- 
2948-   .. versionadded:: 2.2
2949- 
2950- 
2951-.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
2952- 
2953-   Return the referenced object from a weak reference, *ref*.  If the referent is
2954-   no longer live, returns ``None``.
2955- 
2956-   .. versionadded:: 2.2
2957- 
2958- 
2959-.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
2960- 
2961-   Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no
2962-   error checking.
2963- 
2964-   .. versionadded:: 2.2
2965- 
2966- 
2967-.. _cobjects:
2968- 
2969-CObjects
2970---------
2971- 
2972-.. index:: object: CObject
2973- 
2974-Refer to *Extending and Embedding the Python Interpreter*, section 1.12,
2975-"Providing a C API for an Extension Module," for more information on using these
2976-objects.
2977- 
2978- 
2979-.. ctype:: PyCObject
2980- 
2981-   This subtype of :ctype:`PyObject` represents an opaque value, useful for C
2982-   extension modules who need to pass an opaque value (as a :ctype:`void\*`
2983-   pointer) through Python code to other C code.  It is often used to make a C
2984-   function pointer defined in one module available to other modules, so the
2985-   regular import mechanism can be used to access C APIs defined in dynamically
2986-   loaded modules.
2987- 
2988- 
2989-.. cfunction:: int PyCObject_Check(PyObject *p)
2990- 
2991-   Return true if its argument is a :ctype:`PyCObject`.
2992- 
2993- 
2994-.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
2995- 
2996-   Create a :ctype:`PyCObject` from the ``void *``*cobj*.  The *destr* function
2997-   will be called when the object is reclaimed, unless it is *NULL*.
2998- 
2999- 
3000-.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
3001- 
3002-   Create a :ctype:`PyCObject` from the :ctype:`void \*`*cobj*.  The *destr*
3003-   function will be called when the object is reclaimed. The *desc* argument can be
3004-   used to pass extra callback data for the destructor function.
3005- 
3006- 
3007-.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
3008- 
3009-   Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
3010-   created with.
3011- 
3012- 
3013-.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
3014- 
3015-   Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
3016-   created with.
3017- 
3018- 
3019-.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
3020- 
3021-   Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
3022-   have an associated destructor. Return true on success, false on failure.
3023- 
3024- 
3025-.. _cell-objects:
3026- 
3027-Cell Objects
3028-------------
3029- 
3030-"Cell" objects are used to implement variables referenced by multiple scopes.
3031-For each such variable, a cell object is created to store the value; the local
3032-variables of each stack frame that references the value contains a reference to
3033-the cells from outer scopes which also use that variable.  When the value is
3034-accessed, the value contained in the cell is used instead of the cell object
3035-itself.  This de-referencing of the cell object requires support from the
3036-generated byte-code; these are not automatically de-referenced when accessed.
3037-Cell objects are not likely to be useful elsewhere.
3038- 
3039- 
3040-.. ctype:: PyCellObject
3041- 
3042-   The C structure used for cell objects.
3043- 
3044- 
3045-.. cvar:: PyTypeObject PyCell_Type
3046- 
3047-   The type object corresponding to cell objects.
3048- 
3049- 
3050-.. cfunction:: int PyCell_Check(ob)
3051- 
3052-   Return true if *ob* is a cell object; *ob* must not be *NULL*.
3053- 
3054- 
3055-.. cfunction:: PyObject* PyCell_New(PyObject *ob)
3056- 
3057-   Create and return a new cell object containing the value *ob*. The parameter may
3058-   be *NULL*.
3059- 
3060- 
3061-.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
3062- 
3063-   Return the contents of the cell *cell*.
3064- 
3065- 
3066-.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
3067- 
3068-   Return the contents of the cell *cell*, but without checking that *cell* is
3069-   non-*NULL* and a cell object.
3070- 
3071- 
3072-.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
3073- 
3074-   Set the contents of the cell object *cell* to *value*.  This releases the
3075-   reference to any current content of the cell. *value* may be *NULL*.  *cell*
3076-   must be non-*NULL*; if it is not a cell object, ``-1`` will be returned.  On
3077-   success, ``0`` will be returned.
3078- 
3079- 
3080-.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
3081- 
3082-   Sets the value of the cell object *cell* to *value*.  No reference counts are
3083-   adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
3084-   be a cell object.
3085- 
3086- 
3087-.. _gen-objects:
3088- 
3089-Generator Objects
3090------------------
3091- 
3092-Generator objects are what Python uses to implement generator iterators. They
3093-are normally created by iterating over a function that yields values, rather
3094-than explicitly calling :cfunc:`PyGen_New`.
3095- 
3096- 
3097-.. ctype:: PyGenObject
3098- 
3099-   The C structure used for generator objects.
3100- 
3101- 
3102-.. cvar:: PyTypeObject PyGen_Type
3103- 
3104-   The type object corresponding to generator objects
3105- 
3106- 
3107-.. cfunction:: int PyGen_Check(ob)
3108- 
3109-   Return true if *ob* is a generator object; *ob* must not be *NULL*.
3110- 
3111- 
3112-.. cfunction:: int PyGen_CheckExact(ob)
3113- 
3114-   Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
3115-   be *NULL*.
3116- 
3117- 
3118-.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame)
3119- 
3120-   Create and return a new generator object based on the *frame* object. A
3121-   reference to *frame* is stolen by this function. The parameter must not be
3122-   *NULL*.
3123- 
3124- 
3125-.. _datetime-objects:
3126- 
3127-DateTime Objects
3128-----------------
3129- 
3130-Various date and time objects are supplied by the :mod:`datetime` module.
3131-Before using any of these functions, the header file :file:`datetime.h` must be
3132-included in your source (note that this is not include by :file:`Python.h`), and
3133-macro :cfunc:`PyDateTime_IMPORT` must be invoked.  The macro arranges to put a
3134-pointer to a C structure in a static variable ``PyDateTimeAPI``, which is used
3135-by the following macros.
3136- 
3137-Type-check macros:
3138- 
3139- 
3140-.. cfunction:: int PyDate_Check(PyObject *ob)
3141- 
3142-   Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
3143-   :cdata:`PyDateTime_DateType`.  *ob* must not be *NULL*.
3144- 
3145-   .. versionadded:: 2.4
3146- 
3147- 
3148-.. cfunction:: int PyDate_CheckExact(PyObject *ob)
3149- 
3150-   Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
3151-   *NULL*.
3152- 
3153-   .. versionadded:: 2.4
3154- 
3155- 
3156-.. cfunction:: int PyDateTime_Check(PyObject *ob)
3157- 
3158-   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of
3159-   :cdata:`PyDateTime_DateTimeType`.  *ob* must not be *NULL*.
3160- 
3161-   .. versionadded:: 2.4
3162- 
3163- 
3164-.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
3165- 
3166-   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
3167-   be *NULL*.
3168- 
3169-   .. versionadded:: 2.4
3170- 
3171- 
3172-.. cfunction:: int PyTime_Check(PyObject *ob)
3173- 
3174-   Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of
3175-   :cdata:`PyDateTime_TimeType`.  *ob* must not be *NULL*.
3176- 
3177-   .. versionadded:: 2.4
3178- 
3179- 
3180-.. cfunction:: int PyTime_CheckExact(PyObject *ob)
3181- 
3182-   Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
3183-   *NULL*.
3184- 
3185-   .. versionadded:: 2.4
3186- 
3187- 
3188-.. cfunction:: int PyDelta_Check(PyObject *ob)
3189- 
3190-   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of
3191-   :cdata:`PyDateTime_DeltaType`.  *ob* must not be *NULL*.
3192- 
3193-   .. versionadded:: 2.4
3194- 
3195- 
3196-.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
3197- 
3198-   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
3199-   *NULL*.
3200- 
3201-   .. versionadded:: 2.4
3202- 
3203- 
3204-.. cfunction:: int PyTZInfo_Check(PyObject *ob)
3205- 
3206-   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of
3207-   :cdata:`PyDateTime_TZInfoType`.  *ob* must not be *NULL*.
3208- 
3209-   .. versionadded:: 2.4
3210- 
3211- 
3212-.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
3213- 
3214-   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
3215-   *NULL*.
3216- 
3217-   .. versionadded:: 2.4
3218- 
3219-Macros to create objects:
3220- 
3221- 
3222-.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
3223- 
3224-   Return a ``datetime.date`` object with the specified year, month and day.
3225- 
3226-   .. versionadded:: 2.4
3227- 
3228- 
3229-.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
3230- 
3231-   Return a ``datetime.datetime`` object with the specified year, month, day, hour,
3232-   minute, second and microsecond.
3233- 
3234-   .. versionadded:: 2.4
3235- 
3236- 
3237-.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
3238- 
3239-   Return a ``datetime.time`` object with the specified hour, minute, second and
3240-   microsecond.
3241- 
3242-   .. versionadded:: 2.4
3243- 
3244- 
3245-.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
3246- 
3247-   Return a ``datetime.timedelta`` object representing the given number of days,
3248-   seconds and microseconds.  Normalization is performed so that the resulting
3249-   number of microseconds and seconds lie in the ranges documented for
3250-   ``datetime.timedelta`` objects.
3251- 
3252-   .. versionadded:: 2.4
3253- 
3254-Macros to extract fields from date objects.  The argument must be an instance of
3255-:cdata:`PyDateTime_Date`, including subclasses (such as
3256-:cdata:`PyDateTime_DateTime`).  The argument must not be *NULL*, and the type is
3257-not checked:
3258- 
3259- 
3260-.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
3261- 
3262-   Return the year, as a positive int.
3263- 
3264-   .. versionadded:: 2.4
3265- 
3266- 
3267-.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
3268- 
3269-   Return the month, as an int from 1 through 12.
3270- 
3271-   .. versionadded:: 2.4
3272- 
3273- 
3274-.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
3275- 
3276-   Return the day, as an int from 1 through 31.
3277- 
3278-   .. versionadded:: 2.4
3279- 
3280-Macros to extract fields from datetime objects.  The argument must be an
3281-instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument
3282-must not be *NULL*, and the type is not checked:
3283- 
3284- 
3285-.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
3286- 
3287-   Return the hour, as an int from 0 through 23.
3288- 
3289-   .. versionadded:: 2.4
3290- 
3291- 
3292-.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
3293- 
3294-   Return the minute, as an int from 0 through 59.
3295- 
3296-   .. versionadded:: 2.4
3297- 
3298- 
3299-.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
3300- 
3301-   Return the second, as an int from 0 through 59.
3302- 
3303-   .. versionadded:: 2.4
3304- 
3305- 
3306-.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
3307- 
3308-   Return the microsecond, as an int from 0 through 999999.
3309- 
3310-   .. versionadded:: 2.4
3311- 
3312-Macros to extract fields from time objects.  The argument must be an instance of
3313-:cdata:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
3314-and the type is not checked:
3315- 
3316- 
3317-.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
3318- 
3319-   Return the hour, as an int from 0 through 23.
3320- 
3321-   .. versionadded:: 2.4
3322- 
3323- 
3324-.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
3325- 
3326-   Return the minute, as an int from 0 through 59.
3327- 
3328-   .. versionadded:: 2.4
3329- 
3330- 
3331-.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
3332- 
3333-   Return the second, as an int from 0 through 59.
3334- 
3335-   .. versionadded:: 2.4
3336- 
3337- 
3338-.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
3339- 
3340-   Return the microsecond, as an int from 0 through 999999.
3341- 
3342-   .. versionadded:: 2.4
3343- 
3344-Macros for the convenience of modules implementing the DB API:
3345- 
3346- 
3347-.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
3348- 
3349-   Create and return a new ``datetime.datetime`` object given an argument tuple
3350-   suitable for passing to ``datetime.datetime.fromtimestamp()``.
3351- 
3352-   .. versionadded:: 2.4
3353- 
3354- 
3355-.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)
3356- 
3357-   Create and return a new ``datetime.date`` object given an argument tuple
3358-   suitable for passing to ``datetime.date.fromtimestamp()``.
3359- 
3360-   .. versionadded:: 2.4
3361- 
3362- 
3363-.. _setobjects:
3364- 
3365-Set Objects
3366------------
3367- 
3368-.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
3369- 
3370- 
3371-.. index::
3372-   objectset
103+   cobject.rst
3373-   object: frozenset
104+   cell.rst
3374- 
105+   gen.rst
3375-.. versionadded:: 2.5
106+   datetime.rst
3376- 
107+   set.rst
3377-This section details the public API for :class:`set` and :class:`frozenset`
3378-objects.  Any functionality not listed below is best accessed using the either
3379-the abstract object protocol (including :cfunc:`PyObject_CallMethod`,
3380-:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`,
3381-:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and
3382-:cfunc:`PyObject_GetIter`) or the abstract number protocol (including
3383-:cfunc:`PyNumber_Add`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`,
3384-:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAdd`,
3385-:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and
3386-:cfunc:`PyNumber_InPlaceXor`).
3387- 
3388- 
3389-.. ctype:: PySetObject
3390- 
3391-   This subtype of :ctype:`PyObject` is used to hold the internal data for both
3392-   :class:`set` and :class:`frozenset` objects.  It is like a :ctype:`PyDictObject`
3393-   in that it is a fixed size for small sets (much like tuple storage) and will
3394-   point to a separate, variable sized block of memory for medium and large sized
3395-   sets (much like list storage). None of the fields of this structure should be
3396-   considered public and are subject to change.  All access should be done through
3397-   the documented API rather than by manipulating the values in the structure.
3398- 
3399- 
3400-.. cvar:: PyTypeObject PySet_Type
3401- 
3402-   This is an instance of :ctype:`PyTypeObject` representing the Python
3403-   :class:`set` type.
3404- 
3405- 
3406-.. cvar:: PyTypeObject PyFrozenSet_Type
3407- 
3408-   This is an instance of :ctype:`PyTypeObject` representing the Python
3409-   :class:`frozenset` type.
3410- 
3411-The following type check macros work on pointers to any Python object. Likewise,
3412-the constructor functions work with any iterable Python object.
3413- 
3414- 
3415-.. cfunction:: int PyAnySet_Check(PyObject *p)
3416- 
3417-   Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
3418-   instance of a subtype.
3419- 
3420- 
3421-.. cfunction:: int PyAnySet_CheckExact(PyObject *p)
3422- 
3423-   Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
3424-   not an instance of a subtype.
3425- 
3426- 
3427-.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p)
3428- 
3429-   Return true if *p* is a :class:`frozenset` object but not an instance of a
3430-   subtype.
3431- 
3432- 
3433-.. cfunction:: PyObject* PySet_New(PyObject *iterable)
3434- 
3435-   Return a new :class:`set` containing objects returned by the *iterable*.  The
3436-   *iterable* may be *NULL* to create a new empty set.  Return the new set on
3437-   success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
3438-   actually iterable.  The constructor is also useful for copying a set
3439-   (``c=set(s)``).
3440- 
3441- 
3442-.. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable)
3443- 
3444-   Return a new :class:`frozenset` containing objects returned by the *iterable*.
3445-   The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
3446-   set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
3447-   not actually iterable.
3448- 
3449-The following functions and macros are available for instances of :class:`set`
3450-or :class:`frozenset` or instances of their subtypes.
3451- 
3452- 
3453-.. cfunction:: int PySet_Size(PyObject *anyset)
3454- 
3455-   .. index:: builtin: len
3456- 
3457-   Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
3458-   ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a
3459-   :class:`set`, :class:`frozenset`, or an instance of a subtype.
3460- 
3461- 
3462-.. cfunction:: int PySet_GET_SIZE(PyObject *anyset)
3463- 
3464-   Macro form of :cfunc:`PySet_Size` without error checking.
3465- 
3466- 
3467-.. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key)
3468- 
3469-   Return 1 if found, 0 if not found, and -1 if an error is encountered.  Unlike
3470-   the Python :meth:`__contains__` method, this function does not automatically
3471-   convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
3472-   the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
3473-   :class:`set`, :class:`frozenset`, or an instance of a subtype.
3474- 
3475-The following functions are available for instances of :class:`set` or its
3476-subtypes but not for instances of :class:`frozenset` or its subtypes.
3477- 
3478- 
3479-.. cfunction:: int PySet_Add(PyObject *set, PyObject *key)
3480- 
3481-   Add *key* to a :class:`set` instance.  Does not apply to :class:`frozenset`
3482-   instances.  Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
3483-   the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
3484-   Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
3485-   subtype.
3486- 
3487- 
3488-.. cfunction:: int PySet_Discard(PyObject *set, PyObject *key)
3489- 
3490-   Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
3491-   error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
3492-   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`discard`
3493-   method, this function does not automatically convert unhashable sets into
3494-   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
3495-   instance of :class:`set` or its subtype.
3496- 
3497- 
3498-.. cfunction:: PyObject* PySet_Pop(PyObject *set)
3499- 
3500-   Return a new reference to an arbitrary object in the *set*, and removes the
3501-   object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
3502-   set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of
3503-   :class:`set` or its subtype.
3504- 
3505- 
3506-.. cfunction:: int PySet_Clear(PyObject *set)
3507- 
3508-   Empty an existing set of all elements.
3509- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op