Make use_original thread-local to fix cross-thread races

The use_original flag on FakeOsModule was a process-global class
attribute toggled by the use_original_os() context manager. When one
thread entered the context manager while another thread was in the
middle of a faked filesystem operation, the faked call could observe
use_original=True and dispatch to the real os module, failing against
paths that only exist in the fake filesystem.

Store use_original in a threading.local and have use_original_os()
save and restore the previous thread-local value so nested uses
continue to work.  The class attribute becomes an instance property,
preserving the existing instance.use_original get/set API.

A regression test in fake_filesystem_unittest_test exercises the
concurrent-worker pattern with explicit hammer threads entering
use_original_os() alongside asyncio.to_thread workers; without the
fix it fails reliably with PermissionError against the fake root.

Fixes #1317.

Author: jfindlay

CHANGES.md

@@ -7,6 +7,9 @@ The released versions correspond to PyPI releases.
 ### Fixes
 * fixed a crash if the stack limit was set to a low value
   (see [#1313](https://github.com/pytest-dev/pyfakefs/issues/1313))
+* made the `use_original` flag on `FakeOsModule` thread-local to fix a race
+  condition with async code (see
+  [#1317](https://github.com/pytest-dev/pyfakefs/issues/1317))
 
 ## [Version 6.2.0](https://pypi.python.org/pypi/pyfakefs/6.2.0) (2026-04-12)
 Changes the MRO for file wrappers.

pyfakefs/fake_os.py

@@ -23,6 +23,7 @@
 import inspect
 import os
 import sys
+import threading
 import uuid
 from contextlib import contextmanager
 from stat import (
@@ -74,6 +75,15 @@
 NR_STD_STREAMS = 3
 
 
+# Thread-local storage for the `use_original` flag.
+_thread_state = threading.local()
+
+
+def _use_original() -> bool:
+    """Return the thread-local `use_original` flag, defaulting to False."""
+    return getattr(_thread_state, "use_original", False)
+
+
 class FakeOsModule:
     """Uses FakeFilesystem to provide a fake os module replacement.
 
@@ -88,7 +98,18 @@ class FakeOsModule:
         my_os_module = fake_os.FakeOsModule(filesystem)
     """
 
-    use_original = False
+    @property
+    def use_original(self) -> bool:
+        """Whether faked operations should dispatch to the real `os` module.
+
+        Stored in thread-local state so that `use_original_os()` in one thread
+        does not affect faked operations running in another thread.
+        """
+        return _use_original()
+
+    @use_original.setter
+    def use_original(self, value: bool) -> None:
+        _thread_state.use_original = value
 
     @staticmethod
     def dir() -> list[str]:
@@ -1468,7 +1489,7 @@ def handle_original_call(f: Callable) -> Callable:
 
     @functools.wraps(f)
     def wrapped(*args, **kwargs):
-        should_use_original = FakeOsModule.use_original
+        should_use_original = _use_original()
 
         if not should_use_original and args:
             self = args[0]
@@ -1500,10 +1521,16 @@ def wrapped(*args, **kwargs):
 @contextmanager
 def use_original_os():
     """Temporarily use original os functions instead of faked ones.
-    Used to ensure that skipped modules do not use faked calls.
+
+    Used to ensure that skipped modules do not use faked calls. The flag
+    is stored in thread-local state so that concurrent calls from
+    multiple threads do not interfere with each other; the previous
+    thread-local value is restored on exit so nested uses work
+    correctly.
     """
+    prev = getattr(_thread_state, "use_original", False)
     try:
-        FakeOsModule.use_original = True
+        _thread_state.use_original = True
         yield
     finally:
-        FakeOsModule.use_original = False
+        _thread_state.use_original = prev

pyfakefs/tests/fake_filesystem_unittest_test.py

@@ -18,6 +18,7 @@
 Test the :py:class`pyfakefs.fake_filesystem_unittest.TestCase` base class.
 """
 
+import asyncio
 import glob
 import importlib.util
 import io
@@ -28,6 +29,7 @@
 import shutil
 import sys
 import tempfile
+import threading
 import unittest
 import warnings
 from contextlib import redirect_stdout
@@ -45,6 +47,7 @@
     patchfs,
     PatchMode,
 )
+from pyfakefs.fake_os import use_original_os
 from pyfakefs.helpers import IS_PYPY
 from pyfakefs.tests.fixtures import module_with_attributes
 
@@ -1065,5 +1068,88 @@ def test_fake_relative_import(self):
         assert module.number == 42
 
 
+class UseOriginalThreadSafetyTest(TestCase):
+    """Regression test: the ``use_original`` flag on :class:`FakeOsModule`
+    used to be a process-global class attribute flipped by the
+    :func:`use_original_os` context manager. When one thread entered the
+    context manager while another thread was in the middle of a faked
+    filesystem operation, the faked call could observe ``use_original=True``
+    from the first thread and dispatch to the real ``os`` module, failing
+    against a path that only exists in the fake filesystem.
+
+    The flag is now stored in :class:`threading.local` so that concurrent
+    ``use_original_os()`` calls do not leak state across threads.
+    """
+
+    def test_use_original_os_is_thread_local(self):
+        """Concurrent ``use_original_os()`` in a sibling thread must not
+        cause faked filesystem operations in a worker thread to dispatch
+        to the real OS.
+
+        This mirrors the behaviour of pyfakefs-internal call sites such as
+        ``linecache`` during traceback formatting, which enter
+        ``use_original_os()`` on arbitrary threads while user code runs
+        faked filesystem calls via ``asyncio.to_thread``.
+        """
+        stop_flag = threading.Event()
+
+        def hammer_use_original():
+            """Enter and exit ``use_original_os()`` in a tight loop to
+            race against the worker threads below."""
+            while not stop_flag.is_set():
+                with use_original_os():
+                    pass
+
+        def _write(p):
+            # Each worker mkdirs and writes inside its own pre-isolated
+            # subtree so that no two workers mutate the same fake-directory
+            # dict.
+            p.parent.mkdir(parents=True, exist_ok=True)
+            with p.open("w") as cf:
+                cf.write("x")
+
+        async def _dispatch(p):
+            await asyncio.to_thread(_write, p)
+
+        async def many(root, n):
+            await asyncio.gather(
+                *[
+                    _dispatch(pathlib.Path(f"{root}/w{i}/a/b/c/file"))
+                    for i in range(n)
+                ]
+            )
+
+        with Patcher() as p:
+            # Start the hammer threads inside the Patcher context so they do
+            # not contend with Patcher's cold module-walk during init.
+            hammers = [
+                threading.Thread(target=hammer_use_original, daemon=True)
+                for _ in range(4)
+            ]
+            for h in hammers:
+                h.start()
+            try:
+                # Run several rounds so the cumulative failure probability
+                # approaches 1; each round uses a distinct root so any
+                # real-OS fallback reliably fails against a non-existent
+                # directory.
+                for round_idx in range(3):
+                    root = f"/fake-env-{round_idx}"
+                    # Pre-create each worker's top-level w{i} directory so the
+                    # workers only mutate dicts inside their own subtree.
+                    for i in range(64):
+                        p.fs.create_dir(f"{root}/w{i}")
+                    asyncio.run(many(root, 64))
+                    for i in range(64):
+                        self.assertTrue(
+                            p.fs.exists(f"{root}/w{i}/a/b/c/file"),
+                            f"expected fake file {root}/w{i}/a/b/c/file to exist",
+                        )
+            finally:
+                stop_flag.set()
+                for h in hammers:
+                    h.join(timeout=1)
+
+
 if __name__ == "__main__":
     unittest.main()