Should we update the documentation for f_lasti?

The documentation says f_lasti is

index of last attempted instruction in bytecode

However, due to optimizations like PREDICT(op), sometimes f_lasti is not updated in time, thus can be several instructions before the actual “last attempted instruction”.

I discussed with @xiangz about this, he said I should not rely on implementation details. However, since CPython chose to expose this information, shouldn’t the documentation at least mention the existence of those edge cases?

Thanks for the suggestion @laike9m, I think it would be worth opening an issue on bugs.python.org for further discussion of a proposed change to the documentation. For future reference, this topic is best suited towards the “Ideas” section; as it implies a suggested change to Python. I’ll move the topic accordingly.

We typically avoid mentioning every possible edge case in the docs, as it could easily result in an excessive amount of distracting information for readers. The docs focus on the most common cases and are written in consideration of the most useful information for the majority of Python users to be aware of; while maintaining as much accuracy as reasonably possible.

IMO, a better solution would be to modify the wording of the existing description in a way that focuses primarily on the general cases without being entirely incorrect for the edge cases.

The final decision to make any changes or not typically is on the maintainers/experts for the respective section of CPython being changed. In this case, the maintainer of the inspect module is @yselivanov. I would advise opening a bpo issue, and adding him to the nosy list.

I would also recommend having a specific proposal in mind, detailing the changes you think should be made. This will most likely lead to further discussion, approval, or rejection depending on what Yury (and potentially other core developers) think of the proposed changes.

There is no 100% guaranteed response time (since almost everyone in the Python development community does so voluntarily), but typically you’ll receive a response within a few weeks as long as the proposal itself is very clearly defined and not overly complex.

Thanks Kyle, it is very helpful to have your suggestions. Honestly, I did not create a bpo because I’m not really sure if this is a bug, or the best way to update the doc.

It is more of a question, and to gather opionions from relevant people. I’m glad to hear what Yury thinks about this problem.

No problem. Discuss > Ideas is a good place to bring up the idea (alternatively python-ideas, I personally prefer Discuss), but we generally use bpo to discuss the actual changes, once the issue itself becomes concrete. Next, a PR can be opened on GitHub that is attached to the bpo issue. If the maintainer/expert of the area approves of the changes (or any core dev for more minor changes), the PR can be merged. For more information on our PR workflow, see https://devguide.python.org/pullrequest/.

This process applies to pretty much any significant changes, including to the documentation or code; regardless of whether it’s a bugfix or an enhancement. I’d personally consider this change to be an enhancement, since the current version seems to be correct for the majority of cases.

I think this suggestion is concrete enough that it could be opened as an issue on bpo if you’re interested in doing so. I would recommend having a rough idea of the actual changes you’d like to make, as this will speed up the process significantly. Just make sure to add Yury to the nosy list on bpo, feel free to add me as well.

Note: The stage of opening a topic on Discuss > Ideas or python-ideas is optional. It’s never a bad idea to do so, but it’s certainly not a required step.