sphinx / Doc-3k / c-api / concrete.rst

Full commit

Concrete Objects Layer

The functions in this chapter are specific to certain Python object types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; for example, to check that an object is a dictionary, use :cfunc:`PyDict_Check`. The chapter is structured like the "family tree" of Python object types.


While the functions described in this chapter carefully check the type of the objects which are passed in, many of them do not check for NULL being passed instead of a valid object. Allowing NULL to be passed in can cause memory access violations and immediate termination of the interpreter.

Fundamental Objects

This section describes Python type objects and the singleton object None.

Type Objects

The None Object

Note that the :ctype:`PyTypeObject` for None is not directly exposed in the Python/C API. Since None is a singleton, testing for object identity (using == in C) is sufficient. There is no :cfunc:`PyNone_Check` function for the same reason.

Numeric Objects

Plain Integer Objects

Boolean Objects

Booleans in Python are implemented as a subclass of integers. There are only two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal creation and deletion functions don't apply to booleans. The following macros are available, however.

Long Integer Objects

Floating Point Objects

Complex Number Objects

Python's complex number objects are implemented as two distinct types when viewed from the C API: one is the Python object exposed to Python programs, and the other is a C structure which represents the actual complex number value. The API provides functions for working with both.

Complex Numbers as C Structures

Note that the functions which accept these structures as parameters and return them as results do so by value rather than dereferencing them through pointers. This is consistent throughout the API.

Complex Numbers as Python Objects

Sequence Objects

Generic operations on sequence objects were discussed in the previous chapter; this section deals with the specific kinds of sequence objects that are intrinsic to the Python language.

String Objects

These functions raise :exc:`TypeError` when expecting a string parameter and are called with a non-string parameter.

Unicode Objects

These are the basic Unicode object types used for the Unicode implementation in Python:

Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep this in mind when writing extensions or interfaces.

The following APIs are really C macros and can be used to do fast checks and to access internal read-only data of Unicode objects:

Unicode provides many different character properties. The most often needed ones are available through these macros which are mapped to C functions depending on the Python configuration.

These APIs can be used for fast direct character conversions:

To create Unicode objects and access their basic sequence properties, use these APIs:

If the platform supports :ctype:`wchar_t` and provides a header file wchar.h, Python can interface directly to this type using the following functions. Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to the system's :ctype:`wchar_t`.

Built-in Codecs

Python provides a set of builtin codecs which are written in C for speed. All of these codecs are directly usable via the following functions.

Many of the following APIs take two arguments encoding and errors. These parameters encoding and errors have the same semantics as the ones of the builtin unicode() Unicode object constructor.

Setting encoding to NULL causes the default encoding to be used which is ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding` as the encoding for file names. This variable should be treated as read-only: On some systems, it will be a pointer to a static string, on others, it will change at run-time (such as when the application invokes setlocale).

Error handling is set by errors which may also be set to NULL meaning to use the default handling defined for the codec. Default error handling for all builtin codecs is "strict" (:exc:`ValueError` is raised).

The codecs all use a similar interface. Only deviation from the following generic ones are documented for simplicity.

These are the generic codec APIs:

These are the UTF-8 codec APIs:

These are the UTF-16 codec APIs:

These are the "Unicode Escape" codec APIs:

These are the "Raw Unicode Escape" codec APIs:

These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode ordinals and only these are accepted by the codecs during encoding.

These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other codes generate errors.

These are the mapping codec APIs:

This codec is special in that it can be used to implement many different codecs (and this is in fact what was done to obtain most of the standard codecs included in the :mod:`encodings` package). The codec uses mapping to encode and decode characters.

Decoding mappings must map single string characters to single Unicode characters, integers (which are then interpreted as Unicode ordinals) or None (meaning "undefined mapping" and causing an error).

Encoding mappings must map single Unicode characters to single string characters, integers (which are then interpreted as Latin-1 ordinals) or None (meaning "undefined mapping" and causing an error).

The mapping objects provided must only support the __getitem__ mapping interface.

If a character lookup fails with a LookupError, the character is copied as-is meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal resp. Because of this, mappings only need to contain those mappings which map characters to different code points.

The following codec API is special in that maps Unicode to Unicode.

These are the MBCS codec APIs. They are currently only available on Windows and use the Win32 MBCS converters to implement the conversions. Note that MBCS (or DBCS) is a class of encodings, not just one. The target encoding is defined by the user settings on the machine running the codec.

Methods and Slot Functions

The following APIs are capable of handling Unicode objects and strings on input (we refer to them as strings in the descriptions) and return Unicode objects or integers as appropriate.

They all return NULL or -1 if an exception occurs.

Buffer Objects

Python objects implemented in C can export a group of functions called the "buffer interface." These functions can be used by an object to expose its data in a raw, byte-oriented format. Clients of the object can use the buffer interface to access the object data directly, without needing to copy it first.

Two examples of objects that support the buffer interface are strings and arrays. The string object exposes the character contents in the buffer interface's byte-oriented form. An array can also expose its contents, but it should be noted that array elements may be multi-byte values.

An example user of the buffer interface is the file object's :meth:`write` method. Any object that can export a series of bytes through the buffer interface can be written to a file. There are a number of format codes to :cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface, returning data from the target object.

More information on the buffer interface is provided in the section "Buffer Object Structures" (section :ref:`buffer-structs`), under the description for :ctype:`PyBufferProcs`.

A "buffer object" is defined in the :file:`bufferobject.h` header (included by :file:`Python.h`). These objects look very similar to string objects at the Python programming level: they support slicing, indexing, concatenation, and some other standard string operations. However, their data can come from one of two sources: from a block of memory, or from another object which exports the buffer interface.

Buffer objects are useful as a way to expose the data from another object's buffer interface to the Python programmer. They can also be used as a zero-copy slicing mechanism. Using their ability to reference a block of memory, it is possible to expose any data to the Python programmer quite easily. The memory could be a large, constant array in a C extension, it could be a raw block of memory for manipulation before passing to an operating system library, or it could be used to pass around structured data in its native, in-memory format.

Tuple Objects

List Objects

Mapping Objects

Dictionary Objects

Other Objects

Class Objects

Note that the class objects described here represent old-style classes, which will go away in Python 3. When creating new types for extension modules, you will want to work with type objects (section :ref:`typeobjects`).

File Objects

Python's built-in file objects are implemented entirely on the :ctype:`FILE\*` support from the C standard library. This is an implementation detail and may change in future releases of Python.

Instance Objects

There are very few functions specific to instance objects.

Function Objects

There are a few functions specific to Python functions.

Method Objects

There are some useful functions that are useful for working with method objects.

Module Objects

There are only a few functions special to module objects.

Iterator Objects

Python provides two general-purpose iterator objects. The first, a sequence iterator, works with an arbitrary sequence supporting the :meth:`__getitem__` method. The second works with a callable object and a sentinel value, calling the callable for each item in the sequence, and ending the iteration when the sentinel value is returned.

Descriptor Objects

"Descriptors" are objects that describe some attribute of an object. They are found in the dictionary of type objects.

Slice Objects

Weak Reference Objects

Python supports weak references as first-class objects. There are two specific object types which directly implement weak references. The first is a simple reference object, and the second acts as a proxy for the original object as much as it can.


Refer to Extending and Embedding the Python Interpreter, section 1.12, "Providing a C API for an Extension Module," for more information on using these objects.

Cell Objects

"Cell" objects are used to implement variables referenced by multiple scopes. For each such variable, a cell object is created to store the value; the local variables of each stack frame that references the value contains a reference to the cells from outer scopes which also use that variable. When the value is accessed, the value contained in the cell is used instead of the cell object itself. This de-referencing of the cell object requires support from the generated byte-code; these are not automatically de-referenced when accessed. Cell objects are not likely to be useful elsewhere.

Generator Objects

Generator objects are what Python uses to implement generator iterators. They are normally created by iterating over a function that yields values, rather than explicitly calling :cfunc:`PyGen_New`.

DateTime Objects

Various date and time objects are supplied by the :mod:`datetime` module. Before using any of these functions, the header file :file:`datetime.h` must be included in your source (note that this is not included by :file:`Python.h`), and the macro :cfunc:`PyDateTime_IMPORT` must be invoked. The macro puts a pointer to a C structure into a static variable, PyDateTimeAPI, that is used by the following macros.

Type-check macros:

Macros to create objects:

Macros to extract fields from date objects. The argument must be an instance of :cdata:`PyDateTime_Date`, including subclasses (such as :cdata:`PyDateTime_DateTime`). The argument must not be NULL, and the type is not checked:

Macros to extract fields from datetime objects. The argument must be an instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument must not be NULL, and the type is not checked:

Macros to extract fields from time objects. The argument must be an instance of :cdata:`PyDateTime_Time`, including subclasses. The argument must not be NULL, and the type is not checked:

Macros for the convenience of modules implementing the DB API:

Set Objects

This section details the public API for :class:`set` and :class:`frozenset` objects. Any functionality not listed below is best accessed using the either the abstract object protocol (including :cfunc:`PyObject_CallMethod`, :cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`, :cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and :cfunc:`PyObject_GetIter`) or the abstract number protocol (including :cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`, :cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`, :cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and :cfunc:`PyNumber_InPlaceXor`).

The following type check macros work on pointers to any Python object. Likewise, the constructor functions work with any iterable Python object.

The following functions and macros are available for instances of :class:`set` or :class:`frozenset` or instances of their subtypes.

The following functions are available for instances of :class:`set` or its subtypes but not for instances of :class:`frozenset` or its subtypes.