python-extracontext 1.0.0b1__py3-none-any.whl

extracontext/__init__.py

@@ -0,0 +1,14 @@
+from .base import ContextLocal
+from .contextlocal import PyContextLocal, ContextError
+from .mapping import ContextMap
+from .contextlocal_native import NativeContextLocal
+
+__version__ = "1.0.0b1"
+
+__all__ = [
+    "ContextLocal",
+    "ContextMap",
+    "PyContextLocal",
+    "ContextError",
+    "NativeContextLocal",
+]

extracontext/_future_task.py

@@ -0,0 +1,59 @@
+"""
+Code backported from Python 3.12:
+Task.__init__ will accept a "contxt" parameter that is needed
+in order to re-use contexts for async generator iterations.
+
+
+The subclass is created in order for the minimal of "copy-pasting" around
+to be needed.
+
+# **** License for this file: PSF License - ****
+"""
+
+import contextvars
+import itertools
+from asyncio.tasks import _PyTask, _register_task
+
+# from asyncio import futures
+
+from asyncio import coroutines
+
+
+_task_name_counter = itertools.count(1).__next__
+
+
+class FutureTask(_PyTask):
+    # Just overrides __init__ with Python 3.12 _PyTask.__init__,
+    # which accepts the context as argument
+
+    def __init__(self, coro, *, loop=None, name=None, context=None, eager_start=False):
+        # skip Python < 3.10 Task.__init__ :
+        super(_PyTask, self).__init__(loop=loop)
+        if self._source_traceback:
+            del self._source_traceback[-1]
+        if not coroutines.iscoroutine(coro):
+            # raise after Future.__init__(), attrs are required for __del__
+            # prevent logging for pending task in __del__
+            self._log_destroy_pending = False
+            raise TypeError(f"a coroutine was expected, got {coro!r}")
+
+        if name is None:
+            self._name = f"FutureTask-{_task_name_counter()}"
+        else:
+            self._name = str(name)
+
+        self._num_cancels_requested = 0
+        self._must_cancel = False
+        self._fut_waiter = None
+        self._coro = coro
+        if context is None:
+            # this is the only codepath in Python < 3.10, and the reason for this hack:
+            self._context = contextvars.copy_context()
+        else:
+            self._context = context
+
+        if eager_start and self._loop.is_running():
+            self.__eager_start()
+        else:
+            self._loop.call_soon(self._Task__step, context=self._context)
+            _register_task(self)

extracontext/base.py

@@ -0,0 +1,20 @@
+class ContextLocal:
+    _backend_registry = {}
+
+    def __new__(cls, *args, backend=None, **kwargs):
+        if backend is None:
+            backend = getattr(cls, "_backend_key", "native")
+
+        cls = cls._backend_registry[backend]
+        ## Do not forward arguments to object.__new__
+        if len(__class__.__mro__) == 2:
+            args, kwargs = (), {}
+        return super().__new__(cls, *args, **kwargs)
+
+    def __init__(self, *, backend=None):
+        pass
+
+    def __init_subclass__(cls, *args, **kw):
+        if hasattr(cls, "_backend_key"):
+            cls._backend_registry[cls._backend_key] = cls
+        super().__init_subclass__(*args, **kw)

extracontext/contextlocal.py

@@ -0,0 +1,263 @@
+"""
+Super context wrapper -
+
+meant to be simpler to use and work in more scenarios than
+Python's contextvars.
+
+Usage:
+Create one or more project-wide instances of "ContextLocal"
+Decorate your functions, co-routines, worker-methods and generators
+that should hold their own states with that instance's `context` method -
+
+and use the instance as namespace for private variables that will be local
+and non-local until entering another callable decorated
+with that instance - that will create a new, separated scope
+visible inside  the decorated callable.
+
+
+"""
+
+import uuid
+import sys
+import typing as T
+
+from functools import wraps
+from types import FrameType
+from weakref import WeakKeyDictionary
+
+from .base import ContextLocal
+
+__author__ = "João S. O. Bueno"
+__license__ = "LGPL v. 3.0+"
+
+
+class ContextError(AttributeError):
+    pass
+
+
+_sentinel = object()
+
+
+class _WeakableId:
+    """Used internally to identify Frames with context data attached using weakrefs"""
+
+    __slots__ = ["__weakref__", "value"]
+
+    def __init__(self, v=0):
+        if not v:
+            v = int(uuid.uuid4())
+        self.value = v
+
+    def __eq__(self, other):
+        return self.value == other.value
+
+    def __hash__(self):
+        return hash(self.value)
+
+    def __repr__(self):
+        return f"ID({uuid.UUID(int=self.value)})"
+
+
+class PyContextLocal(ContextLocal):
+    """Creates a namespace object whose attributes can keep individual and distinct values for
+    the same key for code running in parallel - either in asyncio tasks, or threads.
+
+    The bennefits are the same one gets by using contextvars.ContextVar from the stdlib as
+    specified on PEP 567. However extracontext.ContextLocal is designed to be easier
+    and more convenient to use - as a single instance can hold values for several
+    keys, just as happens with threading.local objects. And no special getter and
+    setter methods are needed to retrieve the unique value stored in the current
+    context: normal attribute access and assignment works transparently.
+
+    Internally, the current implementation uses a completly different way to
+    keep distinct states where needed: the "locals" mapping for each execution
+    frame is used as storage for the unique values in an async task context, or in
+    a thread. Although not recomended up to now, read/write access to non-local-variables
+    in the "locals" mapping is specified on PEP 558. While that PEP is not
+    final, it is clear in its texts that the capability of using "locals" as
+    a mapping to convey data will be kept and made official.
+
+    References to the frames containing context data is kept using
+    weakreferences, so when a Frame ends up execution, its contents
+    are deleted normally, with no risks of frame data
+    hanging around due to PyContextLocal data.
+
+
+    """
+
+    # TODO: change _BASEDIST to a property counting the intermediate
+    # methods between subclasses and the methods here.
+    _BASEDIST = 0
+
+    _backend_key = "python"
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        super().__setattr__("_et_registry", WeakKeyDictionary())
+
+    def _introspect_registry(
+        self, name: T.Optional[str] = None, starting_frame: int = 2
+    ) -> T.Tuple[dict, T.Tuple[int, int]]:
+        """
+        returns the first namespace found for this context, if name is None
+        else, the first namespace where the name exists. The second return
+        value is a tuple inticatind the frame distance to the topmost namespace
+        and the frame distance to the returned namespace.
+        This way callers can tell if the searched name is on the topmost
+        namespace and act accordingly. ("del" needs this information,
+        as it can't remove information on an outter namespace)
+        """
+        starting_frame += self._BASEDIST
+        f: T.Optional[FrameType] = sys._getframe(starting_frame)
+        count = 0
+        first_ns = None
+        while f:
+            hf = self._frameid(f)
+            if hf in self._et_registry:
+                if first_ns is None:
+                    first_ns = count
+                registered_namespaces = f.f_locals["$contexts"]
+                for namespace_index in reversed(self._et_registry[hf]):
+                    namespace = registered_namespaces[namespace_index]
+                    if name is None or name in namespace:
+                        return namespace, (first_ns, count)
+                    count += 1
+            f = f.f_back
+
+        if name:
+            raise ContextError(f"{name !r} not defined in any previous context")
+        raise ContextError("No previous context set")
+
+    def _frameid(self, frame: FrameType) -> _WeakableId:
+        if not "$contexts_salt" in frame.f_locals:
+            frame.f_locals["$contexts_salt"] = _WeakableId()
+        return frame.f_locals["$contexts_salt"]
+
+    def _register_context(self, f: FrameType) -> None:
+        hf = self._frameid(f)
+        contexts_list = f.f_locals.setdefault("$contexts", [])
+        contexts_list.append({})
+        self._et_registry.setdefault(hf, []).append(len(contexts_list) - 1)
+
+    def _pop_context(self, f: FrameType) -> None:
+        hf = self._frameid(f)
+        context_being_popped = self._et_registry[hf].pop()
+        contexts_list = f.f_locals["$contexts"]
+        contexts_list[context_being_popped] = None
+
+    def __getattr__(self, name: str) -> T.Any:
+        try:
+            namespace, _ = self._introspect_registry(name)
+            result = namespace[name]
+            if result is _sentinel:
+                raise KeyError(name)
+            return result
+        except (ContextError, KeyError):
+            raise AttributeError(f"Attribute not set: {name}")
+
+    def __setattr__(self, name: str, value: T.Any) -> None:
+        try:
+            namespace, _ = self._introspect_registry()
+        except ContextError:
+            # Automatically creates a new namespace if not inside
+            # any explicit denominated context:
+            self._register_context(sys._getframe(1 + self._BASEDIST))
+            namespace, _ = self._introspect_registry()
+
+        namespace[name] = value
+
+    def __delattr__(self, name: str) -> None:
+        try:
+            namespace, (topmost_ns, found_ns) = self._introspect_registry(name)
+        except ContextError:
+            raise AttributeError(name)
+        if topmost_ns == found_ns:
+            result = namespace[name]
+            if result is not _sentinel:
+                if "$deleted" in namespace and name in namespace["$deleted"]:
+                    # attribute exists in target namespace, but the outter
+                    # attribute had previously been shadowed by a delete -
+                    # restore the shadowing:
+                    setattr(self, name, _sentinel)
+
+                else:
+                    # Remove topmost name assignemnt, and outer value is exposed
+                    # ("one_level" attribute stacking behavior as described in 'features.py'
+                    # disbled as unecessaryly complex):
+                    # del namespace[name]
+
+                    # To preserve  "entry_only" behavior:
+                    namespace.setdefault("$deleted", set()).add(name)
+                    setattr(self, name, _sentinel)
+                return
+            # value is already shadowed:
+            raise AttributeError(name)
+
+        # Name is found, but it is not on the top-most level, so attribute is shadowed:
+        setattr(self, name, _sentinel)
+        # fossil: namespace, _ = self._introspect_registry(name)
+        namespace.setdefault("$deleted", set()).add(name)
+
+    def __call__(self, callable_: T.Callable) -> T.Callable:
+        @wraps(callable_)
+        def wrapper(*args, **kw):
+            f = sys._getframe()
+            self._register_context(f)
+            f_id = self._frameid(f)
+            result = _sentinel
+            try:
+                result = callable_(*args, **kw)
+            finally:
+                if f_id in self._et_registry:
+                    del self._et_registry[f_id]
+                # Setup context for generator, async generator or coroutine if one was returned:
+                if result is not _sentinel:
+                    frame = None
+                    for frame_attr in ("gi_frame", "ag_frame", "cr_frame"):
+                        frame = getattr(result, frame_attr, None)
+                        if frame:
+                            self._register_context(frame)
+            return result
+
+        return wrapper
+
+    def __enter__(self):
+        self._register_context(sys._getframe(1))
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self._pop_context(sys._getframe(1))
+
+    def _run(self, callable_, *args, **kw):
+        """Runs callable with an isolated context
+        no need to decorate the target callable
+        """
+        with self:
+            return callable_(*args, **kw)
+
+    def __dir__(self) -> T.List[str]:
+        frame_count = 2
+        all_attrs = set()
+        seen_namespaces = set()
+        while True:
+            try:
+                namespace, _ = self._introspect_registry(starting_frame=frame_count)
+            except (
+                ValueError,
+                ContextError,
+            ):  # ValueError can be raised sys._getframe inside _introspect_registry
+                break
+            frame_count += 1
+            if id(namespace) in seen_namespaces:
+                continue
+            for key, value in namespace.items():
+                if not key.startswith("$") and value is not _sentinel:
+                    all_attrs.add(key)
+
+            seen_namespaces.add(id(namespace))
+        all_attrs = (
+            attr
+            for attr in all_attrs
+            if getattr(self, attr, _sentinel) is not _sentinel
+        )
+        return sorted(all_attrs)

extracontext/contextlocal_native.py

@@ -0,0 +1,262 @@
+"""
+Super context wrapper -
+
+Meant to have the same interface as the easy-to-use PyContextLocal,
+implemented 100% in Python, but backed by PEP 567 stdlib contextvar.ContextVar
+
+
+"""
+
+import asyncio
+import inspect
+import sys
+import threading
+
+from functools import wraps
+from contextvars import ContextVar, copy_context
+
+from .base import ContextLocal
+
+if sys.implementation.name == "pypy":
+    pypy = True
+    from __pypy__ import (
+        get_contextvar_context as _get_contextvar_context,
+        set_contextvar_context as _set_contextvar_context,
+    )
+
+else:
+    pypy = False
+    try:
+        import ctypes
+    except ImportError as error:
+        import warnings
+
+        warnings.warn(
+            f"Couldn't import ctypes! `with` context blocks for NativeContextLocal won't work:\n {error.msg}"
+        )
+        warnings.warn(
+            "\n\nIf you need this feature in subinterpreters, please open a project issue"
+        )
+
+if sys.version_info < (3, 10):
+    from types import AsyncGeneratorType
+
+    anext = AsyncGeneratorType.__anext__
+
+__author__ = "João S. O. Bueno"
+__license__ = "LGPL v. 3.0+"
+
+_sentinel = object()
+
+
+class NativeContextLocal(ContextLocal):
+    """Uses th native contextvar module in the stdlib (PEP 567)
+    to provide a context-local namespace in the way
+    threading.local  works for threads.
+
+    Assignements and reading from the namespace
+    should work naturally with no need to call `get` and `set` methods.
+
+    A new contextvar variable is created in the current (contextvars) context
+    for _each_ attribute acessed on this namespace.
+
+    Also, attributes prefixed with a single "_et_" are intended for internal
+    use and will not be namespaced contextvars.
+
+    # In contrast to the pure-Python implementation there are
+    # some limitations,such as the impossibility to work
+    # in as a contextmanager (Python `with` block),.
+
+    [Work In Progress]
+    """
+
+    _backend_key = "native"
+    _ctypes_initialized = False
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._et_registry = {}
+        self._et_stack = {}
+        self._et_lock = threading.Lock()
+
+    def __getattr__(self, name):
+        var = self._et_registry.get(name, None)
+        if var is None:
+            raise AttributeError(f"Attribute not set: {name}")
+        try:
+            value = var.get()
+        except LookupError as error:
+            raise AttributeError from error
+        if value is _sentinel:
+            raise AttributeError(f"Attribute not set: {name}")
+        return value
+
+    def __setattr__(self, name, value):
+        if name.startswith("_et_"):
+            return super().__setattr__(name, value)
+        var = self._et_registry.get(name, _sentinel)
+        if var is _sentinel:
+            var = self._et_registry[name] = ContextVar(name)
+        var.set(value)
+
+    def __delattr__(self, name):
+        if getattr(self, name, _sentinel) is _sentinel:
+            raise AttributeError(f"Attribute not set: {name}")
+        setattr(self, name, _sentinel)
+
+    def __call__(self, callable_):
+        @wraps(callable_)
+        def wrapper(*args, **kw):
+            return self._run(callable_, *args, **kw)
+
+        return wrapper
+
+    def _ensure_api_ready(self):
+        if not self._ctypes_initialized:
+            ctypes.pythonapi.PyContext_Enter.argtypes = [ctypes.py_object]
+            ctypes.pythonapi.PyContext_Exit.argtypes = [ctypes.py_object]
+            ctypes.pythonapi.PyContext_Enter.restype = ctypes.c_int32
+            ctypes.pythonapi.PyContext_Exit.restype = ctypes.c_int32
+            self.__class__._ctypes_initialized = True
+
+    def _get_ctx_key(self):
+        key_thread = threading.current_thread()
+        try:
+            key_task = asyncio.current_task()
+        except RuntimeError:
+            key_task = None
+        return (key_thread, key_task)
+
+    def _enter_ctx(self, new_ctx):
+        if pypy:
+            prev_ctx = _get_contextvar_context()
+            _set_contextvar_context(new_ctx)
+            return prev_ctx
+        self._ensure_api_ready()
+        result = ctypes.pythonapi.PyContext_Enter(new_ctx)
+        if result != 0:
+            raise RuntimeError(f"Something went wrong entering context {new_ctx}")
+        return None
+
+    def _exit_ctx(self, current_ctx, prev_ctx):
+        if pypy:
+            _set_contextvar_context(prev_ctx)
+            return
+        result = ctypes.pythonapi.PyContext_Exit(current_ctx)
+        if result != 0:
+            raise RuntimeError(f"Something went wrong exiting context {current_ctx}")
+
+    def __enter__(self):
+        new_ctx = copy_context()
+        prev_ctx = self._enter_ctx(new_ctx)
+        with self._et_lock:
+            self._et_stack.setdefault(self._get_ctx_key(), []).append(
+                (new_ctx, prev_ctx)
+            )
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        key = self._get_ctx_key()
+        with self._et_lock:
+            current_ctx, prev_ctx = self._et_stack[key].pop()
+            if not self._et_stack[key]:
+                self._et_stack.pop(key)
+        self._exit_ctx(current_ctx, prev_ctx)
+
+    def _run(self, callable_, *args, **kw):
+        """Runs callable with an isolated context
+        no need to decorate the target callable
+        """
+        new_context = copy_context()
+        result = new_context.run(callable_, *args, **kw)
+        if inspect.isawaitable(result):
+            result = self._awaitable_wrapper(result, new_context)
+        elif inspect.isgenerator(result):
+            result = self._generator_wrapper(result, new_context)
+        elif inspect.isasyncgen(result):
+            result = self._async_generator_wrapper(result, new_context)
+            # raise NotImplementedError("NativeContextLocal doesn't yet work with async generators")
+        return result
+
+    @staticmethod
+    def _generator_wrapper(generator, ctx_copy):
+        value = None
+        while True:
+            try:
+                if value is None:
+                    value = yield ctx_copy.run(next, generator)
+                else:
+                    value = yield ctx_copy.run(generator.send, value)
+            except StopIteration as stop:
+                return stop.value
+            except Exception as exc:
+                # for debugging times: this will be hard without a break here!
+                # print(exc)
+                try:
+                    value = ctx_copy.run(generator.throw, exc)
+                except StopIteration as stop:
+                    return stop.value
+
+    if sys.version_info >= (3, 11):
+
+        async def _awaitable_wrapper(self, coro, ctx_copy):
+            def trampoline():
+                return asyncio.create_task(coro, context=ctx_copy)
+
+            return await ctx_copy.run(trampoline)
+
+    else:
+
+        async def _awaitable_wrapper(self, coro, ctx_copy):
+            from ._future_task import FutureTask
+
+            loop = asyncio.get_running_loop()
+
+            def trampoline():
+                return FutureTask(coro, loop=loop, context=ctx_copy)
+
+            return await ctx_copy.run(trampoline)
+
+        ## this fails in spetacular and inovative ways!
+        # async def _awaitable_wrapper(self, coro, ctx_copy, force_context=True):
+        # if force_context:
+        # try:
+        # self._enter_ctx(ctx_copy)
+        # result = await coro
+        # finally:
+        # self._exit_ctx(ctx_copy)
+        # return result
+        # else:
+        # return await coro
+
+        async def _awaitable_wrapper2(self, coro, ctx_copy):
+            raise NotImplementedError(
+                """This code will only work with Python versions > 3.11. Please use `ContextLocal(backend="python")` for Python version 3.8 - 3.10"""
+            )
+
+    async def _async_generator_wrapper(self, generator, ctx_copy):
+        value = None
+        while True:
+            try:
+                if value is None:
+                    async_res = ctx_copy.run(anext, generator)
+                else:
+                    async_res = ctx_copy.run(generator.asend, value)
+                value = yield await self._awaitable_wrapper(async_res, ctx_copy)
+            except StopAsyncIteration:
+                break
+            except Exception as exc:
+                # for debugging times: this will be hard without a break here!
+                # print("*" * 50 , exc)
+                try:
+                    async_res = ctx_copy.run(generator.athrow, exc)
+                    value = yield await self._awaitable_wrapper(async_res, ctx_copy)
+                except StopAsyncIteration:
+                    break
+
+    def __dir__(self):
+        return list(
+            key
+            for key, value in self._et_registry.items()
+            if value.get() is not _sentinel
+        )

extracontext/mapping.py

@@ -0,0 +1,51 @@
+from collections.abc import MutableMapping
+
+from .base import ContextLocal
+from .contextlocal import PyContextLocal
+from .contextlocal_native import NativeContextLocal
+
+
+class ContextMap(MutableMapping, ContextLocal):
+    """Works the same as PyContextLocal,
+    but uses the mapping interface instead of dealing with instance attributes.
+
+    Ideal, as for most map uses, when the keys depend on data rather than
+    hardcoded state variables
+    """
+
+    _backend_registry = {}
+
+    def __init__(self, *, backend=None, **kwargs):
+        super().__init__()
+        for key, value in kwargs.items():
+            self[key] = value
+
+    def __getitem__(self, name):
+        try:
+            return self.__getattr__(name)
+        except AttributeError:
+            raise KeyError(name)
+
+    def __setitem__(self, name, value):
+        setattr(self, name, value)
+
+    def __delitem__(self, name):
+        try:
+            delattr(self, name)
+        except AttributeError:
+            raise KeyError(name)
+
+    def __iter__(self):
+        return iter(dir(self))
+
+    def __len__(self):
+        return len(dir(self))
+
+
+class PyContextMap(PyContextLocal, ContextMap):
+    _backend_key = "python"
+    _BASEDIST = 1
+
+
+class NativeContextMap(NativeContextLocal, ContextMap):
+    _backend_key = "native"

python_extracontext-1.0.0b1.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.1
+Name: python-extracontext
+Version: 1.0.0b1
+Summary: Context Variable namespaces supporting generators, asyncio and multi-threading
+Author: Joao S. O. Bueno
+Project-URL: repository, https://github.com/jsbueno/extracontext
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pyflakes; extra == "dev"
+Requires-Dist: pytest-coverage; extra == "dev"
+
+Context Local Variables
+==========================
+
+Implements a Pythonic way to work with PEP 567
+contextvars (https://peps.python.org/pep-0567/ )
+
+Introduced in Python 3.7, a design decision by the
+authors of the feature decided to opt-out of
+the simple namespace used by Python's own `threading.local`
+implementation, and requires an explicit top level
+declaration of each context-local variable, and
+the (rather "unpythonic") usage of an explicit
+call to `get` and `set` methods to manipulate
+those.
+
+This package does away with that, and brings simplicity
+back - simply instantiate a `ContextLocal` namespace,
+and any attributes set in that namespace will be unique
+per thread and per asynchronous call chain (i.e.
+unique for each independent task).
+
+In a sense, these are a drop-in replacement for
+`threading.local`, which will also work for
+asynchronous programming without any change in code.
+
+One should just avoid creating the "ContextLocal" instance itself
+in a non-setup function or method - as the implementation
+uses Python contextvars in by default, those are not
+cleaned-up along with the local scope where they are
+created - check the docs on the contextvar module for more
+details.
+
+However, creating the actual variables to use inside this namespace
+can be made local to functions or methods: the same inner
+ContextVar instance will be re-used when re-entering the function
+
+
+Usage:
+
+Create one or more project-wide instances of "extracontext.ContextLocal"
+Decorate your functions, co-routines, worker-methods and generators
+that should hold their own states with that instance itself, using it as a decorator
+
+and use the instance as namespace for private variables that will be local
+and non-local until entering another callable decorated
+with the instance itself - that will create a new, separated scope
+visible inside  the decorated callable.
+
+```python
+
+from extracontext import ContextLocal
+
+# global namespace, available in any thread or async task:
+ctx = ContextLocal()
+
+def myworker():
+    # value set only visible in the current thread or asyncio task:
+    ctx.value = "test"
+
+
+```
+
+More Features:
+
+Unlike `threading.local` namespaces, one can explicitly isolate a contextlocal namespace
+when calling a function even on the same thread or same async call chain (task). And unlike
+`contextvars.ContextVar`, there is no need to have an explicit context copy
+and often an intermediate function call to switch context: `extracontext.ContextLocal`
+can isolate the context using either a `with` block or as a decorator
+(when entering the decorated function, all variables in the namespace are automatically
+protected against any changes that would be visible when that call returns,
+the previous values being restored).
+
+
+Example showing context separation for concurrent generators:
+
+
+
+```python
+from extracontext import ContextLocal
+
+
+ctx = ContextLocal()
+
+results = []
+@ctx
+def contexted_generator(value):
+    ctx.value = value
+    yield None
+    results.append(ctx.value)
+
+
+
+def runner():
+    generators = [contexted_generator(i) for i in range(10)]
+    any(next(gen) for gen in generators)
+    any(next(gen, None) for gen in generators)
+    assert results == list(range(10))
+```
+
+ContextLocal namespaces can also be isolated by context-manager blocks (`with` statement):
+
+```python
+from extracontext import ContextLocal
+
+
+def with_block_example():
+
+    ctx = ContextLocal()
+    ctx.value = 1
+    with ctx:
+        ctx.value = 2
+        assert ctx.value == 2
+
+    assert ctx.value == 1
+
+
+```
+
+
+
+This is what one has to do if "isolated_function" will use a contextvar value
+for other nested calls, but should not change the caller's visible value:
+
+```python
+##########################
+# using stdlib contextvars:
+
+import contextvars
+
+# Each variable has to be declared at top-level:
+value = contextvars.ContextVar("value")
+
+def parent():
+    # explicit use of setter method for each value:
+    value.set(5)
+    # call to nested function which needs and isolated copy of context
+    # must be done in two stages:
+    new_context = contextvars.copy_context()
+    new_context.run(isolated_function)
+    # explicit use of getter method:
+    assert value.get() == 5
+
+def isolated_function()
+    value.set(23)
+    # run other code that needs "23"
+    # ...
+    assert value.get(23)
+
+
+```
+
+This is the same code using this package:
+```python
+from extracontext import NativeContextLocal
+
+# instantiate a namespace at top level:
+ctx = NativeContextLocal()
+
+def parent():
+    # create variables in the namespace without prior declaration:
+    # and just use the assignment operator (=)
+    ctx.value = 5
+    # no boilerplate to call function:
+    isolated_function()
+    # no need to call a getter:
+    assert ctx.value == 5
+
+# Decorate function that should run in an isolated context:
+@ctx
+def isolated_function()
+    assert ctx.value == 5
+    ctx.value = 23
+    # run other code that needs "23"
+    # ...
+    assert ctx.value == 23
+
+```
+
+Map namespaces
+-----------------
+
+The `ContextMap` class works just the same way, but works
+as a mapping:
+
+
+```python
+
+from extracontext import ContextMap
+
+# global namespace, available in any thread or async task:
+ctx = ContextMap()
+
+def myworker():
+    # value set only visible in the current thread or asyncio task:
+    ctx["value"] = "test"
+
+
+```
+
+Non Leaky Contexts
+-------------------
+Contrary to default contextvars usage, generators
+(and async generators) running in another context do
+take effect inside the generator, and doesn't
+leak back to the calling scope:
+
+```python
+import extracontext
+ctx = extracontext.ContextLocal()
+@ctx
+def isolatedgen(n):
+    for i in range(n):
+        ctx.myvar = i
+        yield i
+        print (ctx.myvar)
+def test():
+    ctx.myvar = "lambs"
+    for j in isolatedgen(2):
+        print(ctx.myvar)
+        ctx.myvar = "wolves"
+
+In [11]: test()
+lambs
+0
+wolves
+1
+```
+
+By using a stdlib `contextvars.ContextVar` one simply
+can't isolate the body of a generator, save by
+not running a `for` at all, and running all
+iterations manually by calling `ctx_copy.run(next, mygenerator)`
+
+
+
+New for 1.0
+-----------
+
+Switch the backend to use native Python contextvars (exposed in
+the stdlib "contextvars" module by default.
+
+Up to the update in July/Aug 2024 the core package functionality
+was provided by a pure Python implementation which keeps context state
+in a hidden frame-local variables - while that is throughfully tested
+it performs a linear lookup in all the callchain for the context namespace.
+
+ For the 0.3 release, the "native" stdlib contextvars.ContextVar backed class,
+ has reached first class status, and is now the default method used.
+
+ The extracontext.NativeContextLocal class builds on Python's contextvars
+ instead of reimplementing all the functionality from scratch, and makes
+ simple namespaces and decorator-based scope isolation just work, with
+ all the safety and performance of the Python native implementation,
+ with none of the boilerplate or confuse API.
+
+
+Next Steps:
+-----------
+(not so sure about these - they are fruit of some 2018 brainstorming for
+features in a project I am not coding for anymore)
+
+
+ 1. Add a way to chain-contexts, so, for example
+and app can have a root context with default values
+
+ 1. Describe the capabilities of each Context class clearly in a data-scheme,
+ so one gets to know, and how to retrieve classes that can behave like maps, or
+ allow/hide outter context values, work as a full stack, support the context protocol (`with` command),
+ etc... (this is more pressing since stlib contextvar backed Context classes will
+         not allow for some of the capabilities in the pure-Python reimplementation in "ContextLocal")
+
+ 1. Add a way to merge wrappers for different ContextLocal instances on the same function
+
+ 1. Add an "auto" flag - all called functions/generators/co-routines create a child context by default.
+
+ 1. Add support for a descriptor-like variable slot - so that values can trigger code when set or retrieved
+
+ 1. Shared values and locks: values that are guarranteed to be the same across tasks/threads, and a lock mechanism allowing atomic operations with these values. (extra bonus: try to develop a deadlock-proof lock)

python_extracontext-1.0.0b1.dist-info/RECORD

@@ -0,0 +1,10 @@
+extracontext/__init__.py,sha256=zAVHqTFP5Tl5hKVP0psbER4QIEUKfxXFiJjrQADvdWE,316
+extracontext/_future_task.py,sha256=PEPWIJDdpLvvu90r-rD5btHnnyVTJ1dghiggURIbTW8,1898
+extracontext/base.py,sha256=6TGVBdkZFr4vW18milFkOmzsw049wGuP9lyymBt5wqc,664
+extracontext/contextlocal.py,sha256=EQnR-6vWU7JyREeefxlMQC7zGAo5RV9qq_oTynHutZI,9843
+extracontext/contextlocal_native.py,sha256=uE67YmO-i40vd89AWOR67_AnnHW1milTPycZuGrNmKM,8771
+extracontext/mapping.py,sha256=oNmgLJnE-8_L46qZwpLEwJTIdX1ZRWg5FzlzepKaBf0,1295
+python_extracontext-1.0.0b1.dist-info/METADATA,sha256=atM3ybXCr-k7byEwiiVdf-7xS5GoZRPwWxSDWTN8u50,9361
+python_extracontext-1.0.0b1.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+python_extracontext-1.0.0b1.dist-info/top_level.txt,sha256=r0JvexrESeoDk32GNGKs1pSnl-SA_3YiMrDcGIT952A,13
+python_extracontext-1.0.0b1.dist-info/RECORD,,

python_extracontext-1.0.0b1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (72.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_extracontext-1.0.0b1.dist-info/top_level.txt

@@ -0,0 +1 @@
+extracontext