swizzle 2.0.0__py3-none-any.whl → 2.1.1__py3-none-any.whl

swizzle/__init__.py

@@ -1,7 +1,9 @@
 # Copyright (c) 2024 Jan T. Müller <mail@jantmueller.com>
 
+import warnings
 from functools import wraps
 import types
+import builtins
 import sys as _sys
 
 from keyword import iskeyword as _iskeyword
@@ -12,12 +14,60 @@ except ImportError:
     _tuplegetter = lambda index, doc: property(_itemgetter(index), doc=doc)
 
 
-__version__ = "2.0.0"
+__version__ = "2.1.1"
 
 MISSING = object()
 
-def swizzlednamedtuple(typename, field_names, *, rename=False, defaults=None, module=None, arrange_names = None, seperator = None):
-    # Validate the field names. Skip duplicate and underscore checks.
+def swizzledtuple(typename, field_names, *, rename=False, defaults=None, module=None, arrange_names = None, seperator = None):
+    """
+    Create a custom named tuple class with swizzled attributes, allowing for rearranged field names
+    and customized attribute access.
+
+    This function generates a new subclass of `tuple` with named fields, similar to Python's
+    `collections.namedtuple`. However, it extends the functionality by allowing field names to be
+    rearranged, and attributes to be accessed with a customizable separator. The function also
+    provides additional safeguards for field naming and attribute access.
+
+    Args:
+        typename (str): The name of the new named tuple type.
+        field_names (sequence of str or str): A sequence of field names for the tuple. If given as
+            a single string, it will be split into separate field names.
+        rename (bool, optional): If True, invalid field names are automatically replaced with
+            positional names. Defaults to False.
+        defaults (sequence, optional): Default values for the fields. Defaults to None.
+        module (str, optional): The module name in which the named tuple is defined. Defaults to
+            the caller's module.
+        arrange_names (sequence of str, optional): A sequence of field names indicating the order
+            in which fields should be arranged in the resulting named tuple. This allows for fields
+            to be rearranged and, unlike standard `namedtuple`, can include duplicates. Defaults
+            to the order given in `field_names`.
+        separator (str, optional): A separator string that customizes the structure of attribute
+            access. If provided, this separator allows attributes to be accessed by combining field
+            names with the separator in between them. Defaults to no separator.
+
+    Returns:
+        type: A new subclass of `tuple` with named fields and customized attribute access.
+
+    Notes:
+        - The function is based on `collections.namedtuple` but with additional features such as
+          field rearrangement and swizzled attribute access.
+        - The `arrange_names` argument allows rearranging the field names, and it can include
+          duplicates, which is not possible in a standard `namedtuple`.
+        - The generated named tuple class includes methods like `_make`, `_replace`, `__repr__`,
+          `_asdict`, and `__getnewargs__`, partially customized to handle the rearranged field order.
+        - The `separator` argument enables a custom structure for attribute access, allowing for
+          combined attribute names based on the provided separator. If no separator is provided,
+          standard attribute access is used.
+
+    Example:
+        >>> Vector = swizzledtuple('Vector', 'x y z', arrange_names='y z x x')
+        >>> # Test the swizzle
+        >>> v = Vector(1, 2, 3)
+        >>> print(v)  # Output: Vector(y=2, z=3, x=1, x=1)
+        >>> print(v.yzx)  # Output: Vector(y=2, z=3, x=1)
+        >>> print(v.yzx.xxzyzz)  # Output: Vector(x=1, x=1, z=3, y=2, z=3, z=3)
+    """
+
     if isinstance(field_names, str):
         field_names = field_names.replace(',', ' ').split()
     field_names = list(map(str, field_names))
@@ -142,7 +192,7 @@ def swizzlednamedtuple(typename, field_names, *, rename=False, defaults=None, mo
         'Return self as a plain tuple.  Used by copy and pickle.'
         return _tuple(self)
 
-    @swizzle_attributes_retriever(separator=seperator, type = swizzlednamedtuple)
+    @swizzle_attributes_retriever(separator=seperator, type = swizzledtuple)
     def __getattribute__(self, attr_name):
         return super(_tuple, self).__getattribute__(attr_name)
 
@@ -195,6 +245,11 @@ def swizzlednamedtuple(typename, field_names, *, rename=False, defaults=None, mo
 
     return result
 
+# deprecated name
+def swizzlednamedtuple(typename, field_names, *, rename=False, defaults=None, module=None, arrange_names = None, seperator = None):
+    warnings.warn("swizzlednamedtuple is deprecated, use swizzledtuple instead", DeprecationWarning, stacklevel=2)
+    return swizzledtuple(typename, field_names, rename=rename, defaults=defaults, module=module, arrange_names=arrange_names, seperator=seperator)
+
 
 # Helper function to split a string based on a separator
 def split_string(string, separator):
@@ -263,10 +318,10 @@ def swizzle_attributes_retriever(attribute_funcs=None, separator=None, type = tu
                     if not match_found:
                         raise AttributeError(f"No matching attribute found for substring: {attr_name[i:]}")
 
-            if type == swizzlednamedtuple:
+            if type == swizzledtuple or type == swizzlednamedtuple:
                 field_names = set(arranged_names)
                 field_values = [retrieve_attribute(obj, name) for name in field_names]
-                name = "swizzlednamedtuple"
+                name = "swizzledtuple"
                 if hasattr(obj, "__name__"):
                     name = obj.__name__
                 elif hasattr(obj, "__class__"):
@@ -287,19 +342,28 @@ def swizzle_attributes_retriever(attribute_funcs=None, separator=None, type = tu
         return _swizzle_attributes_retriever
 
 # Decorator function to enable swizzling for a class
-def swizzle(cls=None, use_meta=False, separator=None, _type = tuple):
+def swizzle(cls=None, meta=False, separator=None, type = tuple, **kwargs):
+
+    if 'use_meta' in kwargs:
+        warnings.warn("The 'use_meta' argument is deprecated and will be removed in a future version. Use 'meta' instead.", DeprecationWarning, stacklevel=2)
+        meta = kwargs.pop('use_meta')
+    if '_type' in kwargs:
+        warnings.warn("The '_type' argument is deprecated and will be removed in a future version. Use 'type' instead.", DeprecationWarning, stacklevel=2)
+        type = kwargs.pop('_type')
+
+    _type = builtins.type
+
     def class_decorator(cls):
         # Collect attribute retrieval functions from the class
         attribute_funcs = collect_attribute_functions(cls)
 
         # Apply the swizzling to the class's attribute retrieval
-        setattr(cls, attribute_funcs[-1].__name__, swizzle_attributes_retriever(attribute_funcs, separator, _type))
+        setattr(cls, attribute_funcs[-1].__name__, swizzle_attributes_retriever(attribute_funcs, separator, type))
 
         # Handle meta-class swizzling if requested
-        if use_meta:
-            print(cls)
-            meta_cls = type(cls)
-            if meta_cls == type:
+        if meta:
+            meta_cls = _type(cls)
+            if meta_cls == _type:
                 class SwizzledMetaType(meta_cls):
                     pass
                 meta_cls = SwizzledMetaType
@@ -308,7 +372,7 @@ def swizzle(cls=None, use_meta=False, separator=None, _type = tuple):
                 cls = meta_cls(cls.__name__, cls.__bases__, dict(cls.__dict__))
 
             meta_funcs = collect_attribute_functions(meta_cls)
-            setattr(meta_cls, meta_funcs[-1].__name__, swizzle_attributes_retriever(meta_funcs, separator, _type))
+            setattr(meta_cls, meta_funcs[-1].__name__, swizzle_attributes_retriever(meta_funcs, separator, type))
 
         return cls
 
@@ -323,7 +387,7 @@ class Swizzle(types.ModuleType):
         types.ModuleType.__init__(self, __name__)
         self.__dict__.update(_sys.modules[__name__].__dict__)
 
-    def __call__(self, cls=None, meta=False, sep = None, type = swizzlednamedtuple):
+    def __call__(self, cls=None, meta=False, sep = None, type = swizzledtuple):
         return swizzle(cls, meta, sep, type)
 
 _sys.modules[__name__] = Swizzle()

{swizzle-2.0.0.dist-info → swizzle-2.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: swizzle
-Version: 2.0.0
+Version: 2.1.1
 Summary: Swizzle enables the retrieval of multiple attributes, similar to swizzling in computer graphics.
 Home-page: https://github.com/janthmueller/swizzle
 Author: Jan T. Müller
@@ -19,17 +19,18 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 
 # Swizzle
-[![PyPI version](https://badge.fury.io/py/swizzle.svg)](https://badge.fury.io/py/swizzle)
-[![Downloads](https://pepy.tech/badge/swizzle)](https://pepy.tech/project/swizzle)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/janthmueller/swizzle/blob/main/LICENSE)
+[![PyPI Latest Release](https://img.shields.io/pypi/v/swizzle.svg)](https://pypi.org/project/swizzle/) 
+[![Pepy Total Downlods](https://img.shields.io/pepy/dt/swizzle)](https://pepy.tech/project/swizzle)
+[![GitHub License](https://img.shields.io/github/license/janthmueller/swizzle)](https://github.com/janthmueller/swizzle/blob/main/LICENSE)
 [![GitHub Stars](https://img.shields.io/github/stars/janthmueller/swizzle.svg)](https://github.com/janthmueller/swizzle/stargazers)
 
 **Swizzle** for Python enhances attribute lookup methods to facilitate dynamic and flexible retrieval of multiple attributes based on specified arrangements of their names.
 > **Update v2:**
-> Introducing `swizzlednamedtuple` , a new function that allows you to create **swizzled named tuples**. This feature is inspired by the `namedtuple` function from the [collections module](https://docs.python.org/3/library/collections.html#collections.namedtuple) and provides a concise way to define swizzled tuples.
+> Introducing `swizzledtuple` , a new function that allows you to create swizzled named tuples. This feature is inspired by the `namedtuple` function from the [collections module](https://docs.python.org/3/library/collections.html#collections.namedtuple) and provides a concise way to define swizzled tuples.
 > ```python
-> from swizzle import swizzlednamedtuple
-> Vector = swizzlednamedtuple('Vector', 'x y z', arrange_names = "y z x x")
+> from swizzle import swizzledtuple
+>
+> Vector = swizzledtuple('Vector', 'x y z', arrange_names = "y z x x")
 >
 > # Test the swizzle
 > v = Vector(1, 2, 3)

swizzle-2.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+swizzle/__init__.py,sha256=_YUDBGbs3unvltIfO8A0DIsWC05vxQaklY43vsFKyK4,16370
+swizzle-2.1.1.dist-info/LICENSE,sha256=WDAegKWtl3rZUiN-SQ2FEQQwEFxlM_jEKQyJRJawJXo,1070
+swizzle-2.1.1.dist-info/METADATA,sha256=xwo2y2C9uuy_-fW5YRDQd3PtMnn7hkD9zXVlAIBqNiU,3826
+swizzle-2.1.1.dist-info/WHEEL,sha256=nCVcAvsfA9TDtwGwhYaRrlPhTLV9m-Ga6mdyDtuwK18,91
+swizzle-2.1.1.dist-info/top_level.txt,sha256=XFSQti81x2zM0zAMCY1YD0lqB1eSg5my9BB03uFgCic,8
+swizzle-2.1.1.dist-info/RECORD,,

{swizzle-2.0.0.dist-info → swizzle-2.1.1.dist-info}/WHEEL

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

swizzle-2.0.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-swizzle/__init__.py,sha256=fg47lzErJW1TS48sxnWsKA0myGIzp7SCxqleo2wHoyI,12504
-swizzle-2.0.0.dist-info/LICENSE,sha256=WDAegKWtl3rZUiN-SQ2FEQQwEFxlM_jEKQyJRJawJXo,1070
-swizzle-2.0.0.dist-info/METADATA,sha256=3zFLwkydXuLnXpdVr59kS6-ozGwX8Qdsk87BhK4kWN0,3803
-swizzle-2.0.0.dist-info/WHEEL,sha256=HiCZjzuy6Dw0hdX5R3LCFPDmFS4BWl8H-8W39XfmgX4,91
-swizzle-2.0.0.dist-info/top_level.txt,sha256=XFSQti81x2zM0zAMCY1YD0lqB1eSg5my9BB03uFgCic,8
-swizzle-2.0.0.dist-info/RECORD,,