memowatch 0.1.0__tar.gz

memowatch-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: memowatch
+Version: 0.1.0
+Summary: A modern, high-performance filesystem monitoring library for Python with async support, event debouncing, file settling detection, and content-aware diffing.
+Author-email: Yogesh V <yogeshgokul372@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yogesh12s/memowatch
+Project-URL: Documentation, https://github.com/yogesh12s/memowatch#readme
+Project-URL: Issues, https://github.com/yogesh12s/memowatch/issues
+Keywords: filesystem,monitoring,watchdog,inotify,fsevents,async
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: System :: Filesystems
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+<div align="center">
+
+# 🔭 memowatch
+**The file watcher from the year 2042.**
+
+[![Python Versions](https://img.shields.io/pypi/pyversions/memowatch.svg?style=for-the-badge&logo=python&logoColor=white)](#)
+[![PyPI version](https://img.shields.io/pypi/v/memowatch.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/memowatch/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](#)
+[![Downloads](https://img.shields.io/pypi/dm/memowatch?style=for-the-badge&color=blue)](#)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/yogeshgokul)
+
+*Because knowing a file changed is cool, but knowing your code logic changed before you even hit 'save' is cooler.* 😎
+
+</div>
+
+---
+
+## 👽 What is this?
+
+Look, standard file watchers (we love you, `watchdog` ❤️) are great if you want to be bombarded with 17 rapid-fire `FileModifiedEvent`s every time you hit `Ctrl+S` in your editor. 
+
+**`memowatch`** is a high-performance, async-first Python file watcher that actually uses its brain. It debounces events, reads your `.gitignore`, natively speaks Windows & Linux C-APIs without clunky dependencies, and—wait for it—**understands your code**.
+
+Oh, and it predicts the future. Seriously.
+
+---
+
+## ✨ Features That Will Make You Cry Tears of Joy
+
+| 🦸‍♂️ Superpower | 📖 What it actually does |
+| :--- | :--- |
+| **AST-Aware Code Watcher** 🧬 | Don't just watch files. Watch *logic*. Triggers on `FunctionAdded` or `ClassModified` while totally ignoring that extra space you accidentally typed. |
+| **Predictive Pre-Fetching** 🔮 | A built-in Markov Chain engine learns your habits and screams *"Hey, they're probably gonna edit `views.py` next!"* |
+| **Fluent "Reads-like-English" API** 🗣️ | Configure your watcher using a Builder pattern that reads so smoothly your non-coder boss might understand it. |
+| **Event Debouncing** 🛑 | Collapses the 5 events your IDE generates for a single save into **one** logical change. |
+| **File Settling Detector** 🛌 | `FileSettledEvent` waits for your giant 10GB video file to *actually finish downloading* and release its file locks before telling you to process it. |
+| **Content Hashing** 🕵️‍♂️ | SHA-256 diffing means we ignore files if you just updated the timestamp but didn't change the text. |
+| **Native `.gitignore`** 🙈 | It automatically ignores your `__pycache__` and `node_modules` so you don't have to write an exclusion regex. |
+| **Pure Python Win32 & Inotify** 🖥️ | Zero C-extensions to compile. Zero `pywin32` dependencies. Just pure, unadulterated `ctypes` magic. |
+
+---
+
+## 🚀 Quick Start (0 to 100 real quick)
+
+### Installation
+*(Requires Python 3.8+ because we have standards)*
+```bash
+pip install memowatch
+```
+
+### 🗣️ The "Reads Like English" Fluent API
+Why write boilerplate classes when you can write poetry?
+
+```python
+import memowatch
+
+def freak_out(event):
+    print(f"🚨 Whoa! You changed a function named: {event.node_name}")
+
+# Reads like plain English!
+watcher = (
+    memowatch.observe("./src")
+    .ignoring_directories()
+    .when_code_changes()
+    .specifically("FunctionAdded", "ClassModified")
+    .then_execute(freak_out)
+    .with_predictive_fetching()
+    .start_in_background()
+)
+```
+
+### 🚦 The "I just want callbacks" Sync API
+For the traditionalists among us.
+
+```python
+import memowatch
+
+class MyChillHandler(memowatch.FileSystemEventHandler):
+    def on_settled(self, event):
+        print(f"😌 Ahhh, {event.src_path} is finally done writing.")
+
+observer = memowatch.Observer(debounce_ms=300, settle_timeout_ms=1000)
+observer.schedule(MyChillHandler(), path="./my_project", recursive=True)
+observer.start()
+
+# Keep the main thread alive, grab a coffee ☕
+import time
+try:
+    while True: time.sleep(1)
+except KeyboardInterrupt:
+    observer.stop()
+```
+
+---
+
+## 🖥️ The Badass CLI
+
+Don't want to write code? Use the built-in CLI daemon.
+
+```bash
+# Watch a directory and print events like a normal person
+memowatch watch ./src
+
+# Run a daemon watcher in the background and trigger a build script
+memowatch watch ./src --background --run "python build.py"
+
+# Stop the invisible background watcher before it becomes self-aware
+memowatch stop ./src
+```
+
+---
+
+## 📖 The Glossary of Events
+
+If it happens on your hard drive, we have an event for it:
+
+| Event Class | Why you care |
+| :--- | :--- |
+| `FileCreatedEvent` | A new file appeared out of thin air. |
+| `FileSettledEvent` | **(Special ✨)** The file is completely finished writing and the locks are gone. |
+| `FileDiffEvent` | **(Special ✨)** Tells you the *exact* lines added or removed. No `git status` required. |
+| `CodeChangedEvent` | **(Special ✨)** You added/modified a Python function or class. |
+| `FilePredictedEvent` | **(Special ✨)** The AI thinks you're about to open this file. |
+| `FileDeletedEvent` | It's gone. Poof. |
+| `FileMovedEvent` | Witness protection program for files. |
+
+---
+
+<div align="center">
+Made with ❤️ and way too much caffeine by <a href="https://github.com/yogesh12s">Yogesh Gokul</a>.<br>
+<sub>(Drop a ⭐ if you think file watching should be this fun!)</sub><br><br>
+
+<a href="https://www.buymeacoffee.com/yogeshgokul" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 40px !important;width: 145px !important;" ></a>
+</div>

memowatch-0.1.0/README.md

@@ -0,0 +1,135 @@
+<div align="center">
+
+# 🔭 memowatch
+**The file watcher from the year 2042.**
+
+[![Python Versions](https://img.shields.io/pypi/pyversions/memowatch.svg?style=for-the-badge&logo=python&logoColor=white)](#)
+[![PyPI version](https://img.shields.io/pypi/v/memowatch.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/memowatch/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](#)
+[![Downloads](https://img.shields.io/pypi/dm/memowatch?style=for-the-badge&color=blue)](#)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/yogeshgokul)
+
+*Because knowing a file changed is cool, but knowing your code logic changed before you even hit 'save' is cooler.* 😎
+
+</div>
+
+---
+
+## 👽 What is this?
+
+Look, standard file watchers (we love you, `watchdog` ❤️) are great if you want to be bombarded with 17 rapid-fire `FileModifiedEvent`s every time you hit `Ctrl+S` in your editor. 
+
+**`memowatch`** is a high-performance, async-first Python file watcher that actually uses its brain. It debounces events, reads your `.gitignore`, natively speaks Windows & Linux C-APIs without clunky dependencies, and—wait for it—**understands your code**.
+
+Oh, and it predicts the future. Seriously.
+
+---
+
+## ✨ Features That Will Make You Cry Tears of Joy
+
+| 🦸‍♂️ Superpower | 📖 What it actually does |
+| :--- | :--- |
+| **AST-Aware Code Watcher** 🧬 | Don't just watch files. Watch *logic*. Triggers on `FunctionAdded` or `ClassModified` while totally ignoring that extra space you accidentally typed. |
+| **Predictive Pre-Fetching** 🔮 | A built-in Markov Chain engine learns your habits and screams *"Hey, they're probably gonna edit `views.py` next!"* |
+| **Fluent "Reads-like-English" API** 🗣️ | Configure your watcher using a Builder pattern that reads so smoothly your non-coder boss might understand it. |
+| **Event Debouncing** 🛑 | Collapses the 5 events your IDE generates for a single save into **one** logical change. |
+| **File Settling Detector** 🛌 | `FileSettledEvent` waits for your giant 10GB video file to *actually finish downloading* and release its file locks before telling you to process it. |
+| **Content Hashing** 🕵️‍♂️ | SHA-256 diffing means we ignore files if you just updated the timestamp but didn't change the text. |
+| **Native `.gitignore`** 🙈 | It automatically ignores your `__pycache__` and `node_modules` so you don't have to write an exclusion regex. |
+| **Pure Python Win32 & Inotify** 🖥️ | Zero C-extensions to compile. Zero `pywin32` dependencies. Just pure, unadulterated `ctypes` magic. |
+
+---
+
+## 🚀 Quick Start (0 to 100 real quick)
+
+### Installation
+*(Requires Python 3.8+ because we have standards)*
+```bash
+pip install memowatch
+```
+
+### 🗣️ The "Reads Like English" Fluent API
+Why write boilerplate classes when you can write poetry?
+
+```python
+import memowatch
+
+def freak_out(event):
+    print(f"🚨 Whoa! You changed a function named: {event.node_name}")
+
+# Reads like plain English!
+watcher = (
+    memowatch.observe("./src")
+    .ignoring_directories()
+    .when_code_changes()
+    .specifically("FunctionAdded", "ClassModified")
+    .then_execute(freak_out)
+    .with_predictive_fetching()
+    .start_in_background()
+)
+```
+
+### 🚦 The "I just want callbacks" Sync API
+For the traditionalists among us.
+
+```python
+import memowatch
+
+class MyChillHandler(memowatch.FileSystemEventHandler):
+    def on_settled(self, event):
+        print(f"😌 Ahhh, {event.src_path} is finally done writing.")
+
+observer = memowatch.Observer(debounce_ms=300, settle_timeout_ms=1000)
+observer.schedule(MyChillHandler(), path="./my_project", recursive=True)
+observer.start()
+
+# Keep the main thread alive, grab a coffee ☕
+import time
+try:
+    while True: time.sleep(1)
+except KeyboardInterrupt:
+    observer.stop()
+```
+
+---
+
+## 🖥️ The Badass CLI
+
+Don't want to write code? Use the built-in CLI daemon.
+
+```bash
+# Watch a directory and print events like a normal person
+memowatch watch ./src
+
+# Run a daemon watcher in the background and trigger a build script
+memowatch watch ./src --background --run "python build.py"
+
+# Stop the invisible background watcher before it becomes self-aware
+memowatch stop ./src
+```
+
+---
+
+## 📖 The Glossary of Events
+
+If it happens on your hard drive, we have an event for it:
+
+| Event Class | Why you care |
+| :--- | :--- |
+| `FileCreatedEvent` | A new file appeared out of thin air. |
+| `FileSettledEvent` | **(Special ✨)** The file is completely finished writing and the locks are gone. |
+| `FileDiffEvent` | **(Special ✨)** Tells you the *exact* lines added or removed. No `git status` required. |
+| `CodeChangedEvent` | **(Special ✨)** You added/modified a Python function or class. |
+| `FilePredictedEvent` | **(Special ✨)** The AI thinks you're about to open this file. |
+| `FileDeletedEvent` | It's gone. Poof. |
+| `FileMovedEvent` | Witness protection program for files. |
+
+---
+
+<div align="center">
+Made with ❤️ and way too much caffeine by <a href="https://github.com/yogesh12s">Yogesh Gokul</a>.<br>
+<sub>(Drop a ⭐ if you think file watching should be this fun!)</sub><br><br>
+
+<a href="https://www.buymeacoffee.com/yogeshgokul" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 40px !important;width: 145px !important;" ></a>
+</div>

memowatch-0.1.0/memowatch/__init__.py

@@ -0,0 +1,99 @@
+"""
+memowatch - A modern, high-performance filesystem monitoring library for Python.
+
+Features beyond standard watchdog:
+  - First-class async/await support (async iterators)
+  - Built-in event debouncing & coalescing
+  - File settling / lock detection (FileSettledEvent)
+  - Content-aware SHA-256 diffing
+  - Native .gitignore parser + glob/regex/size filters
+  - Pure-Python Windows backend via ctypes (no pywin32)
+  - CLI with command runner and JSON streaming
+
+Usage:
+    # Sync / callback API
+    import memowatch
+
+    class MyHandler(memowatch.FileSystemEventHandler):
+        def on_created(self, event):
+            print(f"Created: {event.src_path}")
+
+    observer = memowatch.Observer()
+    observer.schedule(MyHandler(), path="./src", recursive=True)
+    observer.start()
+
+    # Async API
+    import asyncio
+
+    async def main():
+        async with memowatch.async_watch("./src") as stream:
+            async for event in stream:
+                print(event)
+
+    asyncio.run(main())
+"""
+
+__version__ = "0.1.0"
+__author__ = "Yogesh Gokul <yogeshgokul372@gmail.com>"
+
+# Display author information on import as requested
+print(f"Loaded memowatch v{__version__} - Built with ❤️ by {__author__}")
+
+from memowatch.core.events import (
+    FileSystemEvent,
+    FileCreatedEvent,
+    FileModifiedEvent,
+    FileDeletedEvent,
+    FileMovedEvent,
+    FileSettledEvent,
+    DirCreatedEvent,
+    DirModifiedEvent,
+    DirDeletedEvent,
+    DirMovedEvent,
+    EVENT_TYPE_CREATED,
+    EVENT_TYPE_MODIFIED,
+    EVENT_TYPE_DELETED,
+    EVENT_TYPE_MOVED,
+    EVENT_TYPE_SETTLED,
+)
+
+from memowatch.core.observer import (
+    FileSystemEventHandler,
+    Observer,
+    async_watch,
+)
+
+from memowatch.fluent import observe
+
+__all__ = [
+    # Version
+    "__version__",
+    # Events
+    "FileSystemEvent",
+    "FileCreatedEvent",
+    "FileModifiedEvent",
+    "FileDeletedEvent",
+    "FileMovedEvent",
+    "FileSettledEvent",
+    "CodeChangedEvent",
+    "FilePredictedEvent",
+    "FileDiffEvent",
+    "DirCreatedEvent",
+    "DirModifiedEvent",
+    "DirDeletedEvent",
+    "DirMovedEvent",
+    "EVENT_TYPE_CREATED",
+    "EVENT_TYPE_MODIFIED",
+    "EVENT_TYPE_DELETED",
+    "EVENT_TYPE_MOVED",
+    "EVENT_TYPE_SETTLED",
+    "EVENT_TYPE_DIFF",
+    "EVENT_TYPE_CODE_CHANGED",
+    "EVENT_TYPE_PREDICTED",
+    # Observer
+    "FileSystemEventHandler",
+    "Observer",
+    "async_watch",
+    # Fluent API
+    "observe",
+]

memowatch-0.1.0/memowatch/backends/__init__.py

@@ -0,0 +1,3 @@
+"""
+memowatch.backends - Backend sub-package init.
+"""

memowatch-0.1.0/memowatch/backends/base.py

@@ -0,0 +1,78 @@
+"""
+memowatch.backends.base
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Abstract base class for all platform backends.
+
+A backend is responsible for:
+  1. Watching a single directory (optionally recursively).
+  2. Emitting raw ``FileSystemEvent`` objects via a callback.
+  3. Running in a background thread managed by the ``Observer``.
+"""
+
+from __future__ import annotations
+
+import abc
+import threading
+from typing import Callable, Optional
+
+from memowatch.core.events import FileSystemEvent
+
+
+class BaseBackend(abc.ABC):
+    """Abstract base class that every platform backend must implement."""
+
+    def __init__(
+        self,
+        path: str,
+        recursive: bool = False,
+        callback: Optional[Callable[[FileSystemEvent], None]] = None,
+    ) -> None:
+        self.path = path
+        self.recursive = recursive
+        self.callback = callback
+        self._stop_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    # ── Public API ────────────────────────────
+
+    def start(self) -> None:
+        """Start watching in a background thread."""
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._run, daemon=True, name=f"memowatch-{self.name}"
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Signal the backend to stop and wait for its thread to finish."""
+        self._stop_event.set()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=5.0)
+
+    def is_alive(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    # ── Emit helper ───────────────────────────
+
+    def emit(self, event: FileSystemEvent) -> None:
+        """Forward an event to the registered callback."""
+        if self.callback is not None:
+            self.callback(event)
+
+    # ── Abstract interface ────────────────────
+
+    @property
+    @abc.abstractmethod
+    def name(self) -> str:
+        """Short human-readable name for this backend (e.g. 'win32', 'polling')."""
+
+    @abc.abstractmethod
+    def _run(self) -> None:
+        """Main loop executed in the background thread.
+
+        Implementations should watch ``self.path``, detect changes, and call
+        ``self.emit(event)`` for each one.  The loop must check
+        ``self._stop_event.is_set()`` periodically and return when it becomes
+        ``True``.
+        """