prompt-toolkit / prompt-toolkit/python-prompt-toolkit
Private/undocumented history object properties
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 10.6k
- Forks
- 815
- PR merge metrics
- No merged PRs in 30d
Description
I wanted a way to do Buffer.history_forward() and Buffer.history_backward(), but skipping over the duplicates. I was able to implement that, but I needed to use private and/or undocumented properties, which I'd prefer not to do. I'm guessing a lot of this is just a matter of what docstrings happen to be filled in at this point, and there wasn't any specific intent with these items regarding what should/shouldn't be in the "official" API. If that's the case, I'd be happy provide pull requests to help fill some of these in. But just to confirm...
- The (documented) Buffer.go_to_history() method takes an argument for the item position, but I don't see any obvious documented way to get the max value allowed (like using the history list itself). In other words, how would a user of the API know the range of valid values that can be passed in? For now, I'm using the length of the undocumented _working_lines attribute, which is what other code within the library does.
- What is the best way to get a copy of the history itself (without unnecessary side effects -- e.g. by calling History.load_history_strings), other than using an undocumented attribute like _working_lines (or something complicated involving subclassing History)?
- I see that I can get the current position in history from the working_index attribute. It seems to be semi-documented -- It's mentioned in passing twice in the documentation, but isn't explicitly documented as a property with a description. Is it safe to use that, as far as API stability?
I can put together pull requests to address some or all of the above, if those would be welcome. Specifically:
- Adding an official property to Buffer for "working_lines" (or "history_lines", or something) that either returns
self._working_linesor something likelist(self._working_lines). - Maybe add a "history_count" or "history_length" that returns
len(self._working_lines), unless that's overkill (if the above is added anyway). - Documenting the working_index property. (Just needs a docstring?)
- If others are interested in something like a "skip_dups" flag for the history_forward() and history_backward() methods, I could include code for that as well, with doc updates.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review Buffer.go_to_history(), history_forward(), history_backward(), the History class, _working_lines, and working_index to understand the current history API. Define the intended public properties or duplicate-skipping behavior, then document and validate the agreed interface and its valid history range.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100