Metadata-Version: 2.4
Name: larzwatch
Version: 0.1.0
Summary: Portable, poll-based file and directory watching in pure Python. Detects create/modify/delete, no native backends. Zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzwatch
Project-URL: Repository, https://github.com/larz-scripter/larzwatch
Project-URL: Issues, https://github.com/larz-scripter/larzwatch/issues
Keywords: watch,file-watcher,filesystem,monitor,watchdog-alternative,polling,reload,inotify-alternative,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larzwatch

**Portable, poll-based file & directory watching. Pure Python, zero dependencies.**

Detect when files are created, modified, or deleted, and react. It works by
comparing snapshots of modification times, so it has **no native dependencies and
behaves identically on every OS** (where `watchdog` needs platform backends). Run
a blocking loop, a background thread, or - crucially for tests - call `poll()`
yourself and inspect the changes.

```python
from larzwatch import Watcher

w = Watcher("src", patterns=["*.py"])
w.on_change(lambda c: print(c.type, c.path))   # 'created' / 'modified' / 'deleted'
w.watch(interval=1)          # blocking; or w.start() for a background thread
```

## Why

- **No native backends.** `watchdog` is great but ships OS-specific extensions;
  larzwatch is pure Python and works the same everywhere - handy for CI, weird
  filesystems, and locked-down environments. Polling is perfectly fine for
  reload-on-change, build triggers, and config reloading.
- **Testable.** `poll()` returns the exact list of `Change(type, path)` since the
  last call, so you unit-test file-change logic without threads or sleeps.
- **Filtered & recursive.** `patterns=["*.py", "*.toml"]` and `recursive=True/False`.
- **Zero dependencies.**

## Install

```bash
pip install larzwatch
```

## Usage

```python
from larzwatch import Watcher

w = Watcher("config", patterns=["*.yaml"])
w.on_change(reload_config)

# blocking loop
w.watch(interval=0.5)

# or background + your own loop
w.start(interval=0.5)
...
w.stop()

# or drive it yourself (tests, cron)
for change in w.poll():
    print(change.type, change.path)
```

## Tests

```bash
python -m unittest discover -s tests -v   # 9 tests incl. create/modify/delete + background
```

## The Larz stack

One of 30+ pure-Python, zero-dependency libraries at
[github.com/larz-scripter](https://github.com/larz-scripter).

## License

MIT (c) larz-scripter
