I need to practice my backport cherry picking (and corresponding pull requesting). I have a simple case in mind. Stack operation activity described in the file library/dis.rst mentions both STACK.append and STACK.push as the inverse of STACK.pop. I’m old-fashioned and prefer push to append, but if the concensus is to use append, I’ll change push to append. Looking at git blame output, I see both @markshannon and @MatthieuDartiailh associated with the relevant lines.
This is just an exercise in improving my git fu. I’m happy to do some more activity in dis.rst, but for the moment just want to generate a PR I know will hiccup when bedevere attempts the automatic backport. Some changes would are associated with 3.12, so would fail to apply cleanly to 3.11.
I think it makes sense to use just one term for the operation. STACK is introduced with:
In the following, We will refer to the interpreter stack as STACK and describe
operations on it as if it was a Python list.
so .append makes sense to me, though I could see using .push if it’s explained at the beginning. Make the PR, I’m sure you’ll get help working it through.
Fine, you want lists, then maybe STACK.push should be changed to STACK.append?
You’re letting implementation details bleed into user-facing documentation. If it’s conceptually a stack, then use typical stack nomenclature to describe it.
I’m simply pointing out that there’s already a statement at the top of the page explaining how STACK is being used. It’s not leaking implementation details because the stack is not actually a Python list. It’s being described on this page in terms familiar to the readers (that is, Python programmers).
As I explained on the issue and PR, STACK is not a ‘stack’ as usually defined as the code examples also perform non-stack operations (indexing and slicing). Also, as far as I looked, the code examples are executable Python code and STACK.push() is not.
25 years ago, when I proposed the addition of list.pop, I pointed out that if one were using a list _ as a stack, one could define push = _.append and pop = _.pop and thereafter use push and pop (or the same with prefixes or suffixes added). That approach is not applicable to STACK precisely because it is not just used as a stack. I suppose one could define the concept “indexable stack”