curses-fzf 0.2.0__tar.gz

curses_fzf-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: Python Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Run pytest
+        run: |
+          pytest -v --cov=curses_fzf --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}

curses_fzf-0.2.0/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+.vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# additional
+.ignore/

curses_fzf-0.2.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# CHANGELOG
+
+All versions below are listed in reverse chronological order.
+
+## [0.2.0](https://github.com/Heiko-san/curses_fzf/releases/tag/0.2.0) (2026-03-02)
+
+### Breaking Changes
+
+- Complete rework of fuzzyfinder to object oriented version, to actually make FuzzyFinder testable.
+  - `fuzzyfinder` function removed, `FuzzyFinder` class added.
+  - `FuzzyFinder` mostly takes the same parameters as `fuzzyfinder` before.
+  - Use object's `find` method to provide the actual data list and retrieve the result.
+
+## [0.1.0](https://github.com/Heiko-san/curses_fzf/releases/tag/0.1.0) (2026-02-26)
+
+### Features
+
+- First basic functionality

curses_fzf-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Heiko Finzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

curses_fzf-0.2.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: curses-fzf
+Version: 0.2.0
+Summary: A pure python implementation of fzf (fuzzyfinder) with some additional features using the curses library.
+Project-URL: Homepage, https://github.com/Heiko-san/curses_fzf
+Project-URL: Documentation, https://github.com/Heiko-san/curses_fzf/blob/main/README.md
+Project-URL: Repository, https://github.com/Heiko-san/curses_fzf.git
+Project-URL: Issues, https://github.com/Heiko-san/curses_fzf/issues
+Project-URL: Changelog, https://github.com/Heiko-san/curses_fzf/blob/main/CHANGELOG.md
+Author-email: Heiko Finzel <heikofinzel@googlemail.com>
+Maintainer-email: Heiko Finzel <heikofinzel@googlemail.com>
+License-Expression: MIT
+Keywords: cli,curses,filter,finder,fuzzy,fuzzyfinder,fzf,python,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Text Processing :: Filters
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# curses_fzf
+
+A pure Python implementation of fzf (fuzzyfinder) using the curses library -
+no external `fzf` binary required.
+
+Although there are many good fzf libraries available, they all have one thing in common:
+They are wrappers to the shell tool `fzf`.
+
+This is not inherently bad, but has one major downside:
+It does not integrate well into Python code.
+
+- What if you want to fuzzy-find over a list of dicts or objects?
+- What if you want to pre-select items (e.g. tags already set for a resource,
+that could be unset while selecting new ones)?
+- What if you want to display additional information along with the entry to fuzzy-find on?
+- What if you want to customize the fuzzy-finder algorithm?
+
+To all of the above questions this module is the answer.
+
+# Features
+
+## Multi Select Mode
+
+```py
+from curses_fzf import FuzzyFinder, CursesFzfAborted
+
+fzf = FuzzyFinder(multi=True)
+try:
+    choices = fzf.find(data)
+except CursesFzfAborted:
+    print("Fuzzy finder aborted by user.")
+else:
+    for item in choices:
+        print(item)
+```
+
+In its simplest form, `FuzzyFinder` only requires the `data` list to present to the user,
+a single item can then be chosen from the list.
+
+Setting `multi` to `True` will allow you to select multiple items using the `TAB` key.
+
+In any case the returned result is a list of strings.
+It will contain exactly one items in single-selection mode and `0..n` in
+multi-selection mode.
+
+If selection is aborted a `CursesFzfAborted` exception is raised, so single
+selection mode can't return an empty list.
+
+## Query Pre-Seeding
+
+```py
+from curses_fzf import FuzzyFinder
+
+fzf = FuzzyFinder(query="the in")
+choices = fzf.find(data)
+```
+
+By default `FuzzyFinder` will start with an empty `query`.
+The unfiltered list will then be presented in its original order.
+
+If the user enters a filter query the list is reduced to the matching items,
+sorted by match score (see `score` function).
+
+The `query` can also be pre-seeded with a given string.
+The user is still able to fully modify the query, including completely clearing it.
+The parameter can be given to `FuzzyFinder` constructor or the object's `find` method.
+
+![image](https://github.com/Heiko-san/curses_fzf/releases/download/0.1.0/simple.png)
+
+## Title Prompting The User
+
+```py
+from curses_fzf import FuzzyFinder
+
+fzf = FuzzyFinder(title="Select an item:")
+choices = fzf.find(data)
+```
+
+Instead of "ITEMS", you can provide a custom header for the `FuzzyFinder` window.
+The parameter can be given to `FuzzyFinder` constructor or the object's `find` method.
+
+## Display Function
+
+```py
+from curses_fzf import FuzzyFinder
+
+def display_name_property(item: Any) -> str:
+    return item.name
+
+fzf = FuzzyFinder(display=display_name_property)
+choices = fzf.find(data)
+```
+
+Since `curses_fzf` allows you to work with lists of any type of items,
+you may want to define a custom behavior of how it displays your items.
+In the above example we have a list of objects,
+using the `name` property to represent each item in `FuzzyFinder` listing.
+
+The `display` function must return a single line of text.
+A `CursesFzfAssertion` exception will be raised, if the function returns multi-line text.
+If you want to present more complex information,
+have a look at the `preview` function.
+
+The default behavior is to stringify the item provided:
+
+```py
+FuzzyFinder(display=lambda item: str(item))
+```
+
+## Preselect Function
+
+```py
+from curses_fzf import FuzzyFinder, ScoringResult
+
+def preselect_items(item: Any, scoring_result: ScoringResult) -> bool:
+    return item in PREFERRED_ITEMS
+
+fzf = FuzzyFinder(multi=True, preselect=preselect_items)
+choices = fzf.find(data)
+```
+
+If you use `FuzzyFinder` in multi-select mode, you can pre-select some items
+using the `preselect` function.
+This function is expected to return `True` if the item should be selected.
+
+The default implementation always returns `False`.
+
+![image](https://github.com/Heiko-san/curses_fzf/releases/download/0.1.0/multi_with_preview.png)
+
+## Preview Function
+
+```py
+import curses
+from curses_fzf import FuzzyFinder, ScoringResult, Color, ColorTheme
+
+def my_preview(preview_window: curses.window, color_theme: ColorTheme, item: Any, result: ScoringResult) -> str:
+    preview_window.addstr(1, 1, item.description, curses.color_pair(Color.RED))
+    return ""
+
+fzf = FuzzyFinder(preview=my_preview)
+choices = fzf.find(data)
+```
+
+The `preview` function (default `None`), if set, will show a preview window on the
+right side of the `FuzzyFinder` window.
+You can use this window to present additional information about the item.
+For example you can `yaml.dump` `dict` items.
+
+There are two possible ways to use this function:
+
+Either you ignore the provided `preview_window` and simply return a string,
+that can also be multi-line.
+The `FuzzyFinder` will take care of the text not leaking out of the window boundaries.
+
+Or you return an empty string and use `preview_window` to modify the curses window manually.
+If you do so, you should ensure to handle window boundaries correctly
+to avoid crashes, e.g. on terminal resizing.
+See `ColorTheme` section for information on coloring, the selected `color_theme`
+is also provided to the `preview` function.
+
+See `examples` folder for more detailed code snippets.
+
+Not only the `item` is provided, but also the `ScoringResult`.
+This allows to display scoring related information.
+
+You can use `preview_window_percentage` parameter of `FuzzyFinder` to define the
+width of the preview window.
+The default value is `40` percent of the terminal window.
+Don't worry that the preview window might hide portions of your items,
+you can toggle the preview window any time using `Ctrl + P`.
+
+![image](https://github.com/Heiko-san/curses_fzf/releases/download/0.1.0/simple_with_preview.png)
+
+## Scoring Function
+
+```py
+from curses_fzf import FuzzyFinder, ScoringResult
+
+def my_scoring(query: str, candidate: str) -> ScoringResult:
+    sr = ScoringResult(query, candidate)
+    # ... scoring logic
+    sr.score = 100
+    # ...
+    return sr
+
+fzf = FuzzyFinder(score=my_scoring)
+choices = fzf.find(data)
+```
+
+The `curses_fzf` module comes with built-in scoring functions (default `scoring_full_words`).
+Scoring determines if an item is considered to match the `query` the user entered.
+The higher the score the higher the item gets sorted among the matches.
+If score is 0 the item is considered to not be a match, it will not be displayed in the list at all.
+
+A scoring function retrieves the user `query` as its first argument and the
+`candidate` to match as the second.
+The `candidate` is the `display` string of the item in question.
+
+The function is supposed to return a `ScoringResult`.
+
+### ScoringResult
+
+The only important thing about the `ScoringResult` is its `score` field.
+Although there are helper functions, you are free to modify this field directly
+as your scoring function requires.
+If the value of this field is `0`, the `candidate` will not be displayed in the list of matches.
+A higher value indicates a better match and will prioritize the item in the sorted list of results.
+
+The second field to notice is `matches`, which is a list of tuples containing the
+starting index and length of all matches inside the `candidate` string.
+If set, this information will be used by `FuzzyFinder` to colorize the matched substrings
+in the list of query results.
+
+The intended way to set those fields is `sr.add_match(position: int, length: int, score: int)`.
+The first two parameters represent one tuple appended to the `matches` list.
+The `score` parameter is the score associated with the partial match that `position`
+and `length` identifies, it is added to the `score` field of this `ScoringResult`.
+
+`ScoringResult` also assists with tokenization of the `query` and `candidate`,
+providing the fields `query`, `query_lower`, `query_words_with_index`, `candidate`,
+`candidate_lower` and `candidate_words_with_index`.
+
+## ColorTheme Customization
+
+```py
+from curses_fzf import FuzzyFinder, ColorTheme, Color
+
+fzf = FuzzyFinder(color_theme=ColorTheme(text=Color.CYAN))
+choices = fzf.find(data)
+```
+
+`ColorTheme` can be used to customize text colors, e.g. to increase readability.
+Use the indexes defined via `Color` enum.
+If you want to register your own `color_pairs`, the indexes 1 to 29 are safe to use.
+
+## Autoreturn
+
+```py
+from curses_fzf import FuzzyFinder
+
+fzf = FuzzyFinder(multi=True, query="foo", autoreturn=3)
+choices = fzf.find(data)
+```
+
+If the list provided contains exactly the number of entries defined by `autoreturn`,
+the `FuzzyFinder` will return those entries without user interaction.
+
+This is most useful in combination with a pre-seed `query`,
+in which case the number of matches is considered.
+
+The default `0` means "don't autoreturn".
+If `multi=True` the number given as `autoreturn`'s value is checked against the filter results.
+If `multi=False` the number given as `autoreturn`'s value is not relevant,
+the match will be returned, if there is only one.
+
+## Page Size
+
+The `page_size` parameter (default `10`) defines the number of entries that are
+skipped by the keys `PAGE_UP` and `PAGE_DOWN`.
+
+## Help
+
+Press `F1` to display a help screen with a list of keyboard actions.
+
+![image](https://github.com/Heiko-san/curses_fzf/releases/download/0.2.0/help.png)
+
+## Exceptions
+
+`CursesFzfException` is the base exception type that can catch any `curses_fzf` exceptions.
+
+If the user aborts the selection using `ESC` or `Ctrl + C`, a `CursesFzfAborted` is raised.
+In single selection mode the returned list will always contain an item,
+since otherwise this exception would have been raised.
+In multi selection mode the returned list can be empty,
+if the user accepts an empty selection with `Enter`.
+
+`CursesFzfAssertion` will be raised if some contracts are broken,
+e.g. if the `display` function returns multiline text.
+
+A special case of this assertion is `CursesFzfIndexOutOfBounds`, which is raised e.g.
+if the calls to `query` modification functions use invalid indexes.
+
+## Keymap And More
+
+```py
+from curses_fzf import FuzzyFinder
+
+fzf = FuzzyFinder()
+fzf.keymap[curses.KEY_F2] = lambda: fzf.kb_move_items_cursor_relative(2)
+choices = fzf.find(data)
+```
+
+`FuzzyFinder` is designed to allow for deep customization.
+
+See `examples` folder for more detailed code snippets, e.g. on how to define
+your own keyboard actions.