python-clu 0.12.11__tar.gz → 0.12.13__tar.gz

{python_clu-0.12.11 → python_clu-0.12.13}/.bumpversion.toml

@@ -1,6 +1,6 @@
 
 [tool.bumpversion]
-current_version = "0.12.11"
+current_version = "0.12.13"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"

{python_clu-0.12.11 → python_clu-0.12.13}/CHANGELOG.md

@@ -1,10 +1,135 @@
 # Changelog
 
 
-## 0.12.10:pre1+g4e2fdbd [SNAPSHOT]
+## 0.12.12:pre12+gf9e1a9f [SNAPSHOT]
+
+### Add
+
+* Added some useful rando dicts to `clu.constants.data` [Alexander Böhn]
 
 ### Other
 
+* Nixed `clu.dicts.ChainMap.__eq__(…)` for the moment. [Alexander Böhn]
+
+  … because I have reason to believe that, at this time, it may suck.
+
+* Tidying up and removing more dead code. [Alexander Böhn]
+
+* Removed and renamed much in the `clu.keymap`/`clu.dicts` departments. [Alexander Böhn]
+
+* Total overhaul of oh so much stuff in `clu.config` and `clu.dicts` [Alexander Böhn]
+
+  • For the most part, you pass actual namespaces in to a KeyMaps’
+    methods that say “namespaces”.
+    • Like: “flatmap.submap('yo:dogg', 'iheard:youlike')” works
+    • … as does “flatmap.keys('yo:dogg')” or “flatmap.items('yo:dogg')”
+    • … there was some touchy shit with this so watch this space for more
+    • Tests are updated accordingly (both inline and unit tests)
+  • Many changes in “clu.dicts” to afford different classes and speed
+    and things of that nature
+  • Added a new “clu.config.utils” module
+    • This contains ad-hoc name-based functions for “freezing” and
+      “thawing” classes – like you can do:
+
+      >>> from clu.config.utils import freeze_class, thaw_class
+      >>> from clu.config.keymap import Flat, FrozenFlat
+      >>> assert freeze_class(Flat) is FrozenFlat
+      >>> assert thaw_class(FrozenFlat) is Flat
+
+      … which is pretty neat, I think. It’s totally ad-hoc and fragile,
+        tho, so we will see what happens.
+  • Modified “clu.config.abc” to go with all of this
+  • Added some mapping fixture thingees to “clu.constants.data”
+  • Much other miscellany I am sure
+
+  … Yes!
+
+* Rethinking and reworking how `KeyMap.submap(…)` thinks and works. [Alexander Böhn]
+
+* An array of tweaks and optimizations to be found in `clu.dicts` [Alexander Böhn]
+
+  So. We got:
+  • A rewrite of “clu.dicts.merge_as(…)” that doesn’t just hopelessly
+    piggyback on “merge_two(¬)” of the same module, and keeps the dicts
+    in the right order
+  • Some of that “right order” mojo was sprinkled into the constructor
+    for “clu.dicts.ChainMap”
+  • “clu.dicts.ChainRepr” won’t identify builtin types (namely, “dict”)
+    as irritatingly coming from the “builtins” package
+  • Used frozensets in place of sets, wherever speedier
+  • Inline test names in “clu.dicts” make some a lot of sense
+  • Other miscellaneous shit
+
+* Regex flags in `clu.fs.misc` are now handled cheaply and gracefully. [Alexander Böhn]
+
+  … meaning the defaults are computed in the function sigs, which also
+    means they may be modified at the whim of you, the user
+
+* My my, there was much reserved-word-clobbering up in there. [Alexander Böhn]
+
+  … by “there” I mean “clu.dicts”; q.v. previous commit supra.
+
+* No longer clobbering a reserved word (“map”) in `clu.dicts.ChainMap` [Alexander Böhn]
+
+* Just a small addenda to my favorite CLU docstring. [Alexander Böhn]
+
+* A bunch of new namespace tools for use in `clu.config` [Alexander Böhn]
+
+  To wit:
+  • The very deeply abstract base class now has an abstract method
+    definition specifically for the “submap(…)” signature (which this
+    was previously lacking).
+
+  • There’s a new “KeyedAccessor” class in “clu.config.keymap”, allowing
+    for proxied simple access to keymap elements. Like you can be like:
+
+      >>> nested = Nested(nested_data)
+      >>> accessor = KeyedAccessor(nested, "some:namespace:keypath")
+      >>> assert nested['some:namespace:keypath:key'] = accessor['key']
+
+    … at least, that’s the goal with that RN.
+
+  • There is also a “clean_ns(namespaced_string)” function, to be found
+    in “clu.config.ns”, and support regexes and one-liner functions
+    based on those regexes, and an inline test function.
+
+  • Trivial (really) fixes in “clu.exporting” and “clu.predicates” too.
+
+
+## v0.12.12 (2025-06-03)
+
+### Other
+
+* Bumped version: 0.12.11 → 0.12.12. [Alexander Böhn]
+
+* [make] New changelog added. [Alexander Böhn]
+
+* Reaffirming the commands’ non-erroneousness AGAIN!! [Alexander Böhn]
+
+* Reaffirming the commands’ non-erroneousness. [Alexander Böhn]
+
+* Supress raising pointless `ValueError`s when running “clu-ansidocs” [Alexander Böhn]
+
+* Properly assigning `__doc__` string. [Alexander Böhn]
+
+* Small updates to `clu.enums` and `clu.naming.qualified_import(…)` [Alexander Böhn]
+
+  … “clu.enums” uses its DUNDER constant internally
+  … “clu.naming.qualified_import(…)” has an internally-used “recurse”
+     argument that basically disables the whole “qualified” check,
+     which by the way I am starting to see as totally unnecessary
+
+* Docstring MUST OCCUR FIRST!!! in a thing. [Alexander Böhn]
+
+
+## v0.12.11 (2025-05-25)
+
+### Other
+
+* Bumped version: 0.12.10 → 0.12.11. [Alexander Böhn]
+
+* [make] New changelog added. [Alexander Böhn]
+
 * Ahhhh my home-brewed classifier didn’t work, booooo. [Alexander Böhn]
 
 

{python_clu-0.12.11 → python_clu-0.12.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-clu
-Version: 0.12.11
+Version: 0.12.13
 Summary: Python-CLU: Common Lightweight Utilities
 Home-page: https://github.com/fish2000/clu
 Download-URL: https://github.com/fish2000/clu/zipball/master

python_clu-0.12.13/clu/__version__.py

@@ -0,0 +1 @@
+__version__ = '0.12.13'

{python_clu-0.12.11 → python_clu-0.12.13}/clu/config/abc.py

@@ -15,6 +15,7 @@ from clu.config.ns import unpack_ns, pack_ns, get_ns, compare_ns
 from clu.config.keymapview import KeyMapKeysView, KeyMapItemsView, KeyMapValuesView
 from clu.config.keymapview import NamespaceWalkerKeysView, NamespaceWalkerItemsView
 from clu.config.keymapview import NamespaceWalkerValuesView
+from clu.config.utils import freeze_class
 
 from clu.naming import qualified_import, qualified_name, nameof
 from clu.predicates import (typeof,
@@ -61,6 +62,11 @@ class FrozenKeyMapBase(collections.abc.Mapping,
         """ Iterate over all of the namespaces defined in the mapping. """
         ...
     
+    @abstract
+    def submap(self, *namespaces, unprefixed=False):
+        """ Return a flattened dict containing only the namespaced items. """
+        ...
+    
     @abstract
     def __iter__(self):
         ...
@@ -143,13 +149,13 @@ class FrozenKeyMap(FrozenKeyMapBase):
         """ Used by `clu.config.codecs` to deserialize keymaps """
         return cls(instance_dict)
     
-    def get(self, key, *namespaces, default=NoDefault):
+    def get(self, key, *fragments, default=NoDefault):
         """ Retrieve a (possibly namespaced) value for a given key.
             
             An optional default value may be specified, to be returned
             if the key in question is not found in the mapping.
         """
-        nskey = pack_ns(key, *namespaces)
+        nskey = pack_ns(key, *fragments)
         if default is NoDefault:
             return self[nskey]
         if nskey in self:
@@ -158,12 +164,15 @@ class FrozenKeyMap(FrozenKeyMapBase):
     
     def submap(self, *namespaces, unprefixed=False):
         """ Return a flattened dict containing only the namespaced items. """
+        cls = freeze_class(type(self))
         if unprefixed:
-            return { nskey : self[nskey] for nskey in self if NAMESPACE_SEP not in nskey }
+            return cls({ nskey : self[nskey] for nskey in self if NAMESPACE_SEP not in nskey })
         if not namespaces:
-            return dict(self)
-        prefix = prefix_for(*namespaces)
-        return { nskey : self[nskey] for nskey in self if nskey.startswith(prefix) }
+            return cls(self)
+        out = dict()
+        for namespace in namespaces:
+            out.update({ nskey : self[nskey] for nskey in self if nskey.startswith(namespace) })
+        return cls(out)
     
     def keys(self, *namespaces, unprefixed=False):
         """ Return a namespaced view over either all keys in the mapping,
@@ -198,15 +207,6 @@ class FrozenKeyMap(FrozenKeyMapBase):
     def _get_namespace_foset(self):
         return FlatOrderedSet(get_ns(nskey) for nskey in sorted(self) if NAMESPACE_SEP in nskey)
     
-    def _namespaces(self): # pragma: no cover
-        """ Iterate over all of the namespaces defined in the mapping.
-            
-            This is the generic implementation. It depends on “__iter__(…)”,
-            as implemented by the concrete descendant.
-        """
-        nss = { get_ns(nskey) for nskey in self if NAMESPACE_SEP in nskey }
-        yield from sorted(nss)
-    
     def namespaces(self):
         yield from self._get_namespace_foset()
     
@@ -237,17 +237,17 @@ class KeyMap(KeyMapBase, FrozenKeyMap):
         supra. for further deets, my doggie
     """
     
-    def set(self, key, value, *namespaces):
+    def set(self, key, value, *fragments):
         """ Set a (possibly namespaced) value for a given key. """
-        nskey = pack_ns(key, *namespaces)
+        nskey = pack_ns(key, *fragments)
         self[nskey] = value
     
-    def delete(self, key, *namespaces):
+    def delete(self, key, *fragments):
         """ Delete a (possibly namespaced) value from the mapping. """
-        nskey = pack_ns(key, *namespaces)
+        nskey = pack_ns(key, *fragments)
         del self[nskey]
     
-    def pop(self, key, *namespaces, default=NoDefault):
+    def pop(self, key, *fragments, default=NoDefault):
         """ Pop a (possibly namespaced) value off of the mapping
             and return either that value, or a default value
             if it doesn’t exist – raising a KeyError if no
@@ -256,10 +256,12 @@ class KeyMap(KeyMapBase, FrozenKeyMap):
         # NoDefault never escapes to userland – the call to
         # get(…) will raise the KeyError if NoDefault was passed
         # (Q.v. “get(¬)” definition supra.)
-        value = self.get(key, *namespaces, default=default)
+        value = self.get(key, *fragments, default=default)
+        if value is NoDefault:
+            return None
         if value == default or value is default:
             return value
-        self.delete(key, *namespaces)
+        self.delete(key, *fragments)
         return value
     
     def popitem(self):
@@ -297,7 +299,8 @@ class KeyMap(KeyMapBase, FrozenKeyMap):
             return None
         if not namespaces:
             return super().clear()
-        for nskey in self.submap(*namespaces).keys():
+        submaps = self.submap(*namespaces)
+        for nskey in submaps.keys():
             del self[nskey]
         return None
     
@@ -346,10 +349,10 @@ class NamespaceWalker(FrozenKeyMap):
             Concrete subclasses must implement “walk(…)” such that it iterates
             over all items in a given instance, yielding them in a form like:
             
-                for *namespaces, key, value in self.walk():
+                for *fragments, key, value in self.walk():
                     # …
             
-            … So an item with no namespaces would yield “['key', 'value']”,
+            … So an item with no namespace prefix would yield “['key', 'value']”,
             but one with three would yield “['do', 're', 'me', 'key', 'value']”.
             
             See the “mapwalk(…)” and “envwalk(…)” function implementations,
@@ -371,18 +374,10 @@ class NamespaceWalker(FrozenKeyMap):
         if cls is None:
             from clu.config.keymap import FrozenFlat
             cls = FrozenFlat
-        return cls({ pack_ns(key, *namespaces) : value for *namespaces, key, value in self.walk() })
-    
-    def _namespaces(self): # pragma: no cover
-        """ Iterate over all of the namespaces defined in the mapping. """
-        nss = set()
-        for *namespaces, key, value in self.walk():
-            if namespaces:
-                nss.add(concatenate_ns(*namespaces))
-        yield from sorted(nss)
+        return cls({ pack_ns(key, *fragments) : value for *fragments, key, value in self.walk() })
     
     def _get_namespace_foset(self):
-        return FlatOrderedSet(concatenate_ns(*ns) for *ns, _, _ in self.walk() if ns)
+        return FlatOrderedSet(concatenate_ns(*fragments) for *fragments, _, _ in self.walk() if fragments)
     
     def keys(self, *namespaces, unprefixed=False):
         """ Return a namespaced view over either all keys in the mapping,
@@ -412,25 +407,25 @@ class NamespaceWalker(FrozenKeyMap):
         return NamespaceWalkerValuesView(self, *namespaces)
     
     def __iter__(self):
-        for *namespaces, key, value in self.walk():
-            yield pack_ns(key, *namespaces)
+        for *fragments, key, value in self.walk():
+            yield pack_ns(key, *fragments)
     
     def __len__(self):
         return iterlen(self.walk())
     
     def __contains__(self, nskey):
-        key, namespaces = unpack_ns(nskey)
+        key, fragments = unpack_ns(nskey)
         for *ns, k, value in self.walk():
             if k == key:
-                if compare_ns(ns, namespaces):
+                if compare_ns(ns, fragments):
                     return True
         return False
     
     def __getitem__(self, nskey):
-        key, namespaces = unpack_ns(nskey)
+        key, fragments = unpack_ns(nskey)
         for *ns, k, value in self.walk():
             if k == key:
-                if compare_ns(ns, namespaces):
+                if compare_ns(ns, fragments):
                     return value
         raise KeyError(nskey)
 

{python_clu-0.12.11 → python_clu-0.12.13}/clu/config/env.py

@@ -27,9 +27,9 @@ def envwalk(appname, mapping):
     """
     app_prefix = prefix_env(appname)
     for envkey in (ek for ek in mapping.keys() if ek.startswith(app_prefix)):
-        an, key, namespaces = unpack_env(envkey)
+        an, key, fragments = unpack_env(envkey)
         assert an == appname
-        yield namespaces + [key, mapping[envkey]]
+        yield fragments + [key, mapping[envkey]]
 
 @export
 class FrozenEnviron(NamespaceWalker, clu.abstract.ReprWrapper,
@@ -50,9 +50,14 @@ class FrozenEnviron(NamespaceWalker, clu.abstract.ReprWrapper,
                |      +–––––––––––– namespaces (uppercased, one value)
                +––––––––––––––––––– app name (uppercased)
         
-        … This namespaced key can be accessed from an instance
-        of FrozenEnviron, initialized with an appname of “yodogg”,
-        as “iheard:youlike”.
+        … this corresponds to the namespaced key “iheard:youlike” from
+        an instance of “clu.config.env.Environ” initialized for the
+        appname “yodogg” (say). You can have multiple namespaces in an
+        environment key like the above – just add underscores. For
+        example, “YODOGG_I_HEARD_YOU_LIKE” differs from our given example
+        because it translates to the namespaced key “i:heard:you:like”,
+        which, you will note, is different.
+        
     """
     
     __slots__ = ('environment', 'appname')
@@ -198,8 +203,8 @@ def test():
         """ FrozenEnviron and “envwalk(…)” namespaced-key check """
         env = FrozenEnviron()
         
-        for *namespaces, key, value in envwalk('clu', os.environ.copy()):
-            nskey = pack_ns(key, *namespaces)
+        for *fragments, key, value in envwalk('clu', os.environ.copy()):
+            nskey = pack_ns(key, *fragments)
             assert nskey in env
     
     @inline
@@ -208,8 +213,8 @@ def test():
         updates = { 'yo' : 'dogg', 'iheard' : 'you like' }
         env = FrozenEnviron(**updates)
         
-        for *namespaces, key, value in envwalk('clu', os.environ.copy()):
-            nskey = pack_ns(key, *namespaces)
+        for *fragments, key, value in envwalk('clu', os.environ.copy()):
+            nskey = pack_ns(key, *fragments)
             assert nskey in env
         
         # getenv(…) key check: