prompt-toolkit / prompt-toolkit/python-prompt-toolkit

Private/undocumented history object properties

Open
#1,527 0 comments 0 reactions 0 assignees View on GitHub

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_lines or something like list(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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.