Applied minor improvements

dhondta · dhondta · commit f04f6e2f6ede · 2021-11-20T13:35:20.000+01:00
diff --git a/README.md b/README.md
@@ -16,6 +16,10 @@ This library extends the native [`codecs`](https://docs.python.org/3/library/cod
 $ pip install codext
 ```
 
+Want to contribute a new codec ?    |  Want to contribute a new macro ?
+:----------------------------------:|:---------------------------------
+Check the [documentation](https://python-codext.readthedocs.io/en/latest/howto.html) first<br>Then [PR](https://github.com/dhondta/python-codext/pulls) your new codec | [PR](https://github.com/dhondta/python-codext/pulls) your updated version of [`macros.json`](https://github.com/dhondta/python-codext/blob/master/codext/macros.json)
+
 ## :mag: Demonstrations
 
 <p align="center"><img src="https://raw.githubusercontent.com/dhondta/python-codext/master/docs/demos/using-codext.gif" alt="Using CodExt from the command line"></p>
diff --git a/codext/__common__.py b/codext/__common__.py
@@ -33,8 +33,7 @@
 __all__ = ["add", "add_macro", "add_map", "b", "clear", "codecs", "decode", "encode", "ensure_str", "examples", "guess",
            "isb", "generate_strings_from_regex", "get_alphabet_from_mask", "handle_error", "is_native",
            "list_categories", "list_encodings", "list_macros", "lookup", "maketrans", "os", "rank", "re", "register",
-           "remove", "remove_macro", "reset", "s2i", "search", "stopfunc", "BytesIO", "MASKS", "PY3", "_input",
-           "_stripl", "CodecMacro"]
+           "remove", "reset", "s2i", "search", "stopfunc", "BytesIO", "MASKS", "PY3", "_input", "_stripl", "CodecMacro"]
 CODECS_REGISTRY = None
 CODECS_CATEGORIES = ["native", "custom"]
 MASKS = {
@@ -83,7 +82,7 @@ def __new__(cls, name):
         self.codecs = [lookup(e, False) for e in self.codecs]  # lookup(e, False)
         self.parameters = {'name': name, 'category': "macro"}  #             ^  means that macros won't be nestable
         # test examples to check that the chain of encodings works
-        for action, examples in (self.codecs[0].parameters.get('examples', {}) or {}).items():
+        for action, examples in (self.codecs[0].parameters.get('examples', {}) or {'enc-dec(': ["T3st str!"]}).items():
             if re.match(r"enc(-dec)?\(", action):
                 for e in (examples.keys() if action.startswith("enc(") else examples or []):
                     rd = re.match(r"\@random(?:\{(\d+(?:,(\d+))*?)\})?$", e)
@@ -298,17 +297,23 @@ def add_macro(mname, *encodings):
     :param mname:     macro name
     :param encodings: encoding names of the encodings to be chained with the macro
     """
+    global PERS_MACROS
     # check for name clash with alreday existing macros and codecs
     if mname in MACROS or mname in PERS_MACROS:
         raise ValueError("Macro name already exists")
     try:
         ci = lookup(mname, False)
         raise ValueError("Macro name clashes with codec '%s'" % ci.name)
     except LookupError:
-        #TODO: test if the encodings sequence can work, using an example from the first codec
+        pass
+    try:
         PERS_MACROS[mname] = encodings
+        CodecMacro(mname)
         with open(PERS_MACROS_FILE, 'w') as f:
-            json.dump(PERS_MACROS, f)
+            json.dump(PERS_MACROS, f, indent=2)
+    except ValueError:
+        del PERS_MACROS[mname]
+        raise
 codecs.add_macro = add_macro
 
 
@@ -551,8 +556,8 @@ def __get_value(token, position, case_changed=False):
 
 def clear():
     """ Clear codext's local registry of search functions. """
-    global __codecs_registry
-    __codecs_registry = []
+    global __codecs_registry, MACROS, PERS_MACROS
+    __codecs_registry, MACROS, PERS_MACROS = [], {}, {}
 codecs.clear = clear
 
 
@@ -648,34 +653,32 @@ def list_macros():
     return sorted(list(set(list(MACROS.keys()) + list(PERS_MACROS.keys()))))
 
 
-def remove(encoding):
-    """ Remove all search functions matching the input encoding name from codext's local registry. """
+def remove(name):
+    """ Remove all search functions matching the input encoding name from codext's local registry or any macro with the
+         given name. """
+    global __codecs_registry, MACROS, PERS_MACROS
     tbr = []
     for search_function in __codecs_registry:
-        if search_function(encoding) is not None:
+        if search_function(name) is not None:
             tbr.append(search_function)
     for search_function in tbr:
         __codecs_registry.remove(search_function)
-codecs.remove = remove
-
-
-def remove_macro(name):
-    """ Remove the given macro from the macro registries. """
     try:
         del MACROS[name]
     except KeyError:
         pass
     try:
         del PERS_MACROS[name]
         with open(PERS_MACROS_FILE, 'w') as f:
-            json.dump(PERS_MACROS, f)
+            json.dump(PERS_MACROS, f, indent=2)
     except KeyError:
         pass
+codecs.remove = remove
 
 
 def reset():
     """ Reset codext's local registry of search functions and macros. """
-    global CODECS_REGISTRY, MACROS, PERS_MACROS, __codecs_registry
+    global __codecs_registry, CODECS_REGISTRY, MACROS, PERS_MACROS
     clear()
     d = os.path.dirname(__file__)
     for pkg in sorted(os.listdir(d)):
diff --git a/docs/features.md b/docs/features.md
@@ -161,6 +161,31 @@ In this second example, we can see that:
 
 -----
 
+## Add a macro
+
+**Macros** are chains of encodings. It is possible to define own macros with this feature. It works by giving the precedence to user's macros saved in `~/.codext-macros.json` then using embedded macros from the `codext` package.
+
+Here is an example of adding a macro (and verifying it was indeed added):
+
+```python
+>>> codext.list_macros()
+['example-macro']
+>>> codext.add_macro("test-macro", "gzip", "base64")
+>>> codext.list_macros()
+['example-macro', 'test-macro']
+```
+
+!!! note "Removing a macro"
+    
+    As macros are resolved like codecs (with the precedence for codecs), they can be removed the same way as a codec.
+    
+        :::python
+        >>> codext.remove("test-macro")
+    
+    If this is a built-in macro, it will removed from the runtime list within the `codext` package. Next time this will be loaded, it will reset the builtin list of macros. Otherwise, if this is a custom macro, it will removed from the list of custom macros AND removed from `~/.codext-macros.json`.
+
+-----
+
 ## List codecs
 
 Codecs can be listed with the `list` function, either the whole codecs or only some categories.
@@ -225,7 +250,7 @@ Also, `codext` provides an `examples` function to get some examples of valid enc
 
 -----
 
-## Remove a custom encoding
+## Remove a custom encoding or macro
 
 New codecs can be removed easily using the new function `remove`, which will only remove every codec matching the given encoding name in the proxy codecs registry and NOT in the native one.
 
@@ -240,19 +265,25 @@ Traceback (most recent call last):
 LookupError: unknown encoding: bin
 ```
 
-While trying to remove a codec that is in the native registry won't raise a `LookupError`.
+Trying to remove a codec that is in the native registry won't raise a `LookupError`.
 
 ```python
 >>> codext.remove("utf-8")
 >>> codext.encode("test", "utf-8")
 b'test'
 ```
 
+Removing a macro works exactly the same way as for a codec.
+
+```python
+>>> codext.remove("test-macro")
+```
+
 -----
 
-## Remove or restore `codext` encodings
+## Remove or restore `codext` encodings and macros
 
-It can be useful while playing with encodings e.g. from Idle to be able to remove or restore `codext`'s encodings. This can be achieved using respectively the new `clear` and `reset` functions.
+It can be useful while playing with encodings and/or macros e.g. from Idle to be able to remove or restore `codext`'s encodings and macros. This can be achieved using respectively the new `clear` and `reset` functions.
 
 ```python
 >>> codext.clear()
diff --git a/tests/test_common.py b/tests/test_common.py
@@ -214,7 +214,7 @@ def test_handle_macros(self):
         MACRO = "test-macro-f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2"
         STR = "this is a test"
         ENC = "H4sIAMrbkmEC/0txzyhIrnQC4QxPj6CcZONAWwAMIDOIFAAAAA=="
-        codext.remove_macro(MACRO)
+        codext.remove(MACRO)
         l = codext.list_macros()
         self.assertTrue(len(l) > 0)
         cm = codext.lookup("example-macro")
@@ -235,14 +235,14 @@ def test_handle_macros(self):
             json.dump(PERS_MACROS, f)
         codext.reset()
         self.assertRaises(ValueError, codext.lookup, MACRO)
-        self.assertIsNone(codext.remove_macro(MACRO))
+        self.assertIsNone(codext.remove(MACRO))
         self.assertRaises(LookupError, codext.lookup, MACRO)
         self.assertNotIn(MACRO, codext.list_macros())
-        self.assertIsNone(codext.remove_macro("THIS-MACRO-DOES-NOT-EXIST"))
-        self.assertIsNone(codext.remove_macro("VALID-MACRO"))
+        self.assertIsNone(codext.remove("THIS-MACRO-DOES-NOT-EXIST"))
+        self.assertIsNone(codext.remove("VALID-MACRO"))
         self.assertIsNone(codext.add_macro("VALID-MACRO", "gzip", "base64"))
-        self.assertIsNone(codext.remove_macro("VALID-MACRO"))
+        self.assertIsNone(codext.remove("VALID-MACRO"))
         self.assertIsNone(codext.add_macro("VALID-MACRO", "lzma", "base64"))
-        self.assertIsNone(codext.remove_macro("VALID-MACRO"))
+        self.assertIsNone(codext.remove("VALID-MACRO"))
         self.assertRaises(ValueError, codext.add_macro, "SHALL-FAIL", "base26", "sms", "letter-indices")
 
