Allow Observer to be used as a context manager (fixes #1090)

README.rst

@@ -47,6 +47,29 @@ as command-line arguments and logs events generated:
         observer.stop()
         observer.join()
 
+Alternatively, you can use the observer as a context manager for cleaner code:
+
+.. code-block:: python
+
+    import time
+
+    from watchdog.events import FileSystemEvent, FileSystemEventHandler
+    from watchdog.observers import Observer
+
+
+    class MyEventHandler(FileSystemEventHandler):
+        def on_any_event(self, event: FileSystemEvent) -> None:
+            print(event)
+
+
+    event_handler = MyEventHandler()
+    observer = Observer()
+    observer.schedule(event_handler, ".", recursive=True)
+
+    with observer:
+        while True:
+            time.sleep(1)
+
 
 Shell Utilities
 ---------------

THIRD_PARTY_LICENSES.md

@@ -1,5 +1,17 @@
 # Third Party Licenses
 
+## Python C-API compatibility header
+
+This project includes the `pythoncapi_compat.h` header provided by the
+`pythoncapi-compat` project. It is located in the `src` directory.
+
+This header is included to allow writing code using C API constructs only
+available in newer Python versions.
+
+**License**: Zero Clause BSD
+**Copyright**: Contributors to the pythoncapi_compat project.
+**Source**: https://github.com/python/pythoncapi_compat
+
 ## Python Standard Library Compatibility Code
 
 This project includes the following unmodified functions from the Python 3.13 standard library:
@@ -15,6 +27,23 @@ These are included in `backwards_compat.py` to provide backwards compatibility w
 
 ---
 
+### Zero Clause BSD License
+
+BSD Zero Clause License
+
+Copyright Contributors to the pythoncapi_compat project.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
 ### Python Software Foundation License Version 2
 
 1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using this software ("Python") in source or binary form and its associated documentation.
@@ -32,3 +61,4 @@ These are included in `backwards_compat.py` to provide backwards compatibility w
 7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee.  This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.
 
 8. By copying, installing or otherwise using Python, Licensee agrees to be bound by the terms and conditions of this License Agreement.
+

changelog.rst

@@ -14,6 +14,7 @@ Changelog
 
 **Other Changes**
 
+- [core] Add context manager support to ``Observer`` class. The observer can now be used with a ``with`` statement for automatic start/stop management. (`#1090 <https://github.com/gorakhargosh/watchdog/pull/1149>`__)
 - [freebsd] Supports ``inotify`` on FreeBSD 15+. (`#1147 <https://github.com/gorakhargosh/watchdog/pull/1147>`__)
 - [core] Adjust ``Observer.schedule()`` ``path`` type annotation to reflect the ``pathlib.Path`` support. (`#1096 <https://github.com/gorakhargosh/watchdog/pull/1096>`__)
 - [core] Add support for the ``follow_symlink`` keyword argument to ``ObservedWatch``. (`#1086 <https://github.com/gorakhargosh/watchdog/pull/1086>`__)

docs/source/quickstart.rst

@@ -53,6 +53,30 @@ file system changes and simply print them to the console::
 
 To stop the program, press Control-C.
 
+Alternatively, you can use the observer as a context manager for cleaner code::
+
+    import time
+
+    from watchdog.events import FileSystemEvent, FileSystemEventHandler
+    from watchdog.observers import Observer
+
+
+    class MyEventHandler(FileSystemEventHandler):
+        def on_any_event(self, event: FileSystemEvent) -> None:
+            print(event)
+
+
+    event_handler = MyEventHandler()
+    observer = Observer()
+    observer.schedule(event_handler, ".", recursive=True)
+
+    with observer:
+        while True:
+            time.sleep(1)
+
+The context manager automatically handles starting and stopping the observer,
+ensuring proper cleanup even if an exception occurs.
+
 Typing
 ------