RFC: Clarify usage of macros for PySequence_Fast within the Limited C API

[HaoZeke]

BPO	47261
Nosy	@HaoZeke

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2022-04-08.15:14:46.053>
labels = ['expert-C-API', 'docs']
title = 'RFC: Clarify usage of macros for PySequence_Fast within the Limited C API'
updated_at = <Date 2022-04-08.15:19:49.541>
user = 'https://github.com/HaoZeke'

bugs.python.org fields:

activity = <Date 2022-04-08.15:19:49.541>
actor = 'rgoswami'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'C API']
creation = <Date 2022-04-08.15:14:46.053>
creator = 'rgoswami'
dependencies = []
files = []
hgrepos = []
issue_num = 47261
keywords = []
message_count = 2.0
messages = ['416989', '416990']
nosy_count = 2.0
nosy_names = ['docs@python', 'rgoswami']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue47261'
versions = []

[HaoZeke]

The current documentation_ of the Python-C API mentions that PySequence_Fast is part of the limited API. However, this may be a typo as all the functions interacting with a PySequence_Fast object are macros, e.g. PySequence_Fast_GET_SIZE, PySequence_Fast_GET_ITEM etc.

If this is indeed a documentation bug I'm happy to open a PR to fix this once consensus is reached.

.. _current documentation : https://docs.python.org/3/c-api/stable.html#contents-of-limited-api

[HaoZeke]

Perhaps to be clear, there are two possibilities:

1. PySequence_Fast should be removed from the Limited API
2. All macros used with PySequence_Fast are valid for use in the context of the Limited API

In either case the documentation should need to be clarified.

The only situation where no changes would result is if:

• PySequence_Fast is part of the Limited API, but must be treated the same as a regular PySequence object
  • Since only PySequence_Size and other variants can be used in the context of the Limited API

This is actually also still confusing and should be mentioned clearly.