python-clu 0.12.4__tar.gz → 0.12.7__tar.gz

{python_clu-0.12.4 → python_clu-0.12.7}/.bumpversion.toml

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

{python_clu-0.12.4 → python_clu-0.12.7}/CHANGELOG.md

@@ -1,7 +1,103 @@
 # Changelog
 
 
-## 0.12.3:pre13+g5d70474 [SNAPSHOT]
+## v0.12.6 (2025-05-19)
+
+### Other
+
+* Bumped version: 0.12.5 → 0.12.6. [Alexander Böhn]
+
+* [make] New changelog added. [Alexander Böhn]
+
+* The ANSI docstring CLU command seems to be up to snuff. [Alexander Böhn]
+
+* Further along the prettyprinting path. [Alexander Böhn]
+
+* Started on a new CLU command to prettyprint ANSI docstrings. [Alexander Böhn]
+
+  … please bear with as we travel on this journey together
+
+* Gratuitously expanded the docstring for `negate(…)` in `clu.predicates` [Alexander Böhn]
+
+  … comparing the function to a child with oppositional-defiant disorder.
+    It makes a lot of sense, no?
+
+* Spruced up the ANSI inline tests. [Alexander Böhn]
+
+
+## v0.12.5 (2025-05-19)
+
+### Add
+
+* Adding TOML module discussion screenshot. [Alexander Böhn]
+
+### Other
+
+* Bumped version: 0.12.4 → 0.12.5. [Alexander Böhn]
+
+* [make] New changelog added. [Alexander Böhn]
+
+* Starting to remove the legacy parts of `clu.config` [Alexander Böhn]
+
+  … fucking finally. These bits were an early draft of what became
+    the KeyMap system – they’ve been removed thoroughly from all the
+    farthest and darkest corners CLU has grown over the years. All
+    the legacy shit was pretty much only used in testing, and like
+    accedentally in some of the config file stuff. Good riddance I
+    say – the only thing that broke is a bunch of tests as old as the
+    legacy code itself. Yeah!
+
+* Updated the TOML file config reader (using native parsers) [Alexander Böhn]
+
+  … which can I ask, what the fuck is this dog’s breakfast with the
+    native TOML modules?! The standard-library pure-python thing is
+    just called “toml”. Fine, so far so good. Then, if you want
+    native TOML I/O, you have to install *two* native modules. The
+    one with “load(…)” and “loads(…)” is called ‘tomli’. Like, it’s
+    like “The ‘i’ is for input! Like accelerated input!” Sure. That’s
+    somewhat reasonable, it’d be nice if it was all in one module.
+    Because the other TOML native module has your “dump(…)” and your
+    “dumps(…)”, right, so what’s that one called though? Is it, by any
+    chance, ‘tomlo’? as in “The ‘o’ is for output”. Well no, that is
+    not the name of this module. In some sort of fit of solidarity
+    with ‘tomli’ the author of this shit decided to call it – wait
+    for it now…
+
+  			« tomli_w »
+
+  … yes you read that correctly. Not ‘tomlo’, not ‘tomlw’, none of
+    any sort of sense-making moniker, nor any moniker that doesn’t
+    make sense but at least was crafted with some sort of follow-able
+    logic. Nor, heaven forbid, would these modules be *combined* into
+    something sort of like the pure-python TOML thing, only native.
+    THAT WOULD BE WAY TOO MUCH TO ASK.
+
+  … so of course I did what I did in this commit, which was to firstly
+    import ‘tomli_w’ (The ‘w’ is for whatever!) as ‘tomlo’. And then
+    I stitched them together in a class called “toml” (crazy, right?)
+    that just had static alias methods to the native module functions.
+    Aesthetics are important, and they ain’t easy, it would seem. Yo.
+
+* Sometimes, I prefer to ask permission first. [Alexander Böhn]
+
+* Removed `setup.cfg` entry from `MANIFEST.in` [Alexander Böhn]
+
+* Minor `README.md` tweak. [Alexander Böhn]
+
+* Updated `README.md` with information on `clu.enums` and `clu.all` [Alexander Böhn]
+
+* EVEN MORE syntax-highlighted `README.md` code. [Alexander Böhn]
+
+* More syntax-highlighted	`README.md` code. [Alexander Böhn]
+
+* Trying out syntax-highlighted fenced code block in `README.md` [Alexander Böhn]
+
+* A few more addenda in `pyproject.toml` [Alexander Böhn]
+
+* Removed the old `setup.cfg` file. [Alexander Böhn]
+
+
+## v0.12.4 (2025-05-19)
 
 ### Add
 
@@ -11,6 +107,10 @@
 
 ### Other
 
+* Bumped version: 0.12.3 → 0.12.4. [Alexander Böhn]
+
+* [make] New changelog added. [Alexander Böhn]
+
 * More refinements to the whole `pyproject.toml` deal. [Alexander Böhn]
 
 * Fixed a few `pyproject.toml` build-related things. [Alexander Böhn]

{python_clu-0.12.4 → python_clu-0.12.7}/MANIFEST.in

@@ -25,7 +25,6 @@ include noxfile.py
 include pyproject.toml
 include pytest.ini
 include pytype.cfg
-include setup.cfg
 include setup.py
 include tox.ini
 

{python_clu-0.12.4 → python_clu-0.12.7}/Makefile

@@ -31,7 +31,7 @@ clean-type-caches:
 	rm -rf $(PROJECT_VENV)/var/cache/pytype
 
 cython:
-	python setup.py build_ext --inplace
+	python -m setup build_ext --inplace
 
 sdist:
 	python -m build

{python_clu-0.12.4 → python_clu-0.12.7}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: python-clu
-Version: 0.12.4
+Version: 0.12.7
 Summary: Python-CLU: Common Lightweight Utilities
 Home-page: https://github.com/fish2000/clu
 Download-URL: https://github.com/fish2000/clu/zipball/master
 Author: Alexander Böhn
 Author-email: Alexander Böhn <fish2000@gmail.com>
+Maintainer-email: Alexander Böhn <fish2000@gmail.com>
+License-Expression: LicenseRef-CLU-MIT
 Project-URL: homepage, https://github.com/fish2000/CLU
 Project-URL: repository, https://github.com/fish2000/CLU
 Project-URL: documentation, https://github.com/fish2000/CLU/blob/master/README.md
@@ -33,7 +35,7 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: build
+Requires-Dist: build>=1.2.2
 Requires-Dist: Click>=7.0
 Requires-Dist: colorama>=0.4.0
 Requires-Dist: dataclasses>=0.6; python_version < "3.7"
@@ -52,6 +54,8 @@ Requires-Dist: redis>=3.4.0
 Requires-Dist: setuptools>=30.0.0
 Requires-Dist: six>=1.10.0
 Requires-Dist: toml>=0.10.0
+Requires-Dist: tomli>=2.2.0
+Requires-Dist: tomli_w>=1.2.0
 Requires-Dist: wheel>=0.34.0
 Requires-Dist: zict>=0.1.2
 Provides-Extra: all
@@ -116,20 +120,24 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     around lexically namespaced dictionaries called “KeyMaps”, which basic examples of which can be
     found in [`clu.config.keymap`][clu.config.keymap]. If your nested data looks like:
 
-        data = {
-            'yo' : {
-                'dogg' : {
-                    'i-heard' : {
-                        'you-like' : "nested data"
-                    }
+    ```python
+    data = {
+        'yo' : {
+            'dogg' : {
+                'i-heard' : {
+                    'you-like' : "nested data"
                 }
             }
         }
+    }
+    ```
     
     … and you assign it to a keymap, like e.g. `keyed = keymap.Nested(data).flatten()`, then you can
     use `keyed` like so:
     
-        assert keyed["yo:dogg:i-heard:you-like"] == "nested data"
+    ```python
+    assert keyed["yo:dogg:i-heard:you-like"] == "nested data"
+    ```
     
     … The `Flat` and `Nested` classes are cheap to construct and lightweight, and generally act like most
     [`dict`][dicts] instances in most of the expected ways. There is also an environment-variable [`keymap`][clu.config.keymap]
@@ -137,10 +145,12 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     `MYAPP_CONFIG_THINGY`, they can be accessed through `env.FrozenEnviron(appname='myapp')` or
     `env.Environ(appname='myapp')` like so:
     
-        appenv = Environ(appname='myapp')
-        assert appenv['config:thingy'] == "some value"
-        appenv['config:doohickey'] = "a different value" # sets MYAPP_CONFIG_DOOHICKEY
-                                                         # in the current env
+    ```python
+    appenv = Environ(appname='myapp')
+    assert appenv['config:thingy'] == "some value"
+    appenv['config:doohickey'] = "a different value" # sets MYAPP_CONFIG_DOOHICKEY
+                                                     # in the current env
+    ```
     
     … and there are plenty of tools for rolling your own `KeyMap`s in [`clu.config`][clu.config]: the
     [`proxy`][clu.config.proxy] subpackage has a `KeyMap` proxy class, [`ns`][clu.config.ns] has utility functions
@@ -153,6 +163,15 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     [polyfills][clu.constants.polyfills] to allow certain dependencies from the Python standard library to work even
     when some of their moving parts are missing (i.e. Ye Olde Pythone 2.7, various PyPy implementations, etc).
 
+* [`all`][clu.all]: Herein you will find some verrrrry interesting “meta” functions for CLU. You have the `import_all_modules(…)`
+    function, which when provided your projects’ base path and appname, will return all the package names therein,
+    whether class-based modules defined through [`clu.exporting`][clu.exporting] or plain ol’ modules defined by files
+    ending in “.py”, basically. It’s awesome.
+    
+    The companion function `import_clu_modules(¬)` is a shortcut just for everything within CLU, and `inline_tests(…)`
+    yields an iterator over every CLU module that defines inline tests through [`clu.testing`][clu.testing]. These
+    are very useful within CLU; for your own project, write your own functions modeled after these! You can’t go wrong.
+
 * [`fs`][clu.fs]: Filesystem-related things. Submodules include:
     
     * [`fs.filesystem`][clu.fs.filesystem]: classes representing filesystem primitives like `Directory`,
@@ -177,28 +196,30 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     
 * [`importing`][clu.importing]: a whole class-based-module system! Basically you can do this:
 
-        class Derived(clu.importing.base.Module):
-        
-            """ I heard you like docstrings """
-        
-            yo = 'dogg'
-        
-            @export
-            def yodogg(self):
-                return "I heard you like"
-        
-            @export
-            def nodogg(self):
-                return None
-        
-            export(yo, name='yo')
-        
-        from clu.app import Derived as derived # TAKE NOTE!!!
-        
-        assert isinstance(derived, Module)
-        assert derived.yo == 'dogg'
-        assert derived.yodogg() == "I heard you like"
-        assert derived.nodogg() is None
+    ```python
+    class Derived(clu.importing.base.Module):
+    
+        """ I heard you like docstrings """
+    
+        yo = 'dogg'
+    
+        @export
+        def yodogg(self):
+            return "I heard you like"
+    
+        @export
+        def nodogg(self):
+            return None
+    
+        export(yo, name='yo')
+    
+    from clu.app import Derived as derived # TAKE NOTE!!!
+    
+    assert isinstance(derived, Module)
+    assert derived.yo == 'dogg'
+    assert derived.yodogg() == "I heard you like"
+    assert derived.nodogg() is None
+    ```
 
     … see that? just by subclassing [`clu.importing.base.Module`][clu.importing.base] you can create something
     instantly importable. Awesome, wouldn’t you say? I would say. We’re working out the best way to create the
@@ -214,7 +235,9 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     
     [`clu.scripts`][clu.scripts] contains a [“repl.py”][clu.scripts.repl] file, which is meant to be loaded into an interactive interpreter like e.g.:
     
-        $ bpython -i «PATH_TO_CLU»/clu/scripts/repl.py
+    ```bash
+    $ bpython -i «PATH_TO_CLU»/clu/scripts/repl.py
+    ```
     
     … which will set all of CLU up for you to use interactively. N.B. if you have your own script you want to include
     but stil want to use CLU, you can set the `CLU_USER_SCRIPT` environment variable to the path to your own script,
@@ -235,6 +258,34 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     there at the end. ALSO, there are additional useful types, from Python’s standard library and common packages,
     in the [`types` namespace][clu.typespace.namespace]. YOU’RE WELCOME!!
 
+* [`enums`][clu.enums]: Furnishes  `alias(…)` – which, spoiler alert, let you create aliases within your enums!
+    Oh yes. Like so:
+    
+    ```python
+    
+    from clu.enums import alias
+    
+    @unique
+    class Numbers(Enum):
+        ONE = 1
+        TWO = 2
+        THREE = 3
+        UNO = alias(ONE)
+        DOS = alias(TWO)
+        TRÉS = alias(THREE)
+    
+    assert Numbers.ONE == Numbers.UNO
+    assert Numbers.TWO == Numbers.DOS
+    assert Numbers.THREE == Numbers.TRÉS
+    
+    ```
+    
+    … aaaaand BOOM, there you go! The `alias` members of an enum don’t show up when iterating the
+    enum’s members, so they’re for your convenience. For a fantastic CLUish real-life example, have a look at
+    the [`clu.repl.ansi`][clu.repl.ansi] module, and [the enums it defines][clu.repl.ansi.enums] – these use a metaclass
+    to line the enum’s standard members up with some predefined class attributes defined in a third-party module;
+    we use `alias(…)` to provide more obvious lexical aliases of these attributes. Yes!
+
 * [`dicts`][clu.dicts]: Functions and classes for wrangling [`dict`s][dicts] (and actually [`Mapping`][collections.abc.Mapping]
     and [`MutableMapping`][collections.abc.MutableMapping] descendants in general). There are ABCs for
     key/value/item views for your own mappings, a much better `ChainMap`, written from scratch and improving
@@ -244,29 +295,34 @@ So do have a look around. Here’s an abridged breakdown of some things within:
 * [`exporting`][clu.exporting]: This is kind of the heart of CLU. At the beginning of all internal CLU modules, you’ll find something
     using the `Exporter`, like this:
     
-        from clu.exporting import Exporter
-        
-        exporter = Exporter(path=__file__)
-        export = exporter.decorator()
+    ```python
+    from clu.exporting import Exporter
     
+    exporter = Exporter(path=__file__)
+    export = exporter.decorator()
+    ```
     … which I know, I know, the use of `__file__` there is kind of irritating. But that `exporter` instance is now
     registered with CLU, and whenever there’s a class or function you want made available outside the module,
     you can specify it like:
     
-        @export
-        def public_function():
-            print("I’m so public")
-            
-        class PrivateAncestor:
-            """ I’m more private, don’t play with me """
-            
-        @export
-        class PublicThing(PrivateAncestor):
-            """ I’m very public, indeed, and available """
+    ```python
+    @export
+    def public_function():
+        print("I’m so public")
+        
+    class PrivateAncestor:
+        """ I’m more private, don’t play with me """
+        
+    @export
+    class PublicThing(PrivateAncestor):
+        """ I’m very public, indeed, and available """
+    ```
     
     At the end of the module (but before your CLU tests, q.v. note _sub_.) you put:
     
-        __all__, __dir__ = exporter.all_and_dir()
+    ```python
+    __all__, __dir__ = exporter.all_and_dir()
+    ```
     
     … which makes things clear what is public and what is private to consumers of your code, without messing
     around with underscore prefixes, which I find coarse, and vulgar. You’re not just labeling things for export,
@@ -277,8 +333,10 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     For your own project, at some part in your code, all you have to do is: `from clu.exporting import ExporterBase`,
     and then subclass `ExporterBase` with your app’s name and base path. Like so:
     
-        class Exporter(ExporterBase, basepath="/your/project", appname="MyProject"):
-            pass
+    ```python
+    class Exporter(ExporterBase, basepath="/your/project", appname="MyProject"):
+        pass
+    ```
     
     … then import your own importer (or call it whatever you want) at the top of your own CLUish modules and
     instantiate per the example _supra_. See also [`clu.scripts.dictroast`][clu.scripts.dictroast] for other tricks your
@@ -288,38 +346,40 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     [`pytest`][pytest-link] – all you have to do is, after your line assigning `__all__` and `__dir__` at the end
     of the module proper, something like:
     
-        def test():
-            from clu.testing.utils import inline
-        
-            @inline.precheck
-            def before_everything_else():
-        	    """ This function runs once before testing """
-                # ...
-                
-            @inline
-            def first_test():
-                """ This test does one thing """
-                # ...
-                
-            @inline
-            def second_test():
-        	    """ This test does another thing """
-                # ...
-                
-            @inline.runif(something == something_else)
-            def test_conditionally_run():
-        	    """ This test only does something if `something` == `something_else` """
-                # ...
-                
-            @inline.diagnostic
-            def apres_testing():
-        	    """ This function runs once after testing """
-                # ...
-                
-            return inline.test(100)
-        
-        if __name__ == '__main__':
-            sys.exit(test())
+    ```python
+    def test():
+        from clu.testing.utils import inline
+    
+        @inline.precheck
+        def before_everything_else():
+    	    """ This function runs once before testing """
+            # ...
+            
+        @inline
+        def first_test():
+            """ This test does one thing """
+            # ...
+            
+        @inline
+        def second_test():
+    	    """ This test does another thing """
+            # ...
+            
+        @inline.runif(something == something_else)
+        def test_conditionally_run():
+    	    """ This test only does something if `something` == `something_else` """
+            # ...
+            
+        @inline.diagnostic
+        def apres_testing():
+    	    """ This function runs once after testing """
+            # ...
+            
+        return inline.test(100)
+    
+    if __name__ == '__main__':
+        sys.exit(test())
+    ```
 
     … running the module (with either `python -m yourapp.yourmodule` or, say, [Nox][nox-link]) will show
     you each tests’ output. But see that `return inline.test(100)` line? That integer argument tells
@@ -345,7 +405,9 @@ So do have a look around. Here’s an abridged breakdown of some things within:
     “qualified names” – for instance, you can use `naming.qualified_import(…)` to import a class [`CurveSet`][instakit.processors.curves.CurveSet]
     from its package [`instakit.processors.curves`][instakit.processors.curves] by doing:
     
-        CurveSet = qualified_import('instakit.processors.curves.CurveSet')
+    ```python
+    CurveSet = qualified_import('instakit.processors.curves.CurveSet')
+    ```
     
     … which that may be handier for you than composing and hard-coding an `import` statement. See also the
     `nameof(…)` and `moduleof(…)` functions, and the utility functions (e.g. `qualified_name(…)`) and
@@ -456,6 +518,7 @@ So do have a look around. Here’s an abridged breakdown of some things within:
 
 [clu.repl]: https://github.com/fish2000/CLU/tree/master/clu/repl
 [clu.repl.ansi]: https://github.com/fish2000/CLU/tree/master/clu/repl/ansi.py
+[clu.repl.ansi.enums]: https://github.com/fish2000/CLU/blob/c5be3edcea7774b0d042b13125458fef6bd8a303/clu/repl/ansi.py#L150-L222
 [clu.repl.banners]: https://github.com/fish2000/CLU/tree/master/clu/repl/banners.py
 [clu.repl.columnize]: https://github.com/fish2000/CLU/tree/master/clu/repl/columnize.py
 [clu.repl.modules]: https://github.com/fish2000/CLU/tree/master/clu/repl/modules.py