PEP 689 -- Add an unstable C-API tier · Issue #91744 · python/cpython (original) (raw)

Skip to content

Navigation Menu

• • GitHub Copilot Write better code with AI
  • GitHub Advanced Security Find and fix vulnerabilities
  • Actions Automate any workflow
  • Codespaces Instant dev environments
  • Issues Plan and track work
  • Code Review Manage code changes
  • Discussions Collaborate outside of code
  • Code Search Find more, search less
• Explore
  • Learning Pathways
  • Events & Webinars
  • Ebooks & Whitepapers
  • Customer Stories
  • Partners
  • Executive Insights
• • GitHub Sponsors Fund open source developers
  • The ReadME Project GitHub community articles
• • Enterprise platform AI-powered developer platform
• Pricing

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sign up

Description

On python-dev, it became clear that it would be useful to have a “semi-stable” “unstable” C-API tier which will stay stable within a minor release.

• This API will go in a new directory (Include/unstable/) - see Nick's reply
  You'll need to #define Py_USING_UNSTABLE_API.
  (name still up for bikeshedding).
• Since we're nearing Beta and there's no rush to break things, in 3.11
  you only get a warning if you try to use it without the opt-in #define.
  In 3.12 it'll fail.
• The functions will be renamed to drop the leading underscore. The old
  names will be available, and may be removed
  whenever the API changes. (Ideally, the underscore should always mark
  API that's fully private with no guarantees at all.)
• Get SC approval (this is now PEP-689 that will need acceptance)
• The API will be stable during a minor release. (As usual, for extreme
  cases, exceptions are possible with SC approval.)
• Docs:
  • Update https://devguide.python.org/c-api/
  • Update https://docs.python.org/3.10/c-api/stable.html
  • Add individual reference entries for the API
  • Document the new opt-in macro
• All ununstable API should be tested
  • PEP-523 PyCode_* functions: tested in test_code
  • ...

What should be here:

• Functions added in PEP-523
• PyCode_New, PyCode_NewWithPosOnlyArgs
• Ideally anything documented as subject to change between minor
  releases. (To be kind to users, if something is added later we should
  again have one release of compiler warnings before requiring the opt-in.
  Unless that API just changed and users would get errors anyway.)
• Cinder's dict writing API looks like it would feel at home here: add support for watching writes to selected dictionaries #91052 (comment)
• PyBytesObject.ob_shash sounds like a good candidate: see https://discuss.python.org/t/15108
• non-opaque access to frame structs and any other key APIs needed to
  implement alternate eval loops with comparable performance to the default
  eval loop (unless & until we can figure out stable public APIs that can
  deliver equivalent performance) - see Nick's reply
• C APIs that provide access to compiled code whether in AST or opcode
  form (the API itself may be stable, but the compiled code isn't, so this is
  kinda covered by your last point) - see Nick's reply
• _Py_HashDouble, see comment below

First PR: #91789