wizlib 0.0.0__py3-none-any.whl

wizlib/app.py

@@ -0,0 +1,85 @@
+import sys
+from dataclasses import dataclass
+import os
+from pathlib import Path
+
+from wizlib.class_family import ClassFamily
+from wizlib.command import WizHelpCommand
+from wizlib.super_wrapper import SuperWrapper
+from wizlib.parser import WizParser
+
+
+RED = '\033[91m'
+RESET = '\033[0m'
+
+
+class WizApp:
+    """Root of all WizLib-based CLI applications. Subclass it. Can be
+    instantiated and then run multiple commands."""
+
+    base_command = None
+    name = ''
+
+    @classmethod
+    def main(cls):  # pragma: nocover
+        """Call this from a __main__ entrypoint"""
+        cls.run(*sys.argv[1:], debug=os.getenv('DEBUG'))
+
+    @classmethod
+    def run(cls, *args, debug=False):
+        """Call this from a Python entrypoint"""
+        try:
+            cls.initialize()
+            app = cls(*args)
+            # if app.ready:
+            command = app.first_command
+            result = command.execute()
+            if result:
+                print(result, file=sys.stdout, end='')
+                if sys.stdout.isatty():  # pragma: nocover
+                    print()
+            if command.status:
+                print(command.status, file=sys.stderr)
+        except Exception as error:
+            if debug:
+                raise error
+            else:
+                print(f"\n{RED}{type(error).__name__}: " +
+                      f"{error}{RESET}\n", file=sys.stderr)
+                sys.exit(1)
+
+    @classmethod
+    def initialize(cls):
+        """Set up the app class to parse arguments"""
+        cls.parser = WizParser(
+            prog=cls.name,
+            exit_on_error=False)
+        for handler in cls.base_command.handlers:
+            cls.parser.add_argument(
+                f"--{handler.name}",
+                f"-{handler.name[0]}",
+                type=handler.named(cls.name),
+                default='')
+        subparsers = cls.parser.add_subparsers(dest='command')
+        for command in cls.base_command.family_members('name'):
+            key = command.get_member_attr('key')
+            aliases = [key] if key else []
+            subparser = subparsers.add_parser(command.name, aliases=aliases)
+            command.add_args(subparser)
+
+    def __init__(self, *args):
+        args = args if args else [self.base_command.default]
+        self.vals = vars(self.parser.parse_args(args))
+        self.first_command = self.get_command(**self.vals)
+
+    def get_command(self, **vals):
+        """Run a single command"""
+        if 'help' in vals:
+            return WizHelpCommand(**vals)
+        else:
+            command_name = vals.pop('command')
+            command_class = self.base_command.family_member(
+                'name', command_name)
+            if not command_class:
+                raise Exception(f"Unknown command {command_name}")
+            return command_class(**vals)

wizlib/class_family.py

@@ -0,0 +1,120 @@
+from importlib import import_module
+from inspect import getmodule
+from pathlib import Path
+from re import match
+
+
+class ClassFamily:
+
+    # Return an attribute of this specific class, not inherited.
+
+    @classmethod
+    def get_member_attr(self, attribute):
+        if attribute in self.__dict__:
+            return self.__dict__[attribute]
+
+    # True or False: This class has all the attributes provided. Return True if
+    # no attributes provided. Use __subclasses__ so we only look at direct
+    # descendents, and __dict__ so we only look at attributes defined here (not
+    # inherited).
+
+    @classmethod
+    def has_member_attrs(self, *attributes):
+
+        # Do I have all the attributes?
+        matches = [a in self.__dict__ for a in attributes]
+
+        # Python's all() function returns True if the list is empty. So we kill
+        # two birds with one stone here - get a hit if there are no attributes,
+        # and avoid the empty-matches problem.
+        return all(matches + list(attributes))
+
+    # Return a set of myself and all my descendents that have certain
+    # attributes. If no attribute names are provided, return the entire family.
+
+    @classmethod
+    def family_members(self, *attributes):
+
+        # Put myself into a set if I qualify
+        hits = {self} if self.has_member_attrs(*attributes) else set()
+
+        # Go through my subclasses
+        for kid in self.family_children():
+
+            # Call the same function on each subclass
+            hits |= kid.family_members(*attributes)
+
+        # Send it back
+        return hits
+
+    @classmethod
+    def family_attrs(self, attribute):
+        """
+        Return a set of all the values of a specific attribute that exist in
+        the family. The set avoids repetition of values in the result.
+        """
+        # Put myself into a set if I qualify
+        if self.has_member_attrs(attribute):
+            values = {self.get_member_attr(attribute)}
+        else:
+            values = set()
+
+        # Go through my subclasses
+        for kid in self.family_children():
+
+            # Call the same function on each subclass
+            values |= kid.family_attrs(attribute)
+
+        # Send it back
+        return values
+
+    @classmethod
+    def family_member(self, attribute, value):
+        """Return a specific family member that has a specified value of an
+        attribute. Assume that there is only one, so return it as soon as it's
+        found."""
+
+        # See if I qualify, and if so, return myself. Use __dict__ rather than
+        # hasattr() and getattr() to refer only to myself, rather than
+        # inherited attributes.
+        if attribute in self.__dict__:
+            if self.__dict__[attribute] == value:
+                return self
+
+        # Go through the subclasses, doing the same. The return statement will
+        # exit the loop, so we get out as soon as we find one, without having
+        # to evaluate others.
+        for kid in self.family_children():
+            found = kid.family_member(attribute, value)
+            if found:
+                return found
+
+    # Import the whole family, so they show up as subclasses. Then return this
+    # classes subclasses. This obviates the need to import everything at
+    # initialization. It happens when needed, and only once.  Family members
+    # must be in modules (files) in the same directory as the parent (me).
+    # Furthermore, all the files in that directory will be imported. The only
+    # exception is a file with the same name as myself, to avoid circular
+    # imports. This is a private method, intended to be called when needed.
+
+    @classmethod
+    def family_children(self):
+
+        # We only need to import the family once
+        if not hasattr(self, '_family_imported'):
+
+            # Find the location of the directory and the name of the module
+            module = getmodule(self)
+            directory = Path(module.__file__).parent
+            module_name = module.__package__
+
+            # Go through the directory and import everything into the module
+            for import_file in directory.iterdir():
+                if match(r'^[^_].*\.py$', import_file.name):
+                    import_module(f'{module_name}.{import_file.stem}')
+
+            # Prevent it from needing to run again
+            self._family_imported = True
+
+        # Return the subclasses (children)
+        return self.__subclasses__()

wizlib/command.py

@@ -0,0 +1,45 @@
+from argparse import ArgumentParser
+from pathlib import Path
+
+from wizlib.class_family import ClassFamily
+from wizlib.config_handler import ConfigHandler
+from wizlib.input_handler import InputHandler
+from wizlib.super_wrapper import SuperWrapper
+
+
+class WizCommand(ClassFamily, SuperWrapper):
+    """Define all the args you want, but stdin always works."""
+
+    status = ''
+    handlers = []
+
+    @classmethod
+    def add_args(self, parser):
+        """Add arguments to the command's parser - override this.
+        Add global arguments in the base class. Not wrapped."""
+        pass
+
+    def __init__(self, **vals):
+        for key in vals:
+            setattr(self, key, vals[key])
+        for handler in self.handlers:
+            if handler.name not in vals:
+                setattr(self, handler.name, handler())
+
+    def handle_vals(self):
+        """Clean up vals, calculate any, ask through UI, etc. - override
+        this and call super().handle_vals()."""
+        pass
+
+    def execute(self, method, *args, **kwargs):
+        """Actually perform the command - override and wrap this via
+        SuperWrapper"""
+        self.handle_vals()
+        result = method(self, *args, **kwargs)
+        return result
+
+
+class WizHelpCommand(WizCommand):
+
+    def execute(self):
+        return self.help

wizlib/config_handler.py

@@ -0,0 +1,87 @@
+from argparse import Namespace
+from pathlib import Path
+import os
+from dataclasses import dataclass
+from unittest.mock import patch
+
+from yaml import load
+from yaml import Loader
+from wizlib.handler import Handler
+
+from wizlib.error import ConfigHandlerError
+
+
+class ConfigHandler(Handler):
+    """
+    Handle app-level configuration, where settings could come from specific
+    settings (such as from argparse), environment variables, or a YAML file.
+    Within the Python code, config keys are underscore-separated all-lower.
+
+    A ConfigHandler returns null in the case of a missing value, assuming that
+    commands can handle their own null cases.
+    """
+
+    name = 'config'
+
+    def __init__(self, value=None):
+        self.file = value
+        self.cache = {}
+
+    @property
+    def yaml(self):
+        if hasattr(self, '_yaml'):
+            return self._yaml
+        path = None
+        if self.file:
+            path = Path(self.file)
+        elif self.appname:
+            localpath = Path.cwd() / f".{self.appname}.yml"
+            homepath = Path.home() / f".{self.appname}.yml"
+            if (envvar := self.env(self.appname + '-config')):
+                path = Path(envvar)
+            elif (localpath.is_file()):
+                path = localpath
+            elif (homepath.is_file()):
+                path = homepath
+        if path:
+            with open(path) as file:
+                self._yaml = load(file, Loader=Loader)
+                return self._yaml
+
+    @staticmethod
+    def env(name):
+        if (envvar := name.upper().replace('-', '_')) in os.environ:
+            return os.environ[envvar]
+
+    def get(self, key: str):
+        """Return the value for the requested config entry"""
+
+        # If we already found the value, return it
+        if key in self.cache:
+            return self.cache[key]
+
+        # Environment variables take precedence
+        if (result := self.env(key)):
+            self.cache[key] = result
+            return result
+
+        # Otherwise look at the YAML
+        if (yaml := self.yaml):
+            split = key.split('-')
+            while (val := split.pop(0)) and (val in yaml):
+                yaml = yaml[val] if val in yaml else None
+                if not split:
+                    self.cache[key] = yaml
+                    return yaml
+
+    @classmethod
+    def fake(cls, **vals):
+        """Return a fake ConfigHandler with forced values, for testing"""
+        handler = cls()
+
+        def fake_env(name):
+            key = name.replace('-', '_')
+            if key in vals:
+                return vals[key]
+        handler.env = fake_env
+        return handler

wizlib/error.py

@@ -0,0 +1,2 @@
+class ConfigHandlerError(Exception):
+    pass

wizlib/handler.py

@@ -0,0 +1,14 @@
+from argparse import Action
+
+
+class Handler:
+    """Base class for handlers"""
+
+    appname = None
+
+    @classmethod
+    def named(cls, name):
+        """Subclass of the handler that holds the app name as a closure"""
+        class NamedHandler(cls):
+            appname = name
+        return NamedHandler

wizlib/input_handler.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+import sys
+
+from wizlib.handler import Handler
+
+
+class InputHandler(Handler):
+
+    name = 'input'
+    text: str = ''
+
+    def __init__(self, file=None, stdin=True):
+        if file:
+            self.text = Path(file).read_text()
+        elif stdin and (not sys.stdin.isatty()):
+            self.text = sys.stdin.read()
+
+    def __str__(self):
+        return self.text
+
+    @classmethod
+    def fake(cls, value):
+        """Return a fake InputHandler with forced values, for testing"""
+        handler = cls(stdin=False)
+        handler.text = value
+        return handler

wizlib/parser.py

@@ -0,0 +1,54 @@
+"""A drop-in replacement for ArgumentParser that always raises exceptions
+for argument errors (including unrecognized arguments) and returns help
+messages in a 'help' item in the resulting namespace. Useful especially for
+REPLs."""
+
+
+from argparse import ArgumentParser
+from argparse import ArgumentError
+from argparse import Action
+from argparse import SUPPRESS
+from contextlib import redirect_stdout
+from io import StringIO
+import sys
+import os
+
+
+class WizHelpAction(Action):
+
+    def __init__(self,
+                 option_strings,
+                 dest=SUPPRESS,
+                 default=SUPPRESS,
+                 help=None):
+        super(WizHelpAction, self).__init__(
+            option_strings=option_strings,
+            dest=dest,
+            default=default,
+            nargs=0,
+            help=help)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        with redirect_stdout(output := StringIO()):
+            parser.print_help()
+        output.seek(0)
+        setattr(namespace, self.dest, output.read())
+
+
+class WizArgumentError(ArgumentError):
+
+    def __init__(self, message):
+        self.argument_name = None
+        self.message = message
+
+
+class WizParser(ArgumentParser):
+
+    def __init__(self, **vals):
+        vals['exit_on_error'] = False
+        vals['add_help'] = False
+        super().__init__(**vals)
+        self.add_argument('--help', '-h', action=WizHelpAction)
+
+    def error(self, *args, **vals):
+        raise WizArgumentError(str(args[0]))

wizlib/rlinput.py

@@ -0,0 +1,71 @@
+try:  # pragma: nocover
+    import gnureadline as readline
+except ImportError:  # pragma: nocover
+    import readline
+import sys
+
+
+# Use tab for completion
+readline.parse_and_bind('tab: complete')
+
+# Only a space separates words
+readline.set_completer_delims(' ')
+
+
+# Readline defaults to complete with local filenames. Definitely not what we
+# want.
+
+def null_complete(text, start):  # pragma: nocover
+    return None
+
+
+readline.set_completer(null_complete)
+
+
+def rlinput(prompt: str = "", default: str = "",
+            options: list = None):  # pragma: nocover
+    """
+    Get input with preset default and/or tab completion of options
+
+    Parameters:
+
+    prompt:str - string to output before requesting input, same as in the
+    input() function
+
+    default:str - value with which to prepopulate the response, can be cleared
+    with ctrl-a, ctrl-k
+
+    options:list - list of choices for tab completion
+    """
+
+    # Clean out the options
+    options = [o.strip() + " " for o in options] if options else []
+
+    # Create the completer using the options
+    def complete(text, state):
+        results = [x for x in options if x.startswith(text)] + [None]
+        return results[state]
+    readline.set_completer(complete)
+
+    # Insert the default when we launch
+    def start():
+        readline.insert_text(default)
+    readline.set_startup_hook(start)
+
+    # Actually perform the input
+    try:
+        value = input(prompt)
+    finally:
+        readline.set_startup_hook()
+        readline.set_completer(null_complete)
+    return value.strip()
+
+
+def tryit():  # pragma: nocover
+    """Quick and dirty tester function"""
+    return rlinput(prompt='>',
+                   options=['a-b', 'a-c', 'b-a'])
+
+
+if __name__ == '__main__':
+    tryit()

wizlib/super_wrapper.py

@@ -0,0 +1,8 @@
+
+class SuperWrapper:
+    @classmethod
+    def wrap(parent_class, method):
+        def wrapper(self, *args, **kwargs):
+            parent_method = getattr(parent_class, method.__name__)
+            return parent_method(self, method, *args, **kwargs)
+        return wrapper

wizlib-0.0.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.1
+Name: wizlib
+Version: 0.0.0
+Summary: Framework for flexible and powerful command-line applications
+License: MIT
+Author: Steampunk Wizard
+Author-email: wizlib@steampunkwizard.ca
+Requires-Python: >=3.11,<3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: PyYAML (>=6.0.1,<7.0.0)
+Requires-Dist: gnureadline (>=8.1.2,<9.0.0) ; sys_platform == "darwin"
+Requires-Dist: myst-parser (>=2.0.0,<3.0.0)
+Requires-Dist: pyreadline3 (>=3.4.1,<4.0.0) ; sys_platform == "win32"
+Description-Content-Type: text/markdown
+
+# WizLib
+
+Framework for flexible and powerful command-line applications
+
+## ClassFamily
+
+A class family is a set of class definitions that use single inheritance
+(each subclass inherits from only one parent) and often multiple inheritance
+(subclasses can inherit from subclasses). So it's a hierarchy of classes,
+with one super-parent (termed the "atriarch") at the top.
+
+We offer a way for members of the family to declare themselves simply by
+living in the right package location. Then those classes can be instantiated
+using keys or names, without having to be specifically called. The members
+act independently of each other.
+
+What we get, after importing everything and loading it all, is essentially a
+little database of classes, where class-level properties become keys for
+looking up member classes. So, for example, we can have a family of commands,
+and use a command string to look up the right command.
+
+Ultimately, the atriarch of the family -- the class at the top of the
+hierarchy -- holds the database, actually a list, in the property called
+"family". So that class can be queried to find appropriate family member
+classes or instances thereof.
+
+This utility provides functions for importing family members, loading the
+"families" property of the super-parent, and querying the family.
+
+In the process of loading and querying the class family, we need to *avoid*
+inheritance of attributes. There might be abstract intermediary classes that
+don't want to play. So we use `__dict__` to ensure we're only seeing the
+atttributes that are defined on that specific class.
+
+## SuperWrapper
+
+Provide a decorator to wrap a method so that it's called within the inherited
+version of that method.
+
+Example of use:
+
+```python
+class Parent(SuperWrapper):
+    def execute(self, method, *args, **kwargs):
+        print(f"Parent execute before")
+        method(self, *args, **kwargs)
+        print(f"Parent execute after")
+
+class InBetween(Parent):
+    @Parent.wrap
+    def execute(self, method, *args, **kwargs):
+        print(f"IB execute before")
+        method(self, *args, **kwargs)
+        print(f"IB execute after")
+
+class NewChild(InBetween):
+    @InBetween.wrap
+    def execute(self, name):
+        print(f"Hello {name}")
+
+c = NewChild()
+c.execute("Jane")
+```
+
+Note that for a method to be "wrappable" it must take the form shown above, and explicitly call the method that's handed into it. So strictly, this is different from regular inheritance, where the parent class method has the same signature as the child class method.
+
+## RLInput
+
+Python supports the GNU readline approach, which enables tab completion, key mappings, and history with the `input()` function. But the documentation is cryptic, and the implementation differs between Linux and MacOS. RLInput makes it easy.
+
+```python
+from wizlib.rlinput import rlinput
+```
+
+It's just a function, with up to three parameters:
+
+- `intro:str=""` - The intro or prompt, same as in the `input()` function.
+- `default:str=""` - If provided, the text will be inserted into the buffer at the start, with the cursor at the end of the buffer. So that becomes the default, that must be overridden by the user if they want different input.
+- `options:list=[]` - A list of options for tab completion. This assumes the options are choices for the entire entry; it's not context-dependent within the buffer.
+
+Emacs keys are enabled by default; I'm able to use the arrow keys on my Mac so you should too. I made one change to the keyboard mappings, which is the Ctrl-A, instead of just moving the cursor to the beginning of the line, wipes the entire buffer. So to wipe out the default value and type or tab something new, just hit Ctrl-A.
+
+
+## The WizApp framework
+
+_Docs in progress - might be out of date_
+
+Commands automatically handle input via stdin for non-tty inputs such as pipes. Some details:
+
+- The argument name is `input`
+- Therefore `input` is a reserved name for arguments
+- Optionally use the `--input` or `-i` command line argument to pass in the same information
+- Reading from stdin in tty cases (i.e. in the terminal) would still have to happen in the command itself.
+
+### ConfigHandler
+
+Enables easy configuration across multiple levels. Tries each of the following approaches in order until one finds the required config option
+
+- First look for attributes of the instance (subclass of ConfigHandler) itself (e.g. `gitlab_host`)
+- Then look for a specific env variable for that config setting in all caps, e.g. `GITLAB_HOST`
+- If those both fail, then look for a YAML configuration file:
+    - First identified with a `--config` / `-c` option on the command line
+    - Then with a path in the `APPNAME_CONFIG` environment variable - note all caps
+    - Then look in the local working directory for `.appname.yml`
+    - Then look for `~/.appname.yml` in the user's home directory
+
+Config files are in YAML, and look something like this:
+
+```yaml
+gitlab:
+  host: gitlab.com
+local:
+  root: $HOME/git
+```
+
+Note that nested labels in the config map to hyphenated command line options.
+
+
+---
+
+Logo by [Freepik](https://www.freepik.com/?_gl=1*1y9rvc9*test_ga*Mjc1MTIzODYxLjE2ODA3OTczNTg.*test_ga_523JXC6VL7*MTY4MDc5NzM1OC4xLjEuMTY4MDc5NzQxNS4zLjAuMA..*fp_ga*Mjc1MTIzODYxLjE2ODA3OTczNTg.*fp_ga_1ZY8468CQB*MTY4MDc5NzM1OC4xLjEuMTY4MDc5NzQxNS4zLjAuMA..)
+
+
+

wizlib-0.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+wizlib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wizlib/app.py,sha256=7emrVV077IXk7PGQeFz1jne0jpDCPyrJXrZfaf2Ya54,2822
+wizlib/class_family.py,sha256=EX1ZZmrmC2M-PV_iorHXCWqETE2thrwQE45RtHxojbs,4424
+wizlib/command.py,sha256=GQlXP8dOJHXUGDhjV3VYnOmHLtbEc4TMAGogLUqy2U8,1304
+wizlib/config_handler.py,sha256=alHpJzFY39XXDv94W4fLwda6hjruySADAJD944rE3HU,2639
+wizlib/error.py,sha256=ypwdMOYhtgKWd48ccfOX8idmCXmm-Skwx3gkPwqJB3c,46
+wizlib/handler.py,sha256=vUrlMIER019Sz17yeg95Cs6u9Vo5u24qf0q7p9HEWec,306
+wizlib/input_handler.py,sha256=RmoZA_FlQ_1qeDEV9YZSU8Zw933pMPEb4yOZLPUGnBA,597
+wizlib/parser.py,sha256=O34azN4ttVfwwAsza0hujxGxDpzc4xUEVAf26DXJS5g,1505
+wizlib/rlinput.py,sha256=l00Pa3rxNeY6LJgz8Aws_rTKoEchw33fuL8yqHF9_-o,1754
+wizlib/super_wrapper.py,sha256=F834ytHqA7zegTD1ezk_uxlF9PLygh84wReuiqcI7BI,272
+wizlib-0.0.0.dist-info/METADATA,sha256=Sz-Eh8FH_CgeAMbZ1FDNLUDHRrsrs-E5MfXT8RNOAog,5965
+wizlib-0.0.0.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+wizlib-0.0.0.dist-info/RECORD,,

wizlib-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.8.1
+Root-Is-Purelib: true
+Tag: py3-none-any