Metadata-Version: 2.4
Name: flitz
Version: 0.0.9
Summary: A fast, keyboard-friendly file manager (Fast Location / Indexing / Traversal Zone).
Keywords: file browser,file explorer,file manager,qt
Author-email: Martin Thoma <info@martin-thoma.de>
Maintainer-email: Martin Thoma <info@martin-thoma.de>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-Expression: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Desktop Environment :: File Managers
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: pillow
Requires-Dist: pydantic>=2
Requires-Dist: pyside6>=6.8
Requires-Dist: pyyaml
Project-URL: Bug Reports, https://github.com/MartinThoma/flitz/issues
Project-URL: Changelog, https://github.com/MartinThoma/flitz/blob/main/CHANGELOG.md
Project-URL: Documentation, https://flitz.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/MartinThoma/flitz

<p align="center">
  <img src="https://raw.githubusercontent.com/MartinThoma/flitz/main/docs/_static/logo.png" alt="flitz logo" width="120">
</p>

<h1 align="center">flitz</h1>

<p align="center">
  <strong>A fast, keyboard-friendly file manager written in Python.</strong><br>
  <em>Fast Location / Indexing / Traversal Zone</em>
</p>

<p align="center">
  <a href="https://pypi.org/project/flitz/"><img src="https://img.shields.io/pypi/v/flitz.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/flitz/"><img src="https://img.shields.io/pypi/pyversions/flitz.svg" alt="Supported Python versions"></a>
  <a href="https://github.com/MartinThoma/flitz/actions/workflows/ci.yaml"><img src="https://github.com/MartinThoma/flitz/actions/workflows/ci.yaml/badge.svg" alt="CI"></a>
  <a href="https://flitz.readthedocs.io/en/latest/"><img src="https://readthedocs.org/projects/flitz/badge/?version=latest" alt="Documentation"></a>
  <a href="https://github.com/MartinThoma/flitz/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
</p>

![Screenshot of flitz](https://raw.githubusercontent.com/MartinThoma/flitz/main/docs/_static/flitz.png)

## Features

- **Clean Qt interface** with a sidebar for bookmarks and file systems, file type
  icons, and human-readable sizes.
- **Sortable columns** — click a column header to sort by name, size, type, or
  modification date.
- **Keyboard first** — search, rename, create, delete, copy and paste without
  touching the mouse. All shortcuts can be changed.
- **Recursive search** within the current folder.
- **Customizable** colors, fonts, context menu, and key bindings via a simple
  YAML file.
- **Remote file systems** such as FTP, next to your local disk.
- **Extensible** — add context menu entries and file systems with plugins.

## Installation

flitz requires Python 3.10 or newer and runs on Linux and macOS.

```bash
pipx install flitz
```

Alternatively, use `uv tool install flitz` or `pip install flitz`.

## Usage

```bash
flitz                 # open the current folder
flitz ~/Documents     # open a specific folder
flitz --list-fonts    # fonts which can be used in the configuration
flitz --version
```

### Keyboard shortcuts

| Action                    | Shortcut                                      |
| ------------------------- | --------------------------------------------- |
| Open file / enter folder  | <kbd>Enter</kbd> or double-click              |
| Go to parent folder       | <kbd>Backspace</kbd>                          |
| Refresh                   | <kbd>F5</kbd>                                 |
| Search                    | <kbd>Ctrl</kbd>+<kbd>F</kbd>                  |
| Leave search              | <kbd>Esc</kbd>                                |
| Rename                    | <kbd>F2</kbd>                                 |
| Create folder             | <kbd>F7</kbd>                                 |
| Delete                    | <kbd>Delete</kbd>                             |
| Copy / paste              | <kbd>Ctrl</kbd>+<kbd>C</kbd> / <kbd>Ctrl</kbd>+<kbd>V</kbd> |
| Show hidden files         | <kbd>Ctrl</kbd>+<kbd>H</kbd>                  |
| Increase / decrease font  | <kbd>Ctrl</kbd>+<kbd>+</kbd> / <kbd>Ctrl</kbd>+<kbd>-</kbd> |
| Context menu              | Right-click                                   |
| Open the settings         | <kbd>Ctrl</kbd>+<kbd>M</kbd>                  |

## Configuration

flitz reads `~/.flitz.yml`. Press <kbd>Ctrl</kbd>+<kbd>M</kbd> to create and open
it. Every setting is optional:

```yaml
font: Ubuntu
font_size: 11
background_color: "#ffffff"
text_color: "#1f2328"
selection:
  background_color: "#16778f"
  text_color: "#ffffff"
show_hidden_files: false
keybindings:
  search: <Control-f>
  rename_item: <F2>
file_systems:
  - name: rebex
    type: FTP
    hostname: test.rebex.net
```

See the [documentation](https://flitz.readthedocs.io/en/latest/user/customization.html)
for all options, including sharing themes with `external_config`.

## Plugins

Other packages can extend flitz via
[entry points](https://packaging.python.org/en/latest/specifications/entry-points/):

- `flitz` — a `flitz.context_menu.ContextMenuItem` for the context menu
- `flitz.file_systems` — a `flitz.file_systems.FileSystem` subclass

```toml
[project.entry-points.flitz]
compress = "my_plugin:compress_menu_item"
```

## Development

flitz uses [uv](https://docs.astral.sh/uv/) to manage its dependencies:

```bash
git clone https://github.com/MartinThoma/flitz.git
cd flitz
uv sync               # create .venv with all development dependencies
uv run flitz          # start flitz
make test             # run the tests
make lint             # ruff + mypy
pre-commit install    # run the checks before every commit
```

### Releasing

1. Update `flitz/_version.py` and `CHANGELOG.md` in a `REL: x.y.z` commit.
2. Create a tag with the release notes as tag message body: `git tag -s x.y.z`
3. Push the tag: `git push origin x.y.z`

The [release workflow](https://github.com/MartinThoma/flitz/blob/main/.github/workflows/release.yaml)
publishes the package to PyPI and creates a GitHub release.

## License

flitz is licensed under the [MIT License](https://github.com/MartinThoma/flitz/blob/main/LICENSE).

