python-extracontext 1.0.0b1__tar.gz

python_extracontext-1.0.0b1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,279 @@
+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/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",
+]

python_extracontext-1.0.0b1/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)

python_extracontext-1.0.0b1/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)