Metadata-Version: 2.4
Name: py-ntfs-quick-index
Version: 0.1.7
Summary: Fast NTFS indexing and search for Windows amd64.
Project-URL: Homepage, https://github.com/GGN-2015/py-ntfs-quick-index
Author: py-ntfs-quick-index contributors
License-Expression: MIT
License-File: LICENSE
Keywords: index,ntfs,sqlite,usn,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Desktop Environment :: File Managers
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: py-admin-launch>=0.1.3
Requires-Dist: tqdm>=4.66
Description-Content-Type: text/markdown

# py-ntfs-quick-index

Fast Windows NTFS indexing and search for amd64 machines.

`pnqi` uses NTFS MFT enumeration for initial indexing and the NTFS USN Journal
for incremental refreshes. Indexes are stored as SQLite files named
`pnqi.index.sqlite` in the volume root, for example `C:\pnqi.index.sqlite`.

## Requirements

- Windows only
- amd64 / x86_64 CPU only
- Administrator privileges
- NTFS volumes only
- Python 3.10+

The program elevates only at startup through
[`py-admin-launch`](https://pypi.org/project/py-admin-launch/). Internal library
calls require the already-elevated process and do not trigger additional UAC
prompts.

## Install

Install the latest release from PyPI:

```powershell
python -m pip install py-ntfs-quick-index
```

Upgrade an existing install:

```powershell
python -m pip install --upgrade py-ntfs-quick-index
```

For local development from a checkout:

```powershell
python -m pip install -e .
```

## CLI

Create or replace an index for a folder:

```powershell
pnqi index C:\
```

Search with `*` wildcards. `*` matches any string, including `\`. Results are
sorted by displayed size descending.

```powershell
pnqi search "C:\Users\*\Desktop\*.pdf"
```

Show descendants sorted by recursive size:

```powershell
pnqi sizes C:\Users --limit 100
```

Show only direct children:

```powershell
pnqi sizes C:\Users --direct
```

CLI progress bars use `tqdm`, and `Ctrl+C` cancels cleanly.

## GUI

```powershell
pnqi-gui
```

The GUI supports creating indexes, searching wildcard paths, browsing indexed
folders, and viewing recursive sizes. The folder browser shows each direct
child's share of the current folder's total recursive size; search and size
result lists stay focused on size, type, time, and path. During long operations
the interface is locked except for Cancel. Long tasks run in a worker process so
NTFS MFT scans and indexed searches do not stall the Tk event loop. Search
results stream back in small batches so large result sets remain cancellable,
and the Max rows control limits how many sorted matches are displayed. Cancelled
index builds write only to a temporary SQLite file and do not replace the
existing index.

## Build a GUI EXE

To build the GUI as a single-file Windows executable from a checkout:

```bat
scripts\build_gui_exe.bat
```

The script creates an isolated build virtual environment under `.build`, installs
the current project and PyInstaller there, and writes `dist\exe\pnqi-gui.exe`.
It does not change the Poetry package configuration or runtime dependencies.

## Incremental Updates

On startup, and before searches or browsing, `pnqi` checks existing
`pnqi.index.sqlite` files and replays USN Journal changes into SQLite. Folder
sizes are maintained as recursive sums of all descendant files; older indexes are
recalculated once when opened. Incremental updates replace stale records that
still occupy a normalized path before writing the new file record. If the USN
Journal was recreated or no longer contains the required history, `pnqi` reports
that the index must be recreated.
