plib3.stdlib 2.3.1__tar.gz → 2.4__tar.gz

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/CHANGES.rst

@@ -1,6 +1,23 @@
 plib3.stdlib Change Log
 =======================
 
+Version 2.4
+-----------
+
+- Remove ``util`` sub-package with ``ModuleProxy`` class, no
+  longer needed in Python 3.8 or later since PEP 562 functionality
+  is available and fulfills the same purpose.
+
+- Add requirement for Python 3.8 or later in ``setup.cfg``.
+
+Version 2.3.2
+-------------
+
+- Use built-in ``prod`` function if available (in versions 3.8
+  and above) instead of adding the implementation from the
+  ``_extras`` module to builtins when ``plib.stdlib.builtins``
+  is imported.
+
 Version 2.3.1
 -------------
 

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.1
 Name: plib3.stdlib
-Version: 2.3.1
+Version: 2.4
 Summary: Useful packages and modules to extend the Python 3 standard library.
 Home-page: http://pypi.org/project/plib3.stdlib
 Author: Peter A. Donis
 Author-email: peterdonis@alum.mit.edu
 License: GPLv2
-Platform: UNKNOWN
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Environment :: MacOS X
@@ -19,6 +18,7 @@ Classifier: Operating System :: POSIX
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 
@@ -141,10 +141,6 @@ The following modules or sub-packages are available in the
   based on those in the Python docs for the ``datetime`` module,
   and a function to return the local system timezone name.
 
-- The ``util`` sub-package provides the ``ModuleProxy`` class, which
-  is used by a number of PLIB3 sub-packages. See the docstrings
-  for the class and the sub-packages using it for more information.
-
 Installation
 ------------
 
@@ -201,5 +197,3 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-
-

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/README.rst

@@ -117,10 +117,6 @@ The following modules or sub-packages are available in the
   based on those in the Python docs for the ``datetime`` module,
   and a function to return the local system timezone name.
 
-- The ``util`` sub-package provides the ``ModuleProxy`` class, which
-  is used by a number of PLIB3 sub-packages. See the docstrings
-  for the class and the sub-packages using it for more information.
-
 Installation
 ------------
 

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/plib/stdlib/__init__.py

@@ -11,4 +11,4 @@ modify the Python standard library, broken out into modules and
 further sub-packages just as the standard library itself is.
 """
 
-__version__ = "2.3.1"
+__version__ = "2.4"

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/plib/stdlib/_extras.py

@@ -122,10 +122,15 @@ def last(iterable, default=None, deque=_deque):
     return q[0] if q else default
 
 
-def prod(iterable, mul=_mul):
-    """Return the product of all items in iterable.
-    """
-    return reduce(mul, iterable, 1)
+try:
+    from math import prod
+
+except ImportError:
+    
+    def prod(iterable, mul=_mul):
+        """Return the product of all items in iterable.
+        """
+        return reduce(mul, iterable, 1)
 
 
 def type_from_name(name):

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/plib/stdlib/builtins.py

@@ -61,7 +61,8 @@ def upgrade_builtins():
         import builtins
         from plib.stdlib import _extras
         for extra_name in EXTRA_NAMES:
-            setattr(builtins, extra_name, getattr(_extras, extra_name))
+            if not hasattr(builtins, extra_name):
+                setattr(builtins, extra_name, getattr(_extras, extra_name))
         _upgraded = True
         return "Upgraded built-ins installed!"
     return "Upgrade already performed, nothing to do."

plib3_stdlib-2.4/plib/stdlib/enumtools.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""
+Module ENUMTOOLS -- PLIB3 Enum Enhancements
+Sub-Package STDLIB of Package PLIB3
+Copyright (C) 2008-2022 by Peter A. Donis
+
+Released under the GNU General Public License, Version 2
+See the LICENSE and README files for more information
+
+This module contains enhanced Enum support; the main purpose
+is to enable user-defined additions to an existing Enum.
+"""
+
+import sys
+from collections.abc import Mapping
+import enum
+
+from plib.stdlib.builtins import first
+
+
+def _make_new_member(new_func, value_type, use_args):
+    # Code cribbed from EnumMeta.__new__, returns a function that
+    # constructs a new instance of the appropriate enum class
+    if use_args:
+        if issubclass(value_type, tuple):
+            def get_args(value):
+                return value
+        else:
+            def get_args(value):
+                return (value,)
+        def new_member(cls, value):
+            args = get_args(value)
+            member = new_func(cls, *args)
+            if not hasattr(member, '_value_'):
+                if value_type is object:
+                    member._value_ = value
+                else:
+                    member._value_ = value_type(*args)
+            return member
+    else:
+        def new_member(cls, value):
+            member = new_func(cls)
+            if not hasattr(member, '_value_'):
+                member._value_ = value
+            return member
+    return new_member
+
+
+class ExtendableEnumMeta(enum.EnumMeta):
+    """Metaclass for extendable enum.
+    
+    Overrides class construction and ``__call__`` methods to allow new
+    instances to be created while still disallowing subclassing once
+    the enum has members.
+    """
+    
+    @classmethod
+    def __prepare__(meta, name, bases, **kwds):
+        # Note: this and what's in __new__ below seems like a lot of boilerplate to
+        # handle adding a keyword argument to a class definition (also it's not
+        # clear what exactly in EnumMeta.__prepare__ is checking for an unexpected
+        # keyword argument since **kwds is neither accessed nor passed in a super call)
+        disable_aliases = kwds.pop('disable_aliases', None)
+        classdict = enum.EnumMeta.__prepare__(name, bases, **kwds)
+        classdict._disable_aliases = disable_aliases
+        return classdict
+    
+    def __new__(meta, name, bases, classdict, **kwds):
+        value_types = set(type(classdict[m]) for m in classdict._member_names)
+        if len(value_types) > 1:
+            raise ValueError("All members of an extendable enum must have the same value type.")
+        value_type = value_types.pop() if value_types else None
+        member_type, first_enum = meta._get_mixins_(name, bases)
+        new_func, _, use_args = meta._find_new_(
+            classdict, member_type, first_enum,
+        )
+        new_member = _make_new_member(new_func, value_type, use_args)
+        disable_aliases = classdict._disable_aliases
+        del classdict._disable_aliases
+        # Note: since we already popped it out of kwds in __prepare__ above,
+        # why is it still here?
+        assert kwds.pop('disable_aliases', None) is disable_aliases
+        enum_class = enum.EnumMeta.__new__(meta, name, bases, classdict, **kwds)
+        enum_class._value_type = value_type
+        enum_class._new_member = new_member
+        enum_class._disable_aliases = disable_aliases
+        return enum_class
+    
+    def __call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, disable_aliases=False):
+        enum_class = enum.EnumMeta.__call__(cls, value, names, module=module, qualname=qualname, type=type, start=start)
+        if names is not None:
+            # We created a new enum class
+            enum_class._disable_aliases = disable_aliases
+        return enum_class
+
+
+class ExtendableEnum(enum.Enum, metaclass=ExtendableEnumMeta):
+    """Extendable enum class.
+    
+    Allows user code to add new members to an existing enum by calling the
+    ``add_member`` class method. The ``extend`` class method is also provided
+    for convenience to allow adding multiple new members at once. Once an
+    extendable enum has members it still cannot be subclassed.
+    
+    >>> class Color(ExtendableEnum):
+    ...     RED = 1
+    ...     GREEN = 2
+    ...
+    >>> Color.add_member('BLUE', 3)
+    <Color.BLUE: 3>
+    >>> Color.add_member('GREEN', 4)
+    Traceback (most recent call last):
+    ...
+    ValueError: Member name GREEN already exists in enum Color
+    >>> Color.add_member('YELLOW', 2)
+    <Color.YELLOW: 2>
+    >>> class UniqueColor(ExtendableEnum, disable_aliases=True):
+    ...     RED = 1
+    ...     GREEN = 2
+    ...
+    >>> UniqueColor.add_member('BLUE', 3)
+    <UniqueColor.BLUE: 3>
+    >>> UniqueColor.add_member('GREEN', 4)
+    Traceback (most recent call last):
+    ...
+    ValueError: Member name GREEN already exists in enum UniqueColor
+    >>> UniqueColor.add_member('YELLOW', 2)
+    Traceback (most recent call last):
+    ...
+    ValueError: Aliases are disabled for enum UniqueColor
+    """
+    
+    @classmethod
+    def add_member(cls, name, value):
+        """Add new member to an extendable enum.
+        
+        Raises ``ValueError`` if a new member's value is not of the same type as
+        existing members' values, or if the member name already exists. If the
+        ``disable_aliases`` keyword argument was used in constructing the extendable
+        enum class, existing values cannot be aliased, and ``ValueError`` is raised
+        if this is attempted.
+        """
+        if not isinstance(value, cls._value_type):
+            raise ValueError("Invalid value type for extendable enum {}: {}".format(cls.__name__, repr(value)))
+        if name in cls.__members__:
+            raise ValueError("Member name {} already exists in enum {}".format(name, cls.__name__))
+        if cls._disable_aliases and (value in cls._value2member_map_):
+            raise ValueError("Aliases are disabled for enum {}".format(cls.__name__))
+        existing_member = first(m for m in cls.__members__.values() if m._value_ == value)
+        obj = cls._new_member(cls, value)
+        obj._name_ = name
+        obj._value_ = value
+        obj.__objclass__ = cls
+        cls._member_map_[name] = existing_member if existing_member is not None else obj
+        try:
+            # This will fail if value is not hashable, but enum supports that case so suppress exception
+            cls._value2member_map_[value] = existing_member if existing_member is not None else obj
+        except TypeError:
+            pass
+        if not existing_member:
+            # This list does not contain aliases
+            cls._member_names_.append(name)
+        return obj
+    
+    @classmethod
+    def extend(cls, members):
+        """Add multiple members at once to an extendable enum.
+        
+        The ``members`` parameter must be an iterable of ``(name, value)`` tuples
+        or a mapping of names to values.
+        """
+        for name, value in (members.items() if isinstance(members, Mapping) else members):
+            cls.add_member(name, value)
+
+
+def _get_transform(name, prefix_classname=False, classname_transform=None):
+    if prefix_classname:
+        prefix = name
+        if classname_transform:
+            prefix = classname_transform(prefix)
+        f = (lambda s: '{}_{}'.format(prefix, s))
+    else:
+        f = (lambda s: s)
+    return f
+
+
+def _add_global(mod, s, m, f):
+    setattr(mod, f(s), m)
+
+
+def add_enum_member_global(modname, s, m, prefix_classname=False, classname_transform=None):
+    """Add global to module modname for enum member ``m`` with name ``s``.
+    """
+    f = _get_transform(type(m).__name__, prefix_classname, classname_transform)
+    _add_global(sys.modules[modname], s, m, f)
+
+
+def _add_globals(mod, name, obj, prefix_classname=False, classname_transform=None):
+    f = _get_transform(name, prefix_classname, classname_transform)
+    for s, m in obj.__members__.items():
+        _add_global(mod, s, m, f)
+
+
+def add_enum_globals(modname, name, obj, prefix_classname=False, classname_transform=None):
+    """Add globals to module ``modname`` for all members of enum with class name ``name``.
+    """
+    return _add_globals(sys.modules[modname], name, obj, prefix_classname, classname_transform)
+
+
+def add_all_enum_globals(modname, prefix_classname=False, classname_transform=None):
+    """Add globals to module ``modname`` for all enums in module.
+    """
+    mod = sys.modules[modname]
+    for name in dir(mod):
+        obj = getattr(mod, name)
+        if isinstance(obj, type) and issubclass(obj, enum.Enum):
+            _add_globals(mod, name, obj, prefix_classname, classname_transform)

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/plib/test/stdlib/__main__.py

@@ -17,6 +17,7 @@ modules_with_doctests = [
     'plib.stdlib.coll',
     'plib.stdlib.coll._tuples',
     'plib.stdlib.decotools',
+    'plib.stdlib.enumtools',
     'plib.stdlib.iters',
     'plib.stdlib.localize'
 ]

plib3_stdlib-2.4/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuputils3 >= 2.2", "setuptools >= 40.8.0", "wheel"]
+build-backend = "setuputils_build"

{plib3.stdlib-2.3.1 → plib3_stdlib-2.4}/setup.cfg

@@ -23,6 +23,7 @@ classifiers =
 	Topic :: Software Development :: Libraries :: Python Modules
 
 [options]
+python_requires = >=3.8
 packages = 
 	plib
 	plib.stdlib
@@ -30,7 +31,6 @@ packages =
 	plib.stdlib.decotools
 	plib.stdlib.ini
 	plib.stdlib.net
-	plib.stdlib.util
 	plib.test
 	plib.test.stdlib
 	plib.test.support

plib3.stdlib-2.3.1/plib/stdlib/util/ModuleProxy.py

@@ -1,183 +0,0 @@
-#!/usr/bin/env python3
-"""
-Module ModuleProxy
-Sub-Package STDLIB.UTIL of Package PLIB3
-Copyright (C) 2008-2022 by Peter A. Donis
-
-Released under the GNU General Public License, Version 2
-See the LICENSE and README files for more information
-
-This module contains the ModuleProxy class. For examples
-of intended use cases for this class, check out the
-``main.py`` module in the PLIB3.GUI sub-package, or any
-of a number of ``__init__.py`` modules in the PLIB3.IO
-sub-packages. The docstrings and comments there give more
-information.
-
-One note about usage: whenever importing from a package
-that uses this functionality, absolute imports should be
-used. Using relative imports risks running afoul of the
-name ambiguity between the object you want to import (a
-class, usually) and the module it's defined in. Absolute
-imports are "purer" anyway, so this is not viewed as a
-bothersome restriction.
-"""
-
-import sys
-import os
-import glob
-import types
-
-from plib.stdlib.imp import import_from_module
-
-__all__ = ('ModuleProxy',)
-
-
-# Helper function for lazy loading of actual modules
-
-def module_helper(pkgname, modname):
-    
-    def f():
-        try:
-            return import_from_module(
-                '{}.{}'.format(pkgname, modname),
-                modname
-            )
-        except:
-            try:
-                # Try retrieving modname from pkgname as an attribute
-                # FIXME: why does this sometimes help? Nothing like
-                # this was needed in Python 2, and the advertised
-                # semantics of the above import_from_module call should
-                # mean that if the below works, the above should have!
-                return getattr(sys.modules.get(pkgname), modname)
-            except:
-                raise TypeError
-    
-    f.__name__ = "{}_helper".format(modname)
-    return f
-
-
-# Note that we subclass types.ModuleType in order to fool
-# various introspection utilities (e.g., pydoc and the builtin
-# 'help' command in the interpreter) into thinking ModuleProxy
-# instances are actual modules. Among other things, this is
-# necessary for the builtin 'help' command to properly display
-# the info from the proxied module's docstring (setting the
-# proxy's __doc__ to the actual module's __doc__ is *not*
-# enough to do this by itself); note also that we don't
-# override the constructor because various Python internals
-# expect module objects to have a particular signature for
-# the constructor; instead, we add the init_proxy method which
-# must be called immediately on constructing the object to do
-# the proxying magic
-
-class ModuleProxy(types.ModuleType):
-    
-    def init_proxy(self, name, path, globals_dict, locals_dict,
-                   names=None, excludes=None, autodiscover=True):
-        
-        self._excludes = excludes
-        
-        names = dict(names or {})
-        excludes = set(excludes or [])
-        
-        if autodiscover:
-            for pathname in path:
-                for filename in glob.glob(os.path.join(pathname, "*.py")):
-                    modname = os.path.splitext(os.path.basename(filename))[0]
-                    if not self._exclude(modname, excludes):
-                        names[modname] = module_helper(name, modname)
-        
-        self._names = names
-        self._realized_names = []
-        
-        # Monkeypatch sys.modules with the proxy object (make
-        # sure we store a reference to the real module first!)
-        self._mod = sys.modules[name]
-        sys.modules[name] = self
-        
-        # Pass-through module's docstring (this attribute name
-        # appears in both so __getattr__ below won't handle it);
-        # as noted above, this in itself isn't enough to make
-        # the 'help' builtin work right, but it is a necessary
-        # part of doing so
-        self.__doc__ = self._mod.__doc__
-    
-    def __repr__(self):
-        return "<proxy of module '{}' from '{}'>".format(
-            self._mod.__name__, self._mod.__file__)
-    
-    def _exclude(self, name, excludes):
-        # This allows customization of the exclusion algorithm; by
-        # default we exclude names in the excludes set and private
-        # names (ones that start with '_')
-        return (name in excludes) or name.startswith('_')
-    
-    def _realize_name(self, name, value):
-        setattr(self, name, value)  # so it gets retrieved without __getattr__
-        self._realized_names.append(name)  # so __dir__ can see it
-    
-    not_proxied = object()
-    
-    def _get_name(self, name, module=None):
-        names = self.__dict__['_names']
-        result = names.get(name, self.not_proxied)
-        if result is not self.not_proxied:
-            
-            if module is None:
-                # This hack allows features like 'lazy importing' to work;
-                # a callable names dict entry allows arbitrary (and possibly
-                # expensive) processing to take place only when the attribute
-                # is first accessed, instead of when the module is initially
-                # imported. Also, since we store the result in our __dict__,
-                # the expensive function won't get called again, so we are
-                # essentially memoizing the result.
-                try:
-                    newresult = result()
-                except TypeError:
-                    pass
-                else:
-                    result = newresult
-            
-            else:
-                # This can happen if the underlying sub-module was imported
-                # before we got a chance to proxy it
-                try:
-                    newresult = getattr(module, name)
-                except AttributeError:
-                    # It wasn't a proxied name after all (or else it isn't
-                    # being proxied our way)
-                    result = self.not_proxied
-                else:
-                    result = newresult
-        
-        if (result is not self.not_proxied) and (name in names):
-            assert name not in self._realized_names
-            self._realize_name(name, result)
-            del names[name]  # no need to track it any more
-        
-        return result
-    
-    not_in_real_module = object()
-    
-    def __getattr__(self, name):
-        # Remember we need to return the real module's attributes!
-        mod_result = getattr(self._mod, name, self.not_in_real_module)
-        if mod_result is self.not_in_real_module:
-            our_result = self._get_name(name)
-            if our_result is self.not_proxied:
-                raise AttributeError("{} object has no attribute {}".format(
-                                     self, name))
-            else:
-                return our_result
-        else:
-            if isinstance(mod_result, types.ModuleType):
-                # We might have gotten the underlying module for a proxied name
-                our_result = self._get_name(name, mod_result)
-                if (our_result is not self.not_proxied):
-                    return our_result
-            return mod_result
-    
-    def __dir__(self):
-        return sorted(dir(self._mod) + self._realized_names + list(self._names.keys()))

plib3.stdlib-2.3.1/plib/stdlib/util/__init__.py

@@ -1,13 +0,0 @@
-#!/usr/bin/env python3
-"""
-Sub-Package STDLIB.UTIL of Package PLIB3
-Copyright (C) 2008-2022 by Peter A. Donis
-
-Released under the GNU General Public License, Version 2
-See the LICENSE and README files for more information
-
-This sub-package exposes the ModuleProxy class by itself,
-to ensure that importing it brings in no other objects.
-"""
-
-from .ModuleProxy import *

plib3.stdlib-2.3.1/pyproject.toml

@@ -1,3 +0,0 @@
-[build-system]
-requires = ["setuputils3 >= 2.1", "setuptools >= 40.8.0", "wheel"]
-build-backend = "setuputils_build"