Skip to content

Unstable C API tier (PEP 689) #101101

Description

@encukou

Add an Unstable C API tier as per PEP 689.

Other candidates for inclusion are below.
These usually need discussion first. This is a checklist for having the discussion.
Please try to not hold the individual discussions in this issue.

  • Dict watching API
  • Functions from PEP-523 not specified in PEP-689 (_PyEval_EvalFrameDefault & co.) -- this is a can of worms tho
  • FrameStack API (Add "unstable" frame stack api #91371)
  • _Py_HashDouble, see PEP 689 -- Add an unstable C-API tier #91744 (comment)
  • PyBytesObject.ob_shash sounds like a good candidate: see https://discuss.python.org/t/15108 (guess fields need a slightly different naming convention though. Sigh. That should have been in the PEP.)
  • 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) - see Nick's reply
  • PyLong_FromByteArray/PyUnstable_LongToBase30Digits: https://discuss.python.org/t/20045 [there's now `PyLong_{From,To}NativeBytes
  • Anything that starts with an underscore and is documented
  • Fast access to PyLong contents [PyLong_Export]

Got any more?
I offer to move other API to the unstable tier myself, if there's a good usage example to base docs & regression tests on [edit 2026:] and a C API WG decision. Please discuss new ideas on Discourse.

Linked PRs

Activity

  1. added a commit that references this issue on Feb 28, 2023
  2. added a commit that references this issue on Feb 28, 2023
  3. added a commit that references this issue on Mar 1, 2023
  4. corona10 commented on Mar 1, 2023

    @corona10
    Member

    @encukou #101102 caused the refleak test failure with my local machine
    I submitted the related patch: #102350
    See also: https://buildbot.python.org/all/#/builders/840/builds/390

  5. added a commit that references this issue on Mar 2, 2023
  6. CAM-Gerlach commented on May 2, 2023

    @CAM-Gerlach
    Member

    Hey @encukou , with the feature freeze coming up, do you have an update on the status here?

  7. encukou commented on May 2, 2023

    @encukou
    MemberAuthor

    Changes described the PEP are in. Waiting for SC approval for a change before I mark it Final: python/steering-council#185

    I won't be able to start all the discussions I want before beta, so the issue will stay open.

  8. vstinner commented on Jan 27, 2025

    @vstinner
    Member

    https://peps.python.org/pep-0689/ status is now Final. Can this issue be closed?

  9. encukou commented on Jan 28, 2025

    @encukou
    MemberAuthor

    Sadly I haven't had as much time for the C API as I hoped. If you want to work on one of the items above, or move this to the C API WG, go ahead.

  10. mbechard commented on Feb 24, 2026

    @mbechard

    I would like to request that the AST parsing be exposed as an Unstable C API as well. I use this to parse simple expressions that run code native to my app, rather than going through the Python interpreter which ultimately ends up back in C module code I've made using the Python C API. This is useful for common used expressions, as it gives a large speedup for the simple/common cases. The code falls back to the full interpreter when an expression includes items my parser doesn't handle.
    In particular, I use
    PyParser_ASTFromString
    And then traverse the AST using the various enums and structs from pycore_ast.h

  11. vstinner commented on Mar 2, 2026

    @vstinner
    Member

    Include/internal/pycore_ast.h and Include/internal/pycore_asdl.h cannot easily be exposed in the public C API, even as PyUnstable. Names are not prefixed by Py prefix. Using directly structure members is more like to cause API compatibility issues if a structure changes. For example, PEP 810 (lazy imports) recently added int is_lazy; to Import and ImportFrom structures, and added int is_lazy parameter to _PyAST_Import() and _PyAST_ImportFrom() functions.

  12. mbechard commented on Mar 2, 2026

    @mbechard

    API incompatibility through struct changes is ok though, as I would expect that in an unstable API.

  13. encukou commented on Mar 3, 2026

    @encukou
    MemberAuthor

    The original post asks:

    Please try to not hold the individual discussions in this issue.

    Nowadays the place for new ideas is Discourse.

    That said, I like the idea in general, but I think exposing this even in the unstable API would be a huge amount of work. This is all optimized, generated code.

    I use this to parse simple expressions that run code native to my app

    You're essentially forking CPython; depending on a specific, tested build.


    I'm thinking of closing this issue -- the world has moved on; unstable API went in a slightly different direction than I thought.

  14. added
    pendingThe issue will be closed if no feedback is provided
    on Mar 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    pendingThe issue will be closed if no feedback is providedtopic-C-APItype-featureA feature request or enhancement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions