python-extracontext 1.0.0__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.0"
+
+__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,19 @@
+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,264 @@
+"""
+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):
+        print(f"\n***************init {type(self)}")
+        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,71 @@
+from collections.abc import Mapping, 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, initial: None | Mapping = None, *, backend=None):
+    # super().__init__()
+    # if not initial:
+    # return
+    # for key, value in initial.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(ContextMap, PyContextLocal):
+    _backend_key = "python"
+    _BASEDIST = 1
+
+    def __init__(self, initial: None | Mapping = None, *, backend=None):
+        super().__init__()
+        if not initial:
+            return
+        try:
+            self._BASEDIST = 2
+            for key, value in initial.items():
+                self[key] = value
+        finally:
+            del self._BASEDIST
+
+
+class NativeContextMap(ContextMap, NativeContextLocal):
+    _backend_key = "native"
+
+    def __init__(self, initial: None | Mapping = None, *, backend=None):
+        super().__init__()
+        if not initial:
+            return
+        for key, value in initial.items():
+            self[key] = value

python_extracontext-1.0.0.dist-info/METADATA

@@ -0,0 +1,562 @@
+Metadata-Version: 2.1
+Name: python-extracontext
+Version: 1.0.0
+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"
+
+# Extracontext: Context Local Variables for everyone
+
+## Description
+
+Provides [PEP 567](https://peps.python.org/pep-0567/)
+compliant drop-in replacement for `threading.local`
+namespaces.
+
+The main goal of PEP 567, supersedding [PEP 550](https://peps.python.org/pep-0550/)
+is to create a way to preserve information in
+concurrent running contexts, including multithreading
+and asynchronous (asyncio) tasks, allowing
+each call stack to have its own versions of
+variables containing settings, or request
+parameters.
+
+### Quoting from PEP 567 Rationalle:
+> Thread-local variables are insufficient for asynchronous
+> tasks that execute concurrently in the same OS thread.
+> Any context manager that saves and restores a context
+> value using threading.local() will have its context values
+> bleed to other code unexpectedly when used in async/await code.
+
+## Rationale for "extracontext"
+
+Contextcars, introduced in Python 3.7, were
+implemented following a design decision by the
+which opted-out of the namespace approach
+used by Python's own `threading.local`
+implementation. It then 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. Also, the only way to run some code in
+an isolated context copy is to call a function
+indirectly through means of the context object  `.run` method.
+This implies that:
+
+1. Knowing when to run something in a different context is responsability of the caller code
+2. Breaks the easy-to-use, easy-to-read, aesthetics, and overal complicates one of the most fundamental blocks of programming in inperative languages: calling functions.
+
+This package does away with that, and brings simplicity
+back, using dotted attributes to a namespace and `=`
+for value assigment:
+
+with stdlib native contexvars:
+
+```python
+import contextvars
+
+# Variable declaration: top level declaration and WET (write everything twice)
+ctx_color = contextvars.ContextVar("ctx_color")
+ctx_font = contextvars.ContextVar("ctx_font")
+
+def blah():
+    ...
+    # use  a set method:
+    ctx_color.set("red")
+    ctx_font.set("arial")
+
+    ...
+    myttext = ...
+    # call a markup render function,
+    # but take care it wont mix our attributes in temporary context changes
+    contextvars.context_copy().run(render_markup, mytext))
+    ...
+
+def render_markup(text):
+    # markup function: knows it will mess up the context, but can't do
+    # a thing about it - the caller has to take care!
+    ...
+```
+
+with extracontext:
+
+```python
+import extracontext
+
+# the only declaration needed at top level code
+ctx = extracontext.ContextLocal()
+
+def blah():
+    ctx.color = "red"
+    ctx.font = "arial"
+
+    mytext = ...
+    # simply calls  the function
+    render_markup(mytext)
+    ...
+
+@ctx
+def render_markup(text):
+    # we will mess the context - but the decorator
+    # ensures no changes leak back to the caller
+    ...
+
+```
+
+## Usage
+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
+
+
+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:
+
+### extracontext namespaces work for generators
+
+Unlike PEP 567 contextvars, extracontext
+will sucessfully isolate contexts whe used with
+generator-functions - meaning,
+the generator body is actually executed in
+an isolated context:
+
+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))
+```
+
+This is virtually impossible with contextvars.  (Ok,
+not impossible - the default extracontext backend
+does that using contextvars after all - but it encapsulates
+the complications for you)
+
+This feature also works with async generators`
+
+
+Another example of this feature:
+
+```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
+```
+
+
+### Change context within  a context-manager `with` block:
+
+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
+
+
+```
+
+
+### Map namespaces
+
+Beyond namespace usages, `extracontext` offer ways
+to have contexts working as mutable mappings,
+using the `ContextMap` class.
+
+
+```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"
+
+
+```
+
+### typing support
+There is no explicit typing support yet - but note that through the use of
+`ContextMap` it is possible to have declare some types, by
+simple declaring `Mapping[type1:type2]` typing.
+
+
+## Specification and Implementation
+
+### ContextLocal
+
+`ContextLocal`  is the main class, and should suffice for most uses.
+It only takes the `backend` keyword-only argument,  which selects
+the usage of the pure-Python backend (`"python"`) or using
+a contextvars.ContextVar backend (`"native"`). The later is the default
+behavior. Calling this class will actually create
+an instance of the appropriate subclass, according to
+the backend: either `PyContextLocal` or `NativeContextLocal` -
+ in the same way stdlib `pathlib.Path` creates
+an instance of Path appropriate for Posix, or Windows style
+paths. (This pattern probably have a name - help welcome).
+
+An instance of it will create a new, fresh, namespace.
+Use dotted attribute access to populate it - each variable set
+in this way will persist through the context lifetime.
+
+#### Usage as a decorator:
+When used as a decorator for a function or method, that callable
+will automatically be executed in a copy of the calling context -
+meaning no changes it makes to any variable in the namespace
+is visible outside of the call.
+
+The decorator (and the isolation provided) works for
+both plain functions, generator functions, co-routine functions
+and async generator functions - meaning that whenever the
+execution switches to the caller context
+(in `yield` or `await` expression) the context is
+restored to that of the caller, and when it
+re-enters the paused code block, the isolated
+context is restored.
+
+
+```python
+from extracontext import ContextLocal
+
+ctx = ContextLocal()
+
+@ctx
+def isolated_example():
+
+    ctx.value = 2
+    assert ctx.value = 2
+
+ctx.value = 1
+isolated_example()
+assert ctx.value == 1
+
+```
+
+#### Usage as a context manager
+
+A `ContextLocal` instance can simply be used in a
+context manager `with` statement, and any variables
+set or changed within the block will not be
+persisted after the block is over.
+
+```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
+
+```
+
+Also, they are re-entrant, so if in a function called
+within the block, the context is used again
+as a context manager, it will just work.
+
+
+#### Semantic difference to contextvars.ContextVar
+   Note that a fresh `ContextLocal()` instance will
+be empty, and have access to none of the values _or names_
+set in another instance. This contrasts sharply with
+`contextvars.Context`, for which each `contextvars.ContextVar`
+created anywhere else in the program (even 3rd party
+modules) is a valid key.
+
+
+### PyContextLocal
+ContextLocal implementation using pure Python code, and
+reimplementing the functionalities of Contexts and ContextVars
+as implemented by PEP 567 fro scratch.
+
+It works by seeting, in a "hidden" way, values in the caller's
+closure (the `locals()` namespace). Though writting
+to this namespace has traditionally been a "grey area"
+in  Python, the way it makes use of this data is compliant
+with the specs in [PEP-558](https://peps.python.org/pep-0558/)
+which officializes this use for Python 3.13 and beyond
+(and it has always worked since Python 3.0.
+The first implementations of this code where
+tested against Python 3.4 and forward)
+
+It should be kept in place for the time being,
+and could be useful to allow customizations,
+workarounds, or buggy behavior bypassing
+where the native implementation presents
+any short-commings.
+
+It is not an easy to follow code, as in
+one hand there are introspection and meta-programming
+patterns to handle access to the data in a containirized way.
+
+Keep in mind that native contexvars use an
+internal copy-on-write structure in  native code
+which should be much more performant than
+the chain-mapping checks used in this backend.
+
+
+It has been throughfully tested and should be bug free,
+though less performant.
+
+### NativeContextLocal
+
+This leverages on PEP 567 Contexts and ContextVars
+to perform all the isolation and setting mechanics,
+and provides an convenient wrapper layer
+which works as a namespace (and as mapping in NativeContextMap)
+
+It was made the default mechanism due to obvious
+performances and updates taking place in the
+embedded implementation in the language.
+
+The normal ContextVarsAPI exposed to Python
+would not allow for changing context inside the
+same function, requiring a `Context.run` call
+as the only way to switch contexts. Instead of releasing this
+backend without this mechanism, it has been opted
+to call the native cAPI for changing
+context (using `ctypes` in cPython, and the relevant internal
+calls on pypy) so that the feature can work.
+
+When this feature was implemented, `NativeContextLocal`
+instances could then work as a context-manager using
+the `with` statement, and there were no reasons why
+they should not be the default backend. Some
+coding effort were placed in the "Reverse subclass picking"
+mechanism, and it was made te default in a backwards-
+compatible way.
+
+### ContextMap
+
+`ContextMap` is a `ContextLocal` subclass which implements
+[the `MutableMapping` interface](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping).
+It is pretty straightforward in
+that, so that assigments and retrievals using the `ctx["key"]`
+syntax are made available, functionality with the
+`in`, `==`, `!=` operators and the `keys`, `items`, `values`, `get`, `pop`, `popitem`, `clear`, `update`, and `setdefault` methods.
+
+It supports loadding a mapping with the initial context contents, passed as
+the `initial` positional argument - but not keyword-args mapping to initial
+content (as in `dict(a=1)`).
+
+Also, it is a subclass of ContextLocal - so it also allows access to the
+keys with the dotted attribute syntax:
+
+```python
+
+a = extracontext.ContextMap
+
+a["b"] = 1
+
+assert a.b == 1
+
+```
+
+And finally, it uses the same `backend` keyword-arg mechanism to switch between the default
+native-context vars backend and the pure Python backend, which will yield either
+a `PyContextMap` or a `NativeContextMap` instance, accordingly.
+
+### PyContextMap
+`ContextMap` implementation as a subclass of `PyContextLocal`
+
+### NativeContextMap
+`ContextMap` implementation as a subclass of `NativeContextLocal`
+
+
+
+### History
+The original implementation from 2019 re-creates
+all the functionality provided by the PEP 567
+contextvars using pure Python code and a lot
+of introspection and meta-programming.
+Not sure why it did that - but one thing is that
+it coud provide the functionality for older
+Pythons at the time, and possibly also because
+I did not see, at the time, other ways
+to workaround the need to call a function
+in order to switch contexts.
+
+At some revival sprint in 2021, a backend
+using native contextvars was created -
+and it just got to completion,
+with all features and tests for the edge clases in
+August 2024, after other periods of non-activity.
+
+At this point, a mechanism for picking the
+desired backend was implemented, and the native
+`ContextLocal` class was switched to use the
+native stdlib contextvars as backend by default.
+(This should be much faster - benchmark
+contributions are welcome, though :-)  )
+
+
+## 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
+
+1. Implementing more of the features possible with the contextvars semantics
+  - `.run` and `.copy` methods
+  - direct access to "`Token`"s as used by contextvars
+  - default value setting for variables
+
+1. A feature allowing other threads to start from a copy of the current context, instead of an empty context. (asyncio independent tasks always see a copy)
+
+1. Bringing in some more typing support
+(not sure what will be possible, but I believe some
+`typing.Protocol` templates at least. On an
+initial search, typing for namespaces is not
+a widelly known feature (if at all)
+
+1. (maybe?) Proper multiprocessing support:
+  - ironing out probable serialization issues,
+  - allowing subprocess workers to start from a copy of the current context.
+
+1. (maybe?) support for nested namespaces and maps.
+
+### Old "Next Steps":
+-----------
+(not so sure about these - they are fruit of some 2019 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.

python_extracontext-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+extracontext/__init__.py,sha256=ZzNamvA_xkIovBmRzh11yjjj9ReObwXTYUAVFtxadI8,314
+extracontext/_future_task.py,sha256=PEPWIJDdpLvvu90r-rD5btHnnyVTJ1dghiggURIbTW8,1898
+extracontext/base.py,sha256=cuAAD93HdzfQp5kVIsB_vzY74o4j603cXgtB_HaelYM,663
+extracontext/contextlocal.py,sha256=xEjqgHJ5vs44geSWCsoHJZ4RkcPVU7ZngHLI_Gh-pvU,9896
+extracontext/contextlocal_native.py,sha256=uE67YmO-i40vd89AWOR67_AnnHW1milTPycZuGrNmKM,8771
+extracontext/mapping.py,sha256=IQvJreYKGujBIlcrq7GXVggopORaMT3SyIeLXNCkM1A,1888
+python_extracontext-1.0.0.dist-info/METADATA,sha256=FKiYOthSEoTvug6FV2D04U9-3uWAHHSjG8q4ExQe0F4,17980
+python_extracontext-1.0.0.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+python_extracontext-1.0.0.dist-info/top_level.txt,sha256=r0JvexrESeoDk32GNGKs1pSnl-SA_3YiMrDcGIT952A,13
+python_extracontext-1.0.0.dist-info/RECORD,,

python_extracontext-1.0.0.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.0.dist-info/top_level.txt

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