robotframework-filewatcher 0.1.0__py3-none-any.whl

FileWatcher/keywords/watching.py

@@ -0,0 +1,132 @@
+from pathlib import Path
+from robot.api.deco import keyword
+from FileWatcher.watcher import WatchManager
+
+
+class WatchingKeywords:
+    """Keywords for managing watched directories."""
+
+    def __init__(self, ctx: any) -> None:
+        """Initializes the WatchingKeywords component.
+
+        Args:
+            ctx: The parent FileWatcherLibrary context.
+        """
+        self.ctx = ctx
+
+    @keyword("Start Watching Directory")
+    def start_watching_directory(self, path: str, recursive: bool = True) -> None:
+        """Start monitoring a directory for filesystem events.
+
+        This keyword instructs the library to monitor the given directory
+        and begin collecting filesystem events (create/modify/delete/move)
+        into the internal EventStore. Observers run in the background
+        so tests can continue while events are collected.
+
+        Arguments:
+            path: Directory path to monitor. Can be relative or absolute.
+            recursive: If True (default), subdirectories are monitored too.
+
+        Returns:
+            None
+
+        Raises:
+            FileWatcherError: If the path is not a directory or observer fails to start.
+
+        *Examples*
+        | ***** Settings *****
+        | Library    FileWatcher
+        |
+        | ***** Test Cases *****
+        | Example
+        |   Start Watching Directory    /path/to/watch    recursive=False
+        """
+        self.ctx.watch_manager.start_watch(path, recursive=recursive)
+
+    @keyword("Stop Watching Directory")
+    def stop_watching_directory(self, path: str) -> None:
+        """Stop monitoring a previously watched directory.
+
+        Arguments:
+            path: Directory path that was previously started with
+                `Start Watching Directory`. The path is resolved when
+                matching active watchers to stop.
+
+        Returns:
+            None
+
+        Raises:
+            FileWatcherError: If there is no active watcher for the given path.
+
+        *Examples*
+        | ***** Settings *****
+        | Library    FileWatcher
+        |
+        | ***** Test Cases *****
+        | Example
+        |   Start Watching Directory    ${DOWNLOADS}
+        |   ${is_watching}=    Is Watching Directory    ${DOWNLOADS}
+        |   Should Be True    ${is_watching}
+        |   Stop Watching Directory    ${DOWNLOADS}
+        """
+        self.ctx.watch_manager.stop_watch(path)
+
+    @keyword("Is Watching Directory")
+    def is_watching_directory(self, path: str) -> bool:
+        """Return whether the library currently monitors the given directory.
+
+        Arguments:
+            path: Directory path to check. Can be relative or absolute.
+
+        Returns:
+            bool: True if an active watcher exists for the resolved path,
+            otherwise False.
+        
+        *Examples*
+        | ***** Settings *****
+        | Library    FileWatcher
+        |
+        | ***** Test Cases *****
+        | Example
+        |   Start Watching Directory    ${DOWNLOADS}
+        |   ${is_watching}=    Is Watching Directory    ${DOWNLOADS}
+        |   Should Be True    ${is_watching}
+        """
+        # Normalize the provided path before checking registry membership
+        try:
+            resolved = str(Path(path).resolve())
+        except Exception:
+            # Fall back to original value if resolution fails
+            resolved = path
+        return self.ctx.watch_manager.is_watching(resolved)
+
+    @keyword("Get Watched Directories")
+    def get_watched_directories(self) -> list[str]:
+        """Return a sorted list of actively monitored directories.
+
+        This returns absolute, unique paths for all directories currently
+        being observed by the library (duplicates removed).
+
+        Returns:
+            list[str]: Sorted list of absolute paths.
+
+        *Examples*
+        | ***** Settings *****
+        | Library    FileWatcher
+        |
+        | ***** Test Cases *****
+        | Example
+        |   ${dirs}=    Get Watched Directories
+        |   Should Contain    ${dirs}    ${DOWNLOADS}
+        """
+        paths = self.ctx.watch_manager.watched_directories()
+        # Ensure unique, sorted string representation
+        seen = set()
+        out = []
+        for p in paths:
+            s = str(p)
+            if s in seen:
+                continue
+            seen.add(s)
+            out.append(s)
+        return out

FileWatcher/library.py

@@ -0,0 +1,52 @@
+import importlib.metadata
+from robotlibcore import HybridCore
+from FileWatcher.watcher import WatchManager
+from FileWatcher.keywords.watching import WatchingKeywords
+from FileWatcher.keywords.waiting import WaitingKeywords
+
+
+class FileWatcher(HybridCore):
+    """FileWatcher is a modern Robot Framework library for filesystem monitoring.
+
+    It uses `watchdog` to monitor directory changes in the background, collects
+    events thread-safely in a non-consuming event store, and exposes keywords
+    to wait for specific creation, modification, deletion, and stability states.
+    """
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+    ROBOT_AUTO_KEYWORDS = False
+
+    try:
+        ROBOT_LIBRARY_VERSION = importlib.metadata.version("robotframework-filewatcher")
+    except importlib.metadata.PackageNotFoundError:
+        ROBOT_LIBRARY_VERSION = "0.1.0"
+
+    def __init__(self, max_events: int = 10000) -> None:
+        """Initializes the FileWatcher library.
+
+        Args:
+            max_events (int): The maximum number of historical events to retain.
+        """
+        self.watch_manager = WatchManager(max_events=int(max_events))
+        libraries = [
+            WatchingKeywords(self),
+            WaitingKeywords(self),
+        ]
+        super().__init__(libraries)
+
+    def close(self) -> None:
+        """Cleans up and shuts down all active background observers.
+
+        Called automatically by Robot Framework at the end of the execution.
+        """
+        self.watch_manager.close()
+
+    def __enter__(self) -> "FileWatcher":
+        return self
+
+    def __exit__(self, exc_type: any, exc_val: any, exc_tb: any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        watching_count = len(self.watch_manager.watched_directories())
+        return f"FileWatcher(version={self.ROBOT_LIBRARY_VERSION}, watching={watching_count})"

FileWatcher/models.py

@@ -0,0 +1,119 @@
+from dataclasses import dataclass
+from enum import Enum
+import fnmatch
+from pathlib import Path
+import threading
+
+
+class EventType(str, Enum):
+    """Enumeration of file system event types."""
+
+    CREATED = "created"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    MOVED = "moved"
+
+
+@dataclass(frozen=True, slots=True)
+class FileEvent:
+    """Immutable representation of a file system event.
+
+    Attributes:
+        id (int): Monotonically increasing sequential ID.
+        event_type (EventType): Type of event (created, modified, deleted, moved).
+        src_path (Path): Path of the file/directory that triggered the event.
+        dest_path (Path | None): Destination path for moved events. Defaults to None.
+        watched_directory (Path): The root directory under watch that caught this event.
+        timestamp (float): Epoch timestamp when the event was recorded.
+    """
+
+    id: int
+    event_type: EventType
+    src_path: Path
+    watched_directory: Path
+    timestamp: float
+    dest_path: Path | None = None
+
+    def matches_glob(self, pattern: str) -> bool:
+        """Checks if the event's source or destination path matches the glob pattern.
+
+        Matches against the path's filename (e.g. 'report.pdf') as well as the
+        relative path from the watched directory (e.g. 'sub/report.pdf').
+
+        Args:
+            pattern (str): The glob pattern to match against (e.g. '*.pdf').
+
+        Returns:
+            bool: True if the pattern matches, False otherwise.
+        """
+        paths_to_check = [self.src_path]
+        if self.dest_path is not None:
+            paths_to_check.append(self.dest_path)
+
+        for path in paths_to_check:
+            # Match against filename (basename)
+            if fnmatch.fnmatch(path.name, pattern):
+                return True
+
+            # Match against relative path from watched directory
+            try:
+                rel_path = path.relative_to(self.watched_directory)
+                if fnmatch.fnmatch(str(rel_path), pattern) or fnmatch.fnmatch(
+                    rel_path.as_posix(), pattern
+                ):
+                    return True
+            except ValueError:
+                # Path is not relative to watched_directory (should not normally happen)
+                pass
+
+        return False
+
+    def matches_directory(self, directory: Path) -> bool:
+        """Checks if the event path resides within or matches the given directory.
+
+        Args:
+            directory (Path): The directory path to check.
+
+        Returns:
+            bool: True if the path matches or is a descendant of the directory.
+        """
+        try:
+            resolved_src = self.src_path.resolve()
+            resolved_dir = directory.resolve()
+            return resolved_dir == resolved_src or resolved_dir in resolved_src.parents
+        except (ValueError, OSError):
+            # Fallback to lexical comparison if resolution fails
+            return directory == self.src_path or directory in self.src_path.parents
+
+    def to_dict(self) -> dict:
+        """Converts the FileEvent to a standard dictionary representation.
+
+        Returns:
+            dict: Dictionary containing serializable event data.
+        """
+        return {
+            "id": self.id,
+            "event_type": self.event_type.value,
+            "src_path": str(self.src_path),
+            "dest_path": str(self.dest_path) if self.dest_path is not None else None,
+            "watched_directory": str(self.watched_directory),
+            "timestamp": self.timestamp,
+        }
+
+
+class EventIdGenerator:
+    """Thread-safe sequential generator for FileEvent IDs."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._counter = 0
+
+    def next_id(self) -> int:
+        """Generates the next sequential ID starting from 1.
+
+        Returns:
+            int: The next unique integer ID.
+        """
+        with self._lock:
+            self._counter += 1
+            return self._counter

FileWatcher/watcher.py

@@ -0,0 +1,343 @@
+from collections import deque
+from pathlib import Path
+import threading
+import time
+from typing import Iterator
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+from watchdog.observers.api import ObservedWatch
+
+from FileWatcher.exceptions import (
+    DirectoryAlreadyWatchedError,
+    DirectoryNotWatchedError,
+    FileWatcherError,
+    FileWatcherTimeoutError,
+)
+from FileWatcher.models import EventIdGenerator, EventType, FileEvent
+
+
+class EventStore:
+    """A thread-safe, non-consuming, in-memory store for file events.
+
+    Retains history using a double-ended queue (deque) with a configurable maximum size.
+    Waiters can block efficiently using a condition variable without busy waiting.
+    """
+
+    def __init__(self, max_events: int = 10000) -> None:
+        """Initializes the EventStore.
+
+        Args:
+            max_events (int): The maximum number of events to retain in memory.
+        """
+        self._max_events = max_events
+        self._condition = threading.Condition()
+        self._events: deque[FileEvent] = deque(maxlen=max_events)
+
+    def push(self, event: FileEvent) -> None:
+        """Appends a new event to the store and notifies all waiting threads.
+
+        Args:
+            event (FileEvent): The file event to add.
+        """
+        with self._condition:
+            self._events.append(event)
+            self._condition.notify_all()
+
+    def get_all(self) -> list[FileEvent]:
+        """Returns a snapshot list of all retained events.
+
+        Returns:
+            list[FileEvent]: A copy of the currently retained events.
+        """
+        with self._condition:
+            return list(self._events)
+
+    def get_since(self, event_id: int) -> list[FileEvent]:
+        """Returns a snapshot list of events with an ID greater than event_id.
+
+        Args:
+            event_id (int): The starting threshold ID.
+
+        Returns:
+            list[FileEvent]: A list of events occurring after event_id.
+        """
+        with self._condition:
+            return [event for event in self._events if event.id > event_id]
+
+    def get_current_event_id(self) -> int:
+        """Returns the ID of the most recent event.
+
+        Returns:
+            int: The maximum event ID currently stored, or 0 if empty.
+        """
+        with self._condition:
+            if not self._events:
+                return 0
+            return self._events[-1].id
+
+    def clear(self) -> None:
+        """Removes all stored events. Thread-safe."""
+        with self._condition:
+            self._events.clear()
+
+    def wait_for_event(
+        self,
+        event_type: EventType | None = None,
+        pattern: str | None = None,
+        since_id: int = 0,
+        timeout: float = 30.0,
+    ) -> FileEvent:
+        """Blocks until a matching event is recorded or the timeout is exceeded.
+
+        First scans the existing history for a match. If not found, blocks
+        using a condition variable.
+
+        Args:
+            event_type (EventType | None): Optional type of event to match.
+            pattern (str | None): Optional glob pattern to match.
+            since_id (int): Match only events with ID greater than this value.
+            timeout (float): Maximum time to wait in seconds.
+
+        Returns:
+            FileEvent: The first matching file event.
+
+        Raises:
+            FileWatcherTimeoutError: If no matching event is found within the timeout.
+        """
+        deadline = time.time() + timeout
+        with self._condition:
+            while True:
+                # 1. Scan current list
+                for event in self._events:
+                    if event.id > since_id:
+                        if event_type is not None and event.event_type != event_type:
+                            continue
+                        if pattern is not None and not event.matches_glob(pattern):
+                            continue
+                        return event
+
+                # 2. Check timeout
+                remaining = deadline - time.time()
+                if remaining <= 0:
+                    raise FileWatcherTimeoutError(
+                        f"Timed out waiting for file event (pattern={pattern}, "
+                        f"event_type={event_type}, since_id={since_id}) after {timeout} seconds."
+                    )
+
+                # 3. Wait for notification
+                self._condition.wait(timeout=remaining)
+
+    def __len__(self) -> int:
+        """Returns the number of currently stored events.
+
+        Returns:
+            int: The size of the store.
+        """
+        with self._condition:
+            return len(self._events)
+
+    def __repr__(self) -> str:
+        """Returns string representation of the EventStore.
+
+        Returns:
+            str: Representative string.
+        """
+        with self._condition:
+            return f"EventStore(events={len(self._events)}, max_events={self._max_events})"
+
+
+class DirectoryEventHandler(FileSystemEventHandler):
+    """Bridges watchdog raw OS events to our EventStore using FileEvent models."""
+
+    def __init__(
+        self,
+        watched_directory: Path,
+        event_store: EventStore,
+        id_generator: EventIdGenerator,
+    ) -> None:
+        """Initializes the DirectoryEventHandler.
+
+        Args:
+            watched_directory (Path): Root directory path monitored by this handler.
+            event_store (EventStore): Targets incoming events to this store.
+            id_generator (EventIdGenerator): Generator for unique event IDs.
+        """
+        super().__init__()
+        self.watched_directory = watched_directory
+        self.event_store = event_store
+        self.id_generator = id_generator
+
+    def on_any_event(self, event: FileSystemEvent) -> None:
+        """Handles any filesystem event, normalization, and pushing to EventStore."""
+        try:
+            event_type = EventType(event.event_type)
+        except ValueError:
+            # Ignore event types we don't track
+            return
+
+        src_path = Path(event.src_path)
+        dest_path = Path(event.dest_path) if getattr(event, "dest_path", None) is not None else None
+
+        file_event = FileEvent(
+            id=self.id_generator.next_id(),
+            event_type=event_type,
+            src_path=src_path,
+            dest_path=dest_path,
+            watched_directory=self.watched_directory,
+            timestamp=time.time(),
+        )
+        self.event_store.push(file_event)
+
+
+class WatchManager:
+    """Orchestrates file system observers and directory watches using watchdog."""
+
+    def __init__(self, max_events: int = 10000) -> None:
+        """Initializes the WatchManager.
+
+        Args:
+            max_events (int): Event retention size.
+        """
+        self._event_store = EventStore(max_events)
+        self._event_id_generator = EventIdGenerator()
+        self._watches: dict[Path, ObservedWatch] = {}
+        self._handlers: dict[Path, DirectoryEventHandler] = {}
+        self._lock = threading.RLock()
+        self._observer: Observer | None = None
+
+    def _get_observer(self) -> Observer:
+        """Returns the watchdog Observer instance, creating it if not exist."""
+        # Must be called under lock
+        if self._observer is None:
+            self._observer = Observer()
+        return self._observer
+
+    def _ensure_observer_running(self) -> None:
+        """Starts the observer background thread if it is not already running."""
+        # Must be called under lock
+        observer = self._get_observer()
+        if not observer.is_alive():
+            try:
+                observer.start()
+            except RuntimeError:
+                # The thread has already been stopped once; recreate it
+                self._observer = Observer()
+                self._observer.start()
+
+    def start_watch(self, path: Path | str, recursive: bool = True) -> None:
+        """Starts monitoring a directory path for events.
+
+        Args:
+            path (Path | str): The directory path to monitor.
+            recursive (bool): Whether to watch subdirectories.
+
+        Raises:
+            FileWatcherError: If path is invalid or does not exist.
+            DirectoryAlreadyWatchedError: If path is already monitored.
+        """
+        with self._lock:
+            try:
+                resolved_path = Path(path).resolve(strict=True)
+            except (OSError, FileNotFoundError) as err:
+                raise FileWatcherError(f"Path does not exist: {path}") from err
+
+            if not resolved_path.is_dir():
+                raise FileWatcherError(f"Path is not a directory: {path}")
+
+            if resolved_path in self._watches:
+                raise DirectoryAlreadyWatchedError(f"Directory is already watched: {path}")
+
+            handler = DirectoryEventHandler(
+                watched_directory=resolved_path,
+                event_store=self._event_store,
+                id_generator=self._event_id_generator,
+            )
+
+            observer = self._get_observer()
+            self._ensure_observer_running()
+
+            watch = observer.schedule(handler, str(resolved_path), recursive=recursive)
+            self._watches[resolved_path] = watch
+            self._handlers[resolved_path] = handler
+
+    def stop_watch(self, path: Path | str) -> None:
+        """Stops monitoring a directory path.
+
+        Args:
+            path (Path | str): The directory path to stop monitoring.
+
+        Raises:
+            DirectoryNotWatchedError: If path was not registered.
+        """
+        with self._lock:
+            resolved_path = Path(path).resolve()
+            if resolved_path not in self._watches:
+                raise DirectoryNotWatchedError(f"Directory is not currently watched: {path}")
+
+            watch = self._watches.pop(resolved_path)
+            self._handlers.pop(resolved_path)
+
+            if self._observer is not None:
+                self._observer.unschedule(watch)
+
+    def is_watching(self, path: Path | str) -> bool:
+        """Checks if a directory path is actively watched.
+
+        Args:
+            path (Path | str): The directory path.
+
+        Returns:
+            bool: True if watched, False otherwise.
+        """
+        with self._lock:
+            try:
+                resolved_path = Path(path).resolve()
+                return resolved_path in self._watches
+            except (OSError, FileNotFoundError):
+                return False
+
+    def watched_directories(self) -> list[Path]:
+        """Returns a sorted list of all active watched paths.
+
+        Returns:
+            list[Path]: Sorted active paths.
+        """
+        with self._lock:
+            return sorted(list(self._watches.keys()))
+
+    def get_event_store(self) -> EventStore:
+        """Returns the shared EventStore instance.
+
+        Returns:
+            EventStore: Shared store.
+        """
+        return self._event_store
+
+    def close(self) -> None:
+        """Stops the observer and unschedules all directory watches.
+
+        Safe to call multiple times.
+        """
+        with self._lock:
+            if self._observer is not None:
+                self._observer.stop()
+                self._observer.join()
+                self._observer = None
+
+            self._watches.clear()
+            self._handlers.clear()
+
+    def __enter__(self) -> "WatchManager":
+        return self
+
+    def __exit__(self, exc_type: any, exc_val: any, exc_tb: any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        with self._lock:
+            observer_running = self._observer is not None and self._observer.is_alive()
+            return (
+                f"WatchManager(watching={len(self._watches)}, "
+                f"observer_running={observer_running})"
+            )