memowatch 0.1.0__py3-none-any.whl

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/backends/__init__.py

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

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``.
+        """

memowatch/backends/linux.py

@@ -0,0 +1,259 @@
+"""
+memowatch.backends.linux
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Native Linux backend using ``inotify`` via ``ctypes``.
+
+Uses the inotify system calls (inotify_init1, inotify_add_watch, read)
+directly via ctypes — no external C-extension compilation required.
+
+Supported inotify events mapped to memowatch events:
+  - IN_CREATE        → FileCreatedEvent / DirCreatedEvent
+  - IN_DELETE        → FileDeletedEvent / DirDeletedEvent
+  - IN_MODIFY        → FileModifiedEvent
+  - IN_MOVED_FROM/TO → FileMovedEvent / DirMovedEvent
+  - IN_ATTRIB        → FileModifiedEvent (metadata change)
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import os
+import struct
+import sys
+from typing import Callable, Dict, List, Optional
+
+from memowatch.backends.base import BaseBackend
+from memowatch.core.events import (
+    DirCreatedEvent,
+    DirDeletedEvent,
+    DirModifiedEvent,
+    DirMovedEvent,
+    FileCreatedEvent,
+    FileDeletedEvent,
+    FileModifiedEvent,
+    FileMovedEvent,
+    FileSystemEvent,
+)
+
+# ──────────────────────────────────────────────────
+# inotify constants
+# ──────────────────────────────────────────────────
+IN_ACCESS = 0x00000001
+IN_MODIFY = 0x00000002
+IN_ATTRIB = 0x00000004
+IN_CLOSE_WRITE = 0x00000008
+IN_CLOSE_NOWRITE = 0x00000010
+IN_OPEN = 0x00000020
+IN_MOVED_FROM = 0x00000040
+IN_MOVED_TO = 0x00000080
+IN_CREATE = 0x00000100
+IN_DELETE = 0x00000200
+IN_DELETE_SELF = 0x00000400
+IN_MOVE_SELF = 0x00000800
+IN_ISDIR = 0x40000000
+
+IN_NONBLOCK = 0x00000800
+IN_CLOEXEC = 0x00080000
+
+# Watch mask
+_WATCH_MASK = (
+    IN_MODIFY
+    | IN_ATTRIB
+    | IN_CLOSE_WRITE
+    | IN_MOVED_FROM
+    | IN_MOVED_TO
+    | IN_CREATE
+    | IN_DELETE
+    | IN_DELETE_SELF
+    | IN_MOVE_SELF
+)
+
+# inotify_event struct: int wd, uint32_t mask, uint32_t cookie, uint32_t len
+_EVENT_HEADER_SIZE = struct.calcsize("iIII")
+_EVENT_HEADER_FORMAT = "iIII"
+
+# Read buffer
+_READ_BUF_SIZE = 65536
+
+
+class InotifyBackend(BaseBackend):
+    """Native Linux filesystem watcher using inotify via ctypes.
+
+    Parameters
+    ----------
+    path : str
+        Root directory to watch.
+    recursive : bool
+        Whether to watch subdirectories.
+    callback : callable
+        Called with each detected ``FileSystemEvent``.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        recursive: bool = False,
+        callback: Optional[Callable[[FileSystemEvent], None]] = None,
+    ) -> None:
+        if sys.platform != "linux":
+            raise RuntimeError("InotifyBackend is only available on Linux")
+        super().__init__(path=path, recursive=recursive, callback=callback)
+        self._inotify_fd: int = -1
+        self._wd_to_path: Dict[int, str] = {}
+        self._cookie_map: Dict[int, str] = {}  # for rename pairing
+        self._libc = ctypes.CDLL(ctypes.util.find_library("c"), use_errno=True)
+
+    @property
+    def name(self) -> str:
+        return "inotify"
+
+    def stop(self) -> None:
+        """Signal stop and close the inotify fd to unblock read()."""
+        self._stop_event.set()
+        # Closing the fd will cause the blocking read() to return with an error
+        if self._inotify_fd >= 0:
+            try:
+                os.close(self._inotify_fd)
+            except OSError:
+                pass
+            self._inotify_fd = -1
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=5.0)
+
+    def _run(self) -> None:
+        abs_path = os.path.abspath(self.path)
+
+        # inotify_init1(IN_NONBLOCK | IN_CLOEXEC)
+        self._inotify_fd = self._libc.inotify_init1(IN_NONBLOCK | IN_CLOEXEC)
+        if self._inotify_fd < 0:
+            raise OSError("inotify_init1 failed")
+
+        try:
+            self._add_watch(abs_path)
+            if self.recursive:
+                self._add_watches_recursive(abs_path)
+            self._read_loop()
+        finally:
+            # Clean up watches
+            for wd in list(self._wd_to_path):
+                try:
+                    self._libc.inotify_rm_watch(self._inotify_fd, wd)
+                except OSError:
+                    pass
+            if self._inotify_fd >= 0:
+                try:
+                    os.close(self._inotify_fd)
+                except OSError:
+                    pass
+                self._inotify_fd = -1
+
+    def _add_watch(self, path: str) -> int:
+        wd = self._libc.inotify_add_watch(
+            self._inotify_fd,
+            path.encode("utf-8"),
+            _WATCH_MASK,
+        )
+        if wd < 0:
+            errno = ctypes.get_errno()
+            raise OSError(f"inotify_add_watch failed for {path} (errno={errno})")
+        self._wd_to_path[wd] = path
+        return wd
+
+    def _add_watches_recursive(self, root: str) -> None:
+        for dirpath, dirnames, _ in os.walk(root):
+            for d in dirnames:
+                full = os.path.join(dirpath, d)
+                try:
+                    self._add_watch(full)
+                except OSError:
+                    pass  # Permission denied, etc.
+
+    def _read_loop(self) -> None:
+        import select
+
+        while not self._stop_event.is_set():
+            # Use select with timeout so we can check stop_event periodically
+            try:
+                readable, _, _ = select.select(
+                    [self._inotify_fd], [], [], 0.5
+                )
+            except (ValueError, OSError):
+                break  # fd closed
+
+            if not readable:
+                continue
+
+            try:
+                data = os.read(self._inotify_fd, _READ_BUF_SIZE)
+            except OSError:
+                break
+
+            if not data:
+                continue
+
+            self._parse_events(data)
+
+    def _parse_events(self, data: bytes) -> None:
+        offset = 0
+        while offset < len(data):
+            if offset + _EVENT_HEADER_SIZE > len(data):
+                break
+
+            wd, mask, cookie, name_len = struct.unpack_from(
+                _EVENT_HEADER_FORMAT, data, offset
+            )
+            offset += _EVENT_HEADER_SIZE
+
+            name_bytes = data[offset : offset + name_len]
+            offset += name_len
+
+            # Trim null bytes
+            name = name_bytes.rstrip(b"\x00").decode("utf-8", errors="replace")
+
+            watch_path = self._wd_to_path.get(wd, "")
+            full_path = os.path.join(watch_path, name) if name else watch_path
+            is_dir = bool(mask & IN_ISDIR)
+
+            if mask & IN_CREATE:
+                if is_dir:
+                    self.emit(DirCreatedEvent(src_path=full_path))
+                    if self.recursive:
+                        try:
+                            self._add_watch(full_path)
+                        except OSError:
+                            pass
+                else:
+                    self.emit(FileCreatedEvent(src_path=full_path))
+
+            elif mask & IN_DELETE:
+                if is_dir:
+                    self.emit(DirDeletedEvent(src_path=full_path))
+                else:
+                    self.emit(FileDeletedEvent(src_path=full_path))
+
+            elif mask & (IN_MODIFY | IN_ATTRIB | IN_CLOSE_WRITE):
+                if is_dir:
+                    self.emit(DirModifiedEvent(src_path=full_path))
+                else:
+                    self.emit(FileModifiedEvent(src_path=full_path))
+
+            elif mask & IN_MOVED_FROM:
+                self._cookie_map[cookie] = full_path
+
+            elif mask & IN_MOVED_TO:
+                old_path = self._cookie_map.pop(cookie, None)
+                if old_path is not None:
+                    if is_dir:
+                        self.emit(DirMovedEvent(src_path=old_path, dest_path=full_path))
+                    else:
+                        self.emit(FileMovedEvent(src_path=old_path, dest_path=full_path))
+                else:
+                    if is_dir:
+                        self.emit(DirCreatedEvent(src_path=full_path))
+                    else:
+                        self.emit(FileCreatedEvent(src_path=full_path))
+
+            elif mask & IN_DELETE_SELF:
+                self._wd_to_path.pop(wd, None)

memowatch/backends/polling.py

@@ -0,0 +1,156 @@
+"""
+memowatch.backends.polling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Cross-platform polling backend.  Works everywhere but is less efficient
+than native backends.  Periodically scans the directory tree, detects
+changes in file metadata (existence, mtime, size), and emits events.
+
+This is the universal fallback and is used on platforms without a native
+backend or when the native backend fails to initialize.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Dict, Optional, Set
+
+from memowatch.backends.base import BaseBackend
+from memowatch.core.events import (
+    DirCreatedEvent,
+    DirDeletedEvent,
+    DirModifiedEvent,
+    FileCreatedEvent,
+    FileDeletedEvent,
+    FileModifiedEvent,
+    FileMovedEvent,
+    FileSystemEvent,
+)
+
+
+@dataclass
+class _Snapshot:
+    """Metadata snapshot for a single file or directory."""
+    is_dir: bool
+    size: int
+    mtime_ns: int
+
+
+class PollingBackend(BaseBackend):
+    """Polling-based filesystem watcher.
+
+    Parameters
+    ----------
+    path : str
+        Root directory to watch.
+    recursive : bool
+        Whether to recursively watch subdirectories.
+    callback : callable
+        Called with each detected ``FileSystemEvent``.
+    interval : float
+        Polling interval in seconds (default 1.0).
+    """
+
+    def __init__(
+        self,
+        path: str,
+        recursive: bool = False,
+        callback: Optional[Callable[[FileSystemEvent], None]] = None,
+        interval: float = 1.0,
+    ) -> None:
+        super().__init__(path=path, recursive=recursive, callback=callback)
+        self.interval = interval
+
+    @property
+    def name(self) -> str:
+        return "polling"
+
+    # ── Scanning ──────────────────────────────
+
+    def _take_snapshot(self) -> Dict[str, _Snapshot]:
+        """Walk the directory tree and capture file metadata."""
+        entries: Dict[str, _Snapshot] = {}
+        try:
+            if self.recursive:
+                for dirpath, dirnames, filenames in os.walk(self.path):
+                    # Record dirs
+                    for d in dirnames:
+                        full = os.path.join(dirpath, d)
+                        entries[full] = self._stat_entry(full, is_dir=True)
+                    # Record files
+                    for f in filenames:
+                        full = os.path.join(dirpath, f)
+                        entries[full] = self._stat_entry(full, is_dir=False)
+            else:
+                for entry in os.scandir(self.path):
+                    entries[entry.path] = self._stat_entry(
+                        entry.path, is_dir=entry.is_dir(follow_symlinks=False)
+                    )
+        except OSError:
+            pass  # directory may have been deleted
+        return entries
+
+    @staticmethod
+    def _stat_entry(path: str, is_dir: bool) -> _Snapshot:
+        try:
+            st = os.stat(path)
+            return _Snapshot(
+                is_dir=is_dir,
+                size=st.st_size if not is_dir else 0,
+                mtime_ns=st.st_mtime_ns,
+            )
+        except OSError:
+            return _Snapshot(is_dir=is_dir, size=-1, mtime_ns=0)
+
+    # ── Diffing ───────────────────────────────
+
+    def _diff(
+        self,
+        old: Dict[str, _Snapshot],
+        new: Dict[str, _Snapshot],
+    ) -> None:
+        """Compare two snapshots and emit events for any differences."""
+        old_paths = set(old.keys())
+        new_paths = set(new.keys())
+
+        # Created
+        for p in new_paths - old_paths:
+            snap = new[p]
+            if snap.is_dir:
+                self.emit(DirCreatedEvent(src_path=p))
+            else:
+                self.emit(FileCreatedEvent(src_path=p))
+
+        # Deleted
+        for p in old_paths - new_paths:
+            snap = old[p]
+            if snap.is_dir:
+                self.emit(DirDeletedEvent(src_path=p))
+            else:
+                self.emit(FileDeletedEvent(src_path=p))
+
+        # Modified (size or mtime changed)
+        for p in old_paths & new_paths:
+            o, n = old[p], new[p]
+            if o.size != n.size or o.mtime_ns != n.mtime_ns:
+                if n.is_dir:
+                    self.emit(DirModifiedEvent(src_path=p))
+                else:
+                    self.emit(FileModifiedEvent(src_path=p))
+
+    # ── Main loop ─────────────────────────────
+
+    def _run(self) -> None:
+        previous = self._take_snapshot()
+
+        while not self._stop_event.is_set():
+            self._stop_event.wait(self.interval)
+            if self._stop_event.is_set():
+                break
+
+            current = self._take_snapshot()
+            self._diff(previous, current)
+            previous = current