This repository is for developing the new C-API for Python. it will contain no implementation, but will serve a repository of design principles, rules and organization. As well as maintaining a record of the discussions involved.
The new C-API will follow a dozen or so design principles. These are the high-level concepts that determine the nature of the API.
It would be laborious and error prone to consider and apply the design principles each time a new function were added to the API.
To enable developers to follow the design principles when extending the API, there are a number of design rules for them to follow.
The intention is that by following the rules, the design principles should be observed. Some judgement will still be required, though.
There about 1500 functions marked as Py_API_FUNC and about 200 objects
marked in as Py_ABI_DATA in the current API.
Many of these are artifacts of the implementation, but we would still expect the API to contain many hundreds, maybe a thousand functions.
The API should be organized in categories, reflected in the namespaces of the API. We want to break the API into namepsaces, and to be discoverable.
We anticipate that many core objects will get there own namespace, for example:
- Object
- Tuple
- List
- Str
- Bytes
Also various aspects of the runtime should also get there own namespace:
- Interpreter
- GC
- FrameStack
- Operations
We do not expect packages to be ported to the new API in one go. To help porting we will provide an interop API
The documentation will follow the Diataxis documentation framework
For each function in the legacy API, we will add documentation describing how code using it should be ported to the new API.