# Python/C API Reference Manual

Guido van Rossum
Corporation for National Research Initiatives (CNRI)
1895 Preston White Drive, Reston, Va 20191, USA
E-mail: `guido@CNRI.Reston.Va.US`, `guido@python.org`

December 31, 1997
Release 1.5

Copyright © 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands.

All Rights Reserved

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Stichting Mathematisch Centrum or CWI or Corporation for National Research Initiatives or CNRI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

While CWI is the initial source for this software, a modified version is made available by the Corporation for National Research Initiatives (CNRI) at the Internet address ftp://ftp.python.org.

STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

### Abstract:

This manual documents the API used by C (or C++) programmers who want to write extension modules or embed Python. It is a companion to ``Extending and Embedding the Python Interpreter'', which describes the general principles of extension writing but does not document the API functions in detail.

Warning: The current version of this document is incomplete. I hope that it is nevertheless useful. I will continue to work on it, and release new versions from time to time, independent from Python source code releases.

- Contents
- 1 Introduction
  - 1.1 Include Files
  - 1.2 Objects, Types and Reference Counts
    - 1.2.1 Reference Counts
    - 1.2.2 Types
  - 1.3 Exceptions
  - 1.4 Embedding Python
- 2 Basic Utilities
- 3 Reference Counting
- 4 Exception Handling
  - 4.1 Standard Exceptions
- 5 Utilities
  - 5.1 OS Utilities
  - 5.2 Importing modules
- 6 Debugging
- 7 The Very High Level Layer
- 8 Abstract Objects Layer
  - 8.1 Object Protocol
  - 8.2 Number Protocol
  - 8.3 Sequence protocol
  - 8.4 Mapping protocol
  - 8.5 Constructors
- 9 Concrete Objects Layer
- 10 Defining New Object Types
- 11 Initialization, Finalization, and Threads
  - 11.1 Thread State and the Global Interpreter Lock
  - 11.2 Defining New Object Types
- 12 Specific Data Types
  - 12.1 Fundamental Objects
    - 12.1.1 Type Objects
    - 12.1.2 The None Object
  - 12.2 Sequence Objects
    - 12.2.1 String Objects
    - 12.2.2 Tuple Objects
    - 12.2.3 List Objects
  - 12.3 Mapping Objects
    - 12.3.1 Dictionary Objects
  - 12.4 Numeric Objects
    - 12.4.1 Plain Integer Objects
    - 12.4.2 Long Integer Objects
    - 12.4.3 Floating Point Objects
    - 12.4.4 Complex Number Objects
  - 12.5 Other Objects
    - 12.5.1 File Objects
    - 12.5.2 CObjects
- Index
- About this document ...