pywatchman

Warnings

• gotcha pywatchman is a client library and requires the separate Watchman daemon to be installed and running on your system. It is not a standalone file watcher written purely in Python.
  Fix: Ensure the Watchman daemon is installed and started according to the official Watchman documentation for your operating system (e.g., via Homebrew on macOS, package managers on Linux).
• breaking Older versions of pywatchman (specifically 1.4.1) were known to raise a `SystemError` on Python 3.10+ due to issues with internal C extensions related to the `PY_SSIZE_T_CLEAN` macro.
  Fix: Upgrade pywatchman to a modern version (2.0.0 or 3.0.0+). These versions provide compatibility with newer Python releases (Python >=3.8 is currently required for 3.0.0).
• gotcha Dedicated documentation for the pywatchman Python API is limited. Users often need to refer to the Watchman daemon's general command documentation and the pywatchman source code for detailed usage examples and API specifics.
  Fix: Consult the main Watchman documentation for command structures and parameters, and review the pywatchman GitHub repository's `pywatchman/__init__.py` for direct API exploration.
• gotcha Issues have been reported where `ignore_dirs` in the `.watchmanconfig` file are not always respected by `WatchmanReloader` integrations (e.g., in Django), leading to excessive file watching in ignored paths like virtual environments or system Python directories.
  Fix: Verify your `.watchmanconfig` syntax. If the issue persists, consider explicit subscription filters in your client code or investigate specific framework integration configurations. This might require debugging the interaction between the framework and pywatchman.

Install

• pip install pywatchman Install pywatchman

Imports

• client
  wrong:

  from watchman_client import Client

  correct:

  import pywatchman
  client = pywatchman.client()

  The `watchman_client` import belongs to a different, unofficial client library (orf/watchman-client). The official pywatchman library uses `pywatchman.client()`.
• bser

  from pywatchman import bser

  Imports the BSER (Binary Serialization) module for efficient data exchange with the Watchman daemon.

Quickstart

This quickstart demonstrates how to connect to the Watchman daemon, establish a watch on a directory, and then query for recently changed Python files within that watched directory. It includes basic error handling for when the Watchman service is not available.

import pywatchman
import os

def main():
    try:
        # Establish a connection to the Watchman daemon
        client = pywatchman.client()
        print(f"Connected to Watchman: {client.query('get-sockname')['sockname']}")

        # Define the directory to watch (current directory for example)
        watch_dir = os.getcwd()
        print(f"Attempting to watch directory: {watch_dir}")

        # Tell Watchman to start watching the directory
        # This will return existing watch if already present
        watch_result = client.query('watch', watch_dir)
        print(f"Watch established: {watch_result}")

        # Perform a query for Python files that have changed since the last clock
        # The 'clock' value is automatically managed by Watchman
        query_result = client.query(
            'query', watch_dir, {
                'expression': ['allof', ['type', 'f'], ['suffix', 'py']],
                'fields': ['name', 'size', 'mtime_ms']
            }
        )
        print("\nRecently changed Python files:")
        for f in query_result.get('files', []):
            print(f" - {f['name']} (size: {f['size']} bytes, modified: {f['mtime_ms']}ms ago)")

    except pywatchman.Unavailable as e:
        print(f"Error: Watchman service is unavailable. Please ensure Watchman is installed and running. Details: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == '__main__':
    main()