Skip to content

DOC: Document the seven text selection strategies missing from the Selectively Converting page #4497

Open

Description

@romanlutz

The Selectively Converting page lists seven selection strategies in its table (section 4, "Select Words or Characters Programmatically"). pyrit.converter exports seven more that appear nowhere in the docs:

Strategy Level What it selects
RegexSelectionStrategy(pattern=...) characters The first regex match
KeywordSelectionStrategy(keyword=..., context_before=0, context_after=0, case_sensitive=True) characters A keyword, optionally with surrounding characters
PositionSelectionStrategy(start_proportion=..., end_proportion=...) characters A range given as proportions of the text length
ProportionSelectionStrategy(proportion=..., anchor="start", seed=None) characters A proportion of the text anchored at the start, end, middle or a random position
RangeSelectionStrategy(start_proportion=0.0, end_proportion=1.0) characters A range given as proportions of the text length
AllWordsSelectionStrategy() words Every word (the default for word-level converters)
ContentWordSelectionStrategy(max_words=2, skip_first=1, ...) words Content words, skipping stopwords and short words

All of them are defined in pyrit/converter/text_selection_strategy.py.

What to change

  • Add the seven strategies to the table in section 4 of doc/code/converters/6_selectively_converting.py.
  • Add one short runnable example for a character-level strategy (for example KeywordSelectionStrategy with context) and one for ContentWordSelectionStrategy. Follow the existing examples on the page, which assert the expected output. None of these strategies needs an LLM or credentials, so the examples can be executed locally.
  • PositionSelectionStrategy and RangeSelectionStrategy have the same one-line docstring ("Selects text based on proportional start and end positions"). Work out from the code how they differ and state it in the table. If they do not differ, say so in the PR; do not change the code in this PR.

Done when

  • Every selection strategy exported from pyrit.converter appears in the table.
  • The two new examples run and their assertions pass.
  • The .py and .ipynb files match, and pre-commit passes.

Implementation notes

  • Doc pages under doc/code/ are jupytext pairs: a .py file and a matching .ipynb. Change both. doc/contributing/7_notebooks.md and .github/instructions/docs.instructions.md explain how.
  • Read the class and its unit tests first, and describe only what the code does today.
  • Keep the text short and concrete. Lead with when someone would use the class, then show the smallest example that works.
  • pre-commit runs the doc validation hooks; they must pass.

How to contribute

  • Claim it first. Before you start, comment on this issue to say you are taking it.
  • First comment wins. If yours is the first claim comment, go ahead and open a PR; you do not need to wait for a reply. If someone has already commented, this issue is taken, so please pick a different one.
  • Link this issue in your PR description.

Activity

  1. jyotshana666 commented on Nov 21, 2026

    @jyotshana666

    I'd like to take this one. I'll read text_selection_strategy.py and its unit tests first, add the seven strategies to the table, write the two runnable examples (KeywordSelectionStrategy and ContentWordSelectionStrategy), investigate whether PositionSelectionStrategy and RangeSelectionStrategy actually differ, sync the .ipynb via jupytext, and run pre-commit before opening the PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions