python-trio / python-trio/trio
Add api for watching for filesystem changes
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 7.3k
- Forks
- 431
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 6
Description
There was a conversation on gitter about adding a filesystem watching api to trio, specifically in the context of Windows but it's something which would be of general utility.
watchdog was brought up as an example of an existing project implementing this functionality albeit not in a trio-native fashion.
@mozesa also linked to an excellent SO post on the topic:
https://stackoverflow.com/a/49888600
...and @njsmith gave some implementation advice:
if you do want to experiment with integrating it directly with the trio loop, the key functions are
trio.hazmat.register_with_iocp(handle)andtrio.hazmat.wait_overlapped(handle, lpOverlapped)Here
handleis a Win32HANDLEobject as a python integer (I think forReadDirectoryChangesWthis is the directory handle), andlpOverlappedis the address of anOVERLAPPEDobject as a python integerSo you'd use
CreateFileto open the directory and get a handle object, then you'd pass that handle object totrio.hazmat.register_with_iocp, and then you'd create anOVERLAPPEDobject and pass it toReadDirectoryChanges, and then pass the handle+overlapped object totrio.hazmat.wait_overlappedFor
win32file, it has ways to createPyHandleandPyOverlappedobjects that wrap the C-levelHANDLEandOVERLAPPEDobjects, but what I don't know is whether it gives you a way to "unwrap" those and get the raw integers that Trio needsI guess it would be reasonable to include a
ReadDirectoryChangesWwrapper in trio itself... it's a pretty simple API. Something likeasync def read_directory_changes(path: str, watch_subtree: bool, notify_filter: IntFlags) -> AsyncIterator[DirectoryChangeEvent]
it would be a low-level platform-specific API, similar totrio.hazmat.readinto_overlapped, but that's OK...
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing trio.hazmat.register_with_iocp, trio.hazmat.wait_overlapped, and the proposed ReadDirectoryChangesW/read_directory_changes interface, then compare the watchdog example and linked Windows guidance. The issue does not name files or tests; completion criteria still need to be defined for a Trio-native filesystem-watching API and its platform scope.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100