proxytypes3 1.0.1__tar.gz → 1.0.2__tar.gz

proxytypes3-1.0.2/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/PKG-INFO

@@ -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.1 → proxytypes3-1.0.2}/README.md

@@ -1,7 +1,7 @@
 Simple Proxy Types
 ==================
 
-[![](https://img.shields.io/pypi/v/proxytypes3.svg)](https://pypi.python.org/pypi/proxytypes3) [![Build Status](https://img.shields.io/travis/chrisspen/proxytypes3.svg?branch=master)](https://travis-ci.org/chrisspen/proxytypes3)
+[![](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

{proxytypes3-1.0.1 → proxytypes3-1.0.2}/proxytypes3/__init__.py

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

{proxytypes3-1.0.1 → proxytypes3-1.0.2}/proxytypes3/proxies.py

@@ -1,4 +1,4 @@
-class AbstractProxy(object):
+class AbstractProxy:
     """
     Delegates all operations (except ``.__subject__``) to another object.
     """
@@ -52,25 +52,25 @@ class AbstractProxy(object):
         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, '__%s__' % name.split('.')[-1]):
+        if name in ('len', 'complex') or hasattr(int, f'__{name.split(".")[-1]}__'):
             if '.' in name:
                 name = name.split('.')
-                exec("global %s; from %s import %s" % (name[1], name[0], name[1]))
+                exec(f"global {name[1]}; from {name[0]} import {name[1]}")
                 name = name[1]
-            exec("def __%s__(self): return %s(self.__subject__)" % (name, name))
+            exec(f"def __{name}__(self): return {name}(self.__subject__)")
 
     for name in 'cmp', 'coerce', 'divmod':
-        if hasattr(int, '__%s__' % name):
-            exec("def __%s__(self,ob): return %s(self.__subject__,ob)" % (name, name))
+        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("def __%s__(self,ob): return self.__subject__ %s ob" % (name, op))
+        exec(f"def __{name}__(self,ob): return self.__subject__ {op} ob")
 
     for name, op in [('neg', '-'), ('pos', '+'), ('invert', '~')]:
-        exec("def __%s__(self): return %s self.__subject__" % (name, op))
+        exec(f"def __{name}__(self): return {op} self.__subject__")
 
     for name, op in [
         ('or', '|'), ('and', '&'), ('xor', '^'), ('lshift', '<<'), ('rshift', '>>'),
@@ -80,16 +80,16 @@ class AbstractProxy(object):
         if name == 'div' and not hasattr(int, '__div__'):
             continue
         exec((
-            "def __%(name)s__(self, ob):\n"
-            "    return self.__subject__ %(op)s ob\n"
+            f"def __{name}__(self, ob):\n"
+            f"    return self.__subject__ {op} ob\n"
             "\n"
-            "def __r%(name)s__(self, ob):\n"
-            "    return ob %(op)s self.__subject__\n"
+            f"def __r{name}__(self, ob):\n"
+            f"    return ob {op} self.__subject__\n"
             "\n"
-            "def __i%(name)s__(self, ob):\n"
-            "    self.__subject__ %(op)s=ob\n"
+            f"def __i{name}__(self, ob):\n"
+            f"    self.__subject__ {op}=ob\n"
             "    return self\n"
-        )  % locals())
+        ))
 
     del name, op
 
@@ -98,7 +98,8 @@ class AbstractProxy(object):
     def __rdivmod__(self, ob):
         return divmod(ob, self.__subject__)
 
-    def __pow__(self, *args):
+    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):