proxytypes3 1.0.2__py3-none-any.whl

proxytypes3/__init__.py

@@ -0,0 +1,4 @@
+from .proxies import *
+
+VERSION = (1, 0, 2)
+__version__ = '.'.join(map(str, VERSION))

proxytypes3/proxies.py

@@ -0,0 +1,199 @@
+class AbstractProxy:
+    """
+    Delegates all operations (except ``.__subject__``) to another object.
+    """
+
+    __slots__ = ()
+
+    def __call__(self, *args, **kw):
+        return self.__subject__(*args, **kw)
+
+    def __getattribute__(self, attr, oga=object.__getattribute__):
+        subject = oga(self, '__subject__')
+        if attr == '__subject__':
+            return subject
+        return getattr(subject, attr)
+
+    def __setattr__(self, attr, val, osa=object.__setattr__):
+        if attr == '__subject__':
+            osa(self, attr, val)
+        else:
+            setattr(self.__subject__, attr, val)
+
+    def __delattr__(self, attr, oda=object.__delattr__):
+        if attr == '__subject__':
+            oda(self, attr)
+        else:
+            delattr(self.__subject__, attr)
+
+    if hasattr(int, '__nonzero__'):
+        def __nonzero__(self):
+            return bool(self.__subject__)
+
+    def __getitem__(self, arg):
+        return self.__subject__[arg]
+
+    def __setitem__(self, arg, val):
+        self.__subject__[arg] = val
+
+    def __delitem__(self, arg):
+        del self.__subject__[arg]
+
+    def __getslice__(self, i, j):
+        return self.__subject__[i:j]
+
+    def __setslice__(self, i, j, val):
+        self.__subject__[i:j] = val
+
+    def __delslice__(self, i, j):
+        del self.__subject__[i:j]
+
+    def __contains__(self, ob):
+        return ob in self.__subject__
+
+    for name in 'repr str hash len abs complex int long float iter oct hex bool operator.index math.trunc'.split():
+        if name in ('len', 'complex') or hasattr(int, f'__{name.split(".")[-1]}__'):
+            if '.' in name:
+                name = name.split('.')
+                exec(f"global {name[1]}; from {name[0]} import {name[1]}")
+                name = name[1]
+            exec(f"def __{name}__(self): return {name}(self.__subject__)")
+
+    for name in 'cmp', 'coerce', 'divmod':
+        if hasattr(int, f'__{name}__'):
+            exec(f"def __{name}__(self,ob): return {name}(self.__subject__,ob)")
+
+    for name, op in [
+        ('lt', '<'), ('gt', '>'), ('le', '<='), ('ge', '>='),
+        ('eq', '=='), ('ne', '!=')
+    ]:
+        exec(f"def __{name}__(self,ob): return self.__subject__ {op} ob")
+
+    for name, op in [('neg', '-'), ('pos', '+'), ('invert', '~')]:
+        exec(f"def __{name}__(self): return {op} self.__subject__")
+
+    for name, op in [
+        ('or', '|'), ('and', '&'), ('xor', '^'), ('lshift', '<<'), ('rshift', '>>'),
+        ('add', '+'), ('sub', '-'), ('mul', '*'), ('div', '/'), ('mod', '%'),
+        ('truediv', '/'), ('floordiv', '//')
+    ]:
+        if name == 'div' and not hasattr(int, '__div__'):
+            continue
+        exec((
+            f"def __{name}__(self, ob):\n"
+            f"    return self.__subject__ {op} ob\n"
+            "\n"
+            f"def __r{name}__(self, ob):\n"
+            f"    return ob {op} self.__subject__\n"
+            "\n"
+            f"def __i{name}__(self, ob):\n"
+            f"    self.__subject__ {op}=ob\n"
+            "    return self\n"
+        ))
+
+    del name, op
+
+    # Oddball signatures
+
+    def __rdivmod__(self, ob):
+        return divmod(ob, self.__subject__)
+
+    def __pow__(self, *args):  # pylint: disable=unexpected-special-method-signature
+        # Deliberately variadic: pow(subject), pow(subject, exp), pow(subject, exp, mod).
+        return pow(self.__subject__, *args)
+
+    def __ipow__(self, ob):
+        self.__subject__ **= ob # pylint: disable=assigning-non-slot
+        return self
+
+    def __rpow__(self, ob):
+        return pow(ob, self.__subject__)
+
+
+class ObjectProxy(AbstractProxy):
+    """
+    Proxy for a specific object.
+    """
+
+    __slots__ = ('__subject__',)
+
+    def __init__(self, subject):
+        self.__subject__ = subject
+
+
+class CallbackProxy(AbstractProxy):
+    """
+    Proxy for a dynamically-chosen object.
+    """
+
+    __slots__ = ('__callback__',)
+
+    def __init__(self, func):
+        set_callback(self, func)
+
+get_callback = CallbackProxy.__callback__.__get__
+set_callback = CallbackProxy.__callback__.__set__
+CallbackProxy.__subject__ = property(lambda self, gc=get_callback: gc(self)())
+
+
+class LazyProxy(CallbackProxy):
+    """
+    Proxy for a lazily-obtained object, that is cached on first use.
+    """
+    __slots__ = ('__cache__',)
+
+get_cache = LazyProxy.__cache__.__get__
+set_cache = LazyProxy.__cache__.__set__
+
+def __subject__(self, get_cache=get_cache, set_cache=set_cache): # pylint: disable=redefined-outer-name
+    try:
+        return get_cache(self)
+    except AttributeError:
+        set_cache(self, get_callback(self)())
+        return get_cache(self)
+
+LazyProxy.__subject__ = property(__subject__, set_cache)
+del __subject__
+
+
+class AbstractWrapper(AbstractProxy):
+    """
+    Mixin to allow extra behaviors and attributes on proxy instance.
+    """
+
+    __slots__ = ()
+
+    def __getattribute__(self, attr, oga=object.__getattribute__):
+        if attr.startswith('__'):
+            subject = oga(self, '__subject__')
+            if attr == '__subject__':
+                return subject
+            return getattr(subject, attr)
+        return oga(self, attr)
+
+    def __getattr__(self, attr, oga=object.__getattribute__):
+        return getattr(oga(self, '__subject__'), attr)
+
+    def __setattr__(self, attr, val, osa=object.__setattr__):
+        if attr == '__subject__' or hasattr(type(self), attr) and not attr.startswith('__'):
+            osa(self, attr, val)
+        else:
+            setattr(self.__subject__, attr, val)
+
+    def __delattr__(self, attr, oda=object.__delattr__):
+        if attr == '__subject__' or hasattr(type(self), attr) and not attr.startswith('__'):
+            oda(self, attr)
+        else:
+            delattr(self.__subject__, attr)
+
+
+class ObjectWrapper(ObjectProxy, AbstractWrapper):
+    __slots__ = ()
+
+
+class CallbackWrapper(CallbackProxy, AbstractWrapper):
+    __slots__ = ()
+
+
+class LazyWrapper(LazyProxy, AbstractWrapper):
+    __slots__ = ()

proxytypes3-1.0.2.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: proxytypes3
+Version: 1.0.2
+Summary: General purpose proxy and wrapper types.
+Home-page: https://github.com/chrisspen/ProxyTypes3
+Author: Chris Spencer
+Author-email: chrisspen@gmail.com
+License: MIT
+Classifier: Development Status :: 6 - Mature
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: summary
+
+Simple Proxy Types
+==================
+
+[![](https://img.shields.io/pypi/v/proxytypes3.svg)](https://pypi.python.org/pypi/proxytypes3) [![CI](https://github.com/chrisspen/proxytypes3/actions/workflows/ci.yml/badge.svg)](https://github.com/chrisspen/proxytypes3/actions/workflows/ci.yml)
+
+The `proxytypes3` package provides some useful base classes for creating
+proxies and wrappers for ordinary Python objects.  Proxy objects automatically
+delegate all attribute access and operations to the proxied object.  Wrappers
+are similar, but can be subclassed to allow additional attributes and
+operations to be added to the wrapped object.
+
+Note that these proxy types are not intended to be tamper-proof; the unproxied
+form of an object can be readily accessed using a proxy's `__subject__`
+attribute, and some proxy types even allow this attribute to be set.  (This can
+be handy for algorithms that lazily create circular structures and thus need to
+be able to hand out "forward reference" proxies.)
+
+This package is a fork of the [peak.util.proxies](https://pypi.org/project/ProxyTypes/) module,
+extended to include support for Python 3.* as well as better testing and continuous integration.
+
+Proxy Basics
+------------
+
+Here's a quick demo of the `ObjectProxy` type::
+
+    >>> from proxytypes3 import ObjectProxy
+    >>> p = ObjectProxy(42)
+
+    >>> p
+    42
+
+    >>> isinstance(p, int)
+    True
+
+    >>> p.__class__
+    <... 'int'>
+
+    >>> p*2
+    84
+
+    >>> 'X' * p
+    'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+
+    >>> hex(p)
+    '0x2a'
+
+    >>> chr(p)
+    '*'
+
+    >>> p ^ 1
+    43
+
+    >>> p ** 2
+    1764
+
+
+As you can see, a proxy is virtually indistinguishable from the object it
+proxies, except via its `__subject__` attribute, and its `type()`::
+
+    >>> p.__subject__
+    42
+
+    >>> type(p)
+    <class 'proxytypes3.proxies.ObjectProxy'>
+
+You can change the `__subject__` of an `ObjectProxy`, and it will then
+refer to something else::
+
+    >>> p.__subject__ = 99
+    >>> p
+    99
+    >>> p-33
+    66
+
+    >>> p.__subject__ = "foo"
+    >>> p
+    'foo'
+
+All operations are delegated to the subject, including setattr and delattr::
+
+    >>> class Dummy: pass
+    >>> d = Dummy()
+    >>> p = ObjectProxy(d)
+
+    >>> p.foo = "bar"
+    >>> d.foo
+    'bar'
+
+    >>> del p.foo
+    >>> hasattr(d,'foo')
+    False
+
+
+Callback Proxies
+----------------
+
+Sometimes, you may want a proxy's subject to be determined dynamically whenever
+the proxy is used.  For this purpose, you can use the `CallbackProxy` type,
+which accepts a callback function and creates a proxy that will invoke the
+callback in order to get the target.  Here's a quick example of a counter
+that gets incremented each time it's used, from zero to three::
+
+    >>> from proxytypes3 import CallbackProxy
+
+    >>> ct = -1
+    >>> def callback():
+    ...     global ct
+    ...     if ct == 3: raise StopIteration
+    ...     ct += 1
+    ...     return ct
+
+    >>> counter = CallbackProxy(callback)
+
+    >>> counter
+    0
+    >>> counter
+    1
+    >>> str(counter)
+    '2'
+    >>> hex(counter)
+    '0x3'
+
+    >>> counter
+    Traceback (most recent call last):
+      ...
+    StopIteration
+
+As you can see, the callback is automatically invoked on any attempt to use the
+proxy.  This is a somewhat silly example; a better one would be something like
+a `thread_id` proxy that is always equal to the ID # of the thread it's
+running in.
+
+A callback proxy's callback can be obtained or changed via the `get_callback`
+and `set_callback` functions::
+
+    >>> from proxytypes3 import get_callback, set_callback
+    >>> set_callback(counter, lambda: 42)
+
+    >>> counter
+    42
+
+    >>> get_callback(counter)
+    <function <lambda> at ...>
+
+
+Lazy Proxies
+------------
+
+A `LazyProxy` is similar to a `CallbackProxy`, but its callback is called
+at most once, and then cached::
+
+    >>> from proxytypes3 import LazyProxy
+
+    >>> def callback():
+    ...     print("called!")
+    ...     return 42
+
+    >>> lazy = LazyProxy(callback)
+    >>> lazy
+    called!
+    42
+    >>> lazy
+    42
+
+You can use the `get_callback` and `set_callback` functions on lazy
+proxies, but it has no effect if the callback was already called::
+
+    >>> set_callback(lazy, lambda: 99)
+    >>> lazy
+    42
+
+But you can use the `get_cache` and `set_cache` functions to tamper with
+the cached value::
+
+    >>> from proxytypes3 import get_cache, set_cache
+    >>> get_cache(lazy)
+    42
+    >>> set_cache(lazy, 99)
+    >>> lazy
+    99
+
+
+Wrappers
+--------
+
+The `ObjectWrapper`, `CallbackWrapper` and `LazyWrapper` classes are
+similar to their proxy counterparts, except that they are intended to be
+subclassed in order to add custom extra attributes or methods.  Any attribute
+that exists in a subclass of these classes will be read or written from the
+wrapper instance, instead of the wrapped object.  For example::
+
+    >>> from proxytypes3 import ObjectWrapper
+    >>> class NameWrapper(ObjectWrapper):
+    ...     name = None
+    ...     def __init__(self, ob, name):
+    ...         ObjectWrapper.__init__(self, ob)
+    ...         self.name = name
+    ...     def __str__(self):
+    ...         return self.name
+
+    >>> w = NameWrapper(42, "The Ultimate Answer")
+    >>> w
+    42
+
+    >>> print(w)
+    The Ultimate Answer
+
+    >>> w * 2
+    84
+
+    >>> w.name
+    'The Ultimate Answer'
+
+Notice that any attributes you add must be defined *in the class*.  You can't
+add arbitary attributes at runtime, because they'll be set on the wrapped
+object instead of the wrapper::
+
+    >>> w.foo = 'bar'
+    Traceback (most recent call last):
+      ...
+    AttributeError: 'int' object has no attribute 'foo'
+
+Note that this means that all instance attributes must be implemented as either
+slots, properties, or have a default value defined in the class body (like the
+`name = None` shown in the example above).
+
+The `CallbackWrapper` and `LazyWrapper` base classes are basically the same
+as `ObjectWrapper`, except that they use a callback or cached lazy callback
+instead of expecting an object as their subject.
+
+
+Creating Custom Subclasses and Mixins
+-------------------------------------
+
+In addition to all the concrete classes described above, there are also two
+abstract base classes: `AbstractProxy` and `AbstractWrapper`.  If you want
+to create a mixin type that can be used with any of the concrete types, you
+should subclass the abstract version and set `__slots__` to an empty list::
+
+    >>> from proxytypes3 import AbstractWrapper
+
+    >>> class NamedMixin(AbstractWrapper):
+    ...     __slots__ = []
+    ...     name = None
+    ...     def __init__(self, ob, name):
+    ...         super(NamedMixin, self).__init__(ob)
+    ...         self.name = name
+    ...     def __str__(self):
+    ...         return self.name
+
+Then, when you mix it in with the respective base class, you can add back in
+any necessary slots, or leave off `__slots__` to give the subclass instances
+a dictionary of their own::
+
+    >>> from proxytypes3 import CallbackWrapper, LazyWrapper
+
+    >>> class NamedObject(NamedMixin, ObjectWrapper): pass
+    >>> class NamedCallback(NamedMixin, CallbackWrapper): pass
+    >>> class NamedLazy(NamedMixin, LazyWrapper): pass
+
+    >>> print(NamedObject(42, "The Answer"))
+    The Answer
+
+    >>> n = NamedCallback(callback, "Test")
+    >>> n
+    called!
+    42
+    >>> n
+    called!
+    42
+
+    >>> n = NamedLazy(callback, "Once")
+    >>> n
+    called!
+    42
+    >>> n
+    42
+
+Both the `AbstractProxy` and `AbstractWrapper` base classes work by
+assuming that `self.__subject__` will be the wrapped or proxied object.  If
+you don't want to use any of the standard three ways of defining
+`__subject__` (i.e., as an object, callback, or lazy callback), you will need
+to subclass `AbstractProxy` or `AbstractWrapper` and provide your own
+way of defining `__subject__`.
+
+Tests
+-----
+
+To run unittests across multiple Python versions, first install the necessary Python versions. On Ubuntu, run:
+
+    sudo add-apt-repository ppa:deadsnakes/ppa
+    sudo apt-get update
+    sudo apt-get install python-dev python3.4-minimal python3.4-dev python3.5-minimal python3.5-dev python3.6 python3.6-dev
+
+Then to run all [tests](http://tox.readthedocs.org/en/latest/):
+
+    tox
+
+To run tests for a specific environment (e.g. Python 2.7):
+    
+    tox -e py27
+
+To run a specific test:
+    
+    export TESTNAME=.additional_tests; tox -e py34
+    
+    export TESTNAME=.TestObjectProxy.testNumbers; tox -e py36

proxytypes3-1.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+proxytypes3/__init__.py,sha256=iStQKZVmXdLAzxIev91bdFyg1tEifX_54r7FRnP9dXE,86
+proxytypes3/proxies.py,sha256=iTdkI6eZOmWIw9OlEzLroTWnrKlPDzlhJABwuUIcbsQ,5953
+proxytypes3-1.0.2.dist-info/licenses/LICENSE,sha256=pLlF16xT90vKyzvgdlRdmk9ORfgGw1GGopRpRvFXDEo,1070
+proxytypes3-1.0.2.dist-info/METADATA,sha256=QjnCCHjppAQBVLSohhvdsjY45J7fp5fkWJUHQsB00Ak,9346
+proxytypes3-1.0.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+proxytypes3-1.0.2.dist-info/top_level.txt,sha256=J4eEVvN3R1hlMSO_OIHu7YPQjHPyB1QOa5t5xr24iqk,12
+proxytypes3-1.0.2.dist-info/RECORD,,

proxytypes3-1.0.2.dist-info/WHEEL

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

proxytypes3-1.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Chris Spencer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proxytypes3-1.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+proxytypes3