cli2 3.3.46__tar.gz → 4.0.0__tar.gz

cli2-4.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.2
+Name: cli2
+Version: 4.0.0
+Summary: image:: https://yourlabs.io/oss/cli2/badges/master/pipeline.svg
+Home-page: https://yourlabs.io/oss/cli2
+Author: James Pic
+Author-email: jamespic@gmail.com
+License: MIT
+Keywords: cli
+Requires-Python: >=3.6
+Description-Content-Type: text/x-rst
+Requires-Dist: docstring_parser
+Requires-Dist: pyyaml
+Requires-Dist: pygments
+Requires-Dist: structlog
+Provides-Extra: client
+Requires-Dist: httpx; extra == "client"
+Requires-Dist: truststore; extra == "client"
+Provides-Extra: test
+Requires-Dist: freezegun; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-httpx; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+.. image:: https://yourlabs.io/oss/cli2/badges/master/pipeline.svg
+   :target: https://yourlabs.io/oss/cli2/pipelines
+.. image:: https://codecov.io/gh/yourlabs/cli2/branch/master/graph/badge.svg
+  :target: https://codecov.io/gh/yourlabs/cli2
+.. image:: https://img.shields.io/pypi/v/cli2.svg
+   :target: https://pypi.python.org/pypi/cli2
+
+cli2: Python Automation Framework
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A Python command line and Ansible Action plugin framework that loves meta
+programming: do less and get more out of it, perfect for many kinds of DevOps
+gigs to automate everything.
+
+Batteries included, all of which are useful on their own:
+
+- beautiful CLI alternative to click, but much less verbose, allowing more
+  creative design patterns without any boilerplate thanks to introspection
+- which comes with a Sphinx extension to extensively document your CLIs
+- magic 12-factor configuration library
+- extremely beautiful structlog configuration for colorful and readable logging
+- httpx client wrapper that handles all kind of retries, data masking...
+- magic ORM for HTTP resources based on that client
+- Ansible Action plugin library with all the beautiful logging and a rich
+  testing library so that you can go straight to the point in pytest
+- a good old fcntl based locking
+- a command line to run any python function over a beautiful CLI
+
+`Documentation available on RTFD <https://cli2.rtfd.io>`_.

cli2-4.0.0/README.rst

@@ -0,0 +1,29 @@
+.. image:: https://yourlabs.io/oss/cli2/badges/master/pipeline.svg
+   :target: https://yourlabs.io/oss/cli2/pipelines
+.. image:: https://codecov.io/gh/yourlabs/cli2/branch/master/graph/badge.svg
+  :target: https://codecov.io/gh/yourlabs/cli2
+.. image:: https://img.shields.io/pypi/v/cli2.svg
+   :target: https://pypi.python.org/pypi/cli2
+
+cli2: Python Automation Framework
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A Python command line and Ansible Action plugin framework that loves meta
+programming: do less and get more out of it, perfect for many kinds of DevOps
+gigs to automate everything.
+
+Batteries included, all of which are useful on their own:
+
+- beautiful CLI alternative to click, but much less verbose, allowing more
+  creative design patterns without any boilerplate thanks to introspection
+- which comes with a Sphinx extension to extensively document your CLIs
+- magic 12-factor configuration library
+- extremely beautiful structlog configuration for colorful and readable logging
+- httpx client wrapper that handles all kind of retries, data masking...
+- magic ORM for HTTP resources based on that client
+- Ansible Action plugin library with all the beautiful logging and a rich
+  testing library so that you can go straight to the point in pytest
+- a good old fcntl based locking
+- a command line to run any python function over a beautiful CLI
+
+`Documentation available on RTFD <https://cli2.rtfd.io>`_.

cli2-4.0.0/cli2/__init__.py

@@ -0,0 +1,42 @@
+# flake8: noqa
+from .cli import (
+    cmd,
+    arg,
+    hide,
+    retrieve,
+    Argument,
+    Command,
+    Group,
+    EntryPoint,
+)
+from .asyncio import async_resolve
+from .colors import colors as c
+
+from .configuration import Configuration, cfg
+try:
+    from .client import (
+        ClientError,
+        ResponseError,
+        TokenGetError,
+        RefusedResponseError,
+        RetriesExceededError,
+        FieldError,
+        FieldValueError,
+        FieldExternalizeError,
+        Client,
+        DateTimeField,
+        Field,
+        Handler,
+        JSONStringField,
+        Model,
+        Paginator,
+        Related,
+    )
+except ImportError:
+    raise
+    # httpx not installed
+    pass
+from .display import diff, diff_data, render, print, highlight
+from .lock import Lock
+from .log import configure, log, get_logger
+from .table import Table

cli2-4.0.0/cli2/ansible/__init__.py

@@ -0,0 +1,8 @@
+# flake8: noqa
+from .action import (
+    ansi_escape,
+    Option,
+    AnsibleError,
+    AnsibleOptionError,
+    ActionBase,
+)

cli2-4.0.0/cli2/ansible/action.py

@@ -0,0 +1,291 @@
+"""
+Experimental: my base class for Ansible actions.
+"""
+
+import asyncio
+import cli2
+import copy
+import mock
+import os
+import re
+import traceback
+
+from ansible.plugins.action import ActionBase
+
+# colors:
+# black
+# bright gray
+# blue
+# white
+# green
+# cyan
+# bright green
+# red
+# bright cyan
+# purple
+# bright red
+# yellow
+# bright purple
+# dark gray
+# magenta
+# bright magenta
+# normal
+
+# 7-bit C1 ANSI sequences
+ansi_escape = re.compile(r'''
+    \x1B  # ESC
+    (?:   # 7-bit C1 Fe (except CSI)
+        [@-Z\\-_]
+    |     # or [ for CSI, followed by a control sequence
+        \[
+        [0-?]*  # Parameter bytes
+        [ -/]*  # Intermediate bytes
+        [@-~]   # Final byte
+    )
+''', re.VERBOSE)
+
+
+UNSET_DEFAULT = '__UNSET__DEFAULT__'
+
+
+class Option:
+    """
+    Ansible Option descriptor.
+
+    .. py:attribute:: arg
+
+        Name of the task argument to get this option value from
+
+    .. py:attribute:: fact
+
+        Name of the fact, if any, to get a value for this option if no task arg
+        is provided
+
+    .. py:attribute:: default
+
+        Default value, if any, in case neither of arg and fact were defined.
+    """
+    UNSET_DEFAULT = UNSET_DEFAULT
+
+    def __init__(self, arg=None, fact=None, default=UNSET_DEFAULT):
+        self.arg = arg
+        self.fact = fact
+        self.default = default
+
+    @property
+    def kwargs(self):
+        kwargs = dict(default=self.default)
+        if self.arg:
+            kwargs['arg_name'] = self.arg
+        if self.fact:
+            kwargs['fact_name'] = self.fact
+        return kwargs
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            return self
+        try:
+            return obj.get(**self.kwargs)
+        except AttributeError:
+            raise AnsibleOptionError(self)
+
+
+class AnsibleError(Exception):
+    pass
+
+
+class AnsibleOptionError(AnsibleError):
+    def __init__(self, option):
+        self.option = option
+        super().__init__(option.kwargs)
+
+    @property
+    def message(self):
+        message = ['Missing']
+        if self.option.arg:
+            message.append(f'arg `{self.option.arg}`')
+            if self.option.fact:
+                message.append('or')
+        if self.option.fact:
+            message.append(f'fact `{self.option.fact}`')
+        return ' '.join(message)
+
+
+class ActionBase(ActionBase):
+    """
+    Base action class
+
+    .. py:attribute:: result
+
+        Result dict that will be returned to Ansible
+
+    .. py:attribute:: task_vars
+
+        The task_vars that the module was called with
+
+    .. py:attribute:: client
+
+        The client object generated by :py:meth:`client_factory` if you
+        implement it.
+    """
+    def get(self, arg_name, fact_name=None, default=UNSET_DEFAULT):
+        if arg_name in self._task.args:
+            return self._task.args[arg_name]
+        if fact_name and fact_name in self.task_vars:
+            return self.task_vars[fact_name]
+        if default != UNSET_DEFAULT:
+            return default
+        if fact_name:
+            raise AttributeError(f'Undefined {arg_name} or {fact_name}')
+        else:
+            raise AttributeError(f'Undefined arg {arg_name}')
+
+    def run(self, tmp=None, task_vars=None):
+        self.tmp = tmp
+        self.task_vars = task_vars
+        self.result = super().run(tmp, task_vars)
+        asyncio.run(self.run_wrapped_async())
+        return self.result
+
+    async def run_wrapped_async(self):
+        self.verbosity = self.task_vars.get('ansible_verbosity', 0)
+
+        if 'LOG_LEVEL' not in os.environ and 'DEBUG' not in os.environ:
+            if self.verbosity == 1:
+                os.environ['LOG_LEVEL'] = 'INFO'
+            elif self.verbosity >= 2:
+                os.environ['LOG_LEVEL'] = 'DEBUG'
+            cli2.configure()
+
+        try:
+            try:
+                self.client = await self.client_factory()
+            except NotImplementedError:
+                self.client = None
+            await self.run_async()
+        except Exception as exc:
+            self.result['failed'] = True
+
+            if isinstance(exc, AnsibleError):
+                self.result['error'] = exc.message
+            elif isinstance(exc, cli2.ResponseError):
+                self.result.update(dict(
+                    method=exc.method,
+                    url=exc.url,
+                    status_code=exc.status_code,
+                ))
+                key, value = self.client.response_log_data(exc.response)
+                if key:
+                    self.result[f'response_{key}'] = value
+                key, value = self.client.request_log_data(exc.request)
+                if key:
+                    self.result[f'request_{key}'] = value
+            elif self.verbosity:
+                traceback.print_exc()
+
+            # for pytest to raise
+            self.exc = exc
+        finally:
+            if (
+                self._before_data != UNSET_DEFAULT
+                and self._after_data != UNSET_DEFAULT
+            ):
+                diff = cli2.diff_data(
+                    self._before_data,
+                    self._after_data,
+                    self._before_label,
+                    self._after_label,
+                )
+                if self.client and self.client.mask:
+                    output = '\n'.join([
+                        line.rstrip() for line in diff if line.strip()
+                    ])
+                    output = re.sub(
+                        f'({"|".join(self.client.mask)}): (.*)',
+                        '\\1: ***MASKED***',
+                        ''.join(output),
+                    )
+                    print(cli2.highlight(output, 'Diff'))
+                else:
+                    cli2.diff(diff)
+
+    async def run_async(self):
+        """
+        The method you are supposed to implement.
+
+        It should:
+
+        - provision the :py:attr:`result` dict
+        - find task_vars in :py:attr:`task_vars`
+        """
+
+    async def client_factory(self):
+        """
+        Return a client instance.
+
+        :raise NotImplementedError: By default
+        """
+        raise NotImplementedError()
+
+    @classmethod
+    async def run_test_async(cls, args=None, facts=None, client=None,
+                             fail=False):
+        """
+        Test run the module in a mocked context.
+
+        :param args: Dict of task arguments
+        :param facts: Dict of play facts
+        :param client: Client instance, overrides the factory
+        :param fail: Allow this test to fail without exception
+        """
+        obj = cls(*[mock.Mock()] * 6)
+        obj.tmp = None
+        obj.task_vars = mock.Mock()
+        obj.result = dict()
+        obj._task = mock.Mock()
+        obj._task.args = args or {}
+        obj.task_vars = facts or {}
+        obj.task_vars['ansible_verbosity'] = 1
+        obj.exc = False
+        if client:
+            async def _factory():
+                return client
+            obj.client_factory = _factory
+        old = obj.client_factory
+
+        async def set_tries():
+            client = await old()
+            client.handler.tries = 0
+            return client
+        obj.client_factory = set_tries
+        await obj.run_wrapped_async()
+        if obj.exc and not fail:
+            raise obj.exc
+        if obj.result.get('failed', False) and not fail:
+            raise Exception('Module failed, and fail is not True {obj.result}')
+        return obj
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._before_data = UNSET_DEFAULT
+        self._after_data = UNSET_DEFAULT
+
+    def before_set(self, data, label='before'):
+        """
+        Set the data we're going to display the diff for at the end.
+
+        :param data: Dictionnary of data
+        :param label: Label to show in diff
+        """
+        self._before_data = copy.deepcopy(data)
+        self._before_label = label
+
+    def after_set(self, data, label='after'):
+        """
+        Set the data we're going to display the diff for at the end.
+
+        :param data: Dictionnary of data
+        :param label: Label to show in diff
+        """
+        self._after_data = copy.deepcopy(data)
+        self._after_label = label

cli2-4.0.0/cli2/ansible/playbook.py

@@ -0,0 +1,215 @@
+import copy
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import yaml
+
+from cli2.ansible import ansi_escape
+
+
+def which_ansible_playbook():
+    PATH = os.environ.get('PATH', os.defpath)
+    local = os.path.join(os.environ.get('HOME', '~'), '.local/bin')
+    if local not in PATH:
+        PATH = ':'.join([local, PATH])
+    path = shutil.which('ansible-playbook', path=PATH)
+    if not path:
+        raise Exception('No ansible-playbook command in $PATH=' + PATH)
+    return path
+
+
+def check_ansible_output_for_exception(exception):
+    # if you read this, it means a Python exception was throw during Ansible
+    # execution, this must not happen for tests to pass
+    assert not exception, 'Exception detected in ansible output'
+
+
+def ansible_playbook(*args):
+    cmd = [
+        which_ansible_playbook(),
+        '-c',
+        'local',
+        '-vvv',
+        '--become',
+        *args,
+    ]
+
+    try:
+        readable = {shlex.join(cmd)}
+    except AttributeError:  # old python
+        readable = ' '.join([shlex.quote(arg) for arg in cmd])
+    print(f'Running:\n{readable}')
+
+    data = dict(
+        ok=0,
+        changed=0,
+        unreachable=0,
+        failed=0,
+        skipped=0,
+        rescued=0,
+        ignored=0,
+        exception=False,
+    )
+
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+
+    lines = []
+    for line in iter(proc.stdout.readline, b''):
+        line = line.decode()
+        if 'Traceback (most recent call last)' in line:
+            data['exception'] = True
+        sys.stdout.write(line)
+        if not line.strip():
+            continue
+        lines.append(ansi_escape.sub('', line))
+
+    for line in reversed(lines):
+        if line.startswith('PLAY RECAP'):
+            break
+        try:
+            for item in re.findall('([a-z]+)=([0-9]*)', line):
+                data[item[0]] += int(item[1])
+        except (IndexError, KeyError):
+            return dict(success=False)
+
+    data['stdout'] = '\n'.join(lines)
+
+    data['success'] = (
+        data['ok']
+        and not (data['failed'] or data['unreachable'])
+    )
+    return data
+
+
+class Playbook:
+    """
+    On-the-fly playbook generator
+
+    .. py:attribute:: root
+
+        This would be a tmp_path returned by pytest
+
+    .. py:attribute:: name
+
+        Name of the playbook, test name by default
+
+    .. py:attribute:: vars
+
+        Playbook vars
+
+    .. py:attribute:: roles
+
+        Playbook roles, use :py:meth:`role_add` to add a role
+
+    .. py:attribute:: tasks
+
+        Playbook tasks, use :py:meth:`task_add` to add a task
+
+    .. py:attribute:: play
+
+        Main playbook play
+
+    .. py:attribute:: plays
+
+        Playbook plays, contains the main one by default
+
+    .. py:attribute:: yaml
+
+        Property that returns the generated yaml
+    """
+
+    def __init__(self, root, name):
+        self.root = root
+        self.name = name
+        self.vars = dict()
+        self.roles = []
+        self.tasks = []
+        self.play = dict(
+            hosts='localhost',
+            vars=self.vars,
+            roles=self.roles,
+            tasks=self.tasks,
+        )
+        self.plays = [self.play]
+
+    def role_add(self, name, *tasks, **variables):
+        """
+        Create a new role with given tasks, include it with given variables
+
+        :param name: role name
+        :param tasks: List of task dicts
+        :param variables: Variables that will be passed to include_role
+        """
+        self.roles.append(dict(
+            role=str(self.root / name),
+            tasks=tasks,
+            **variables,
+        ))
+
+    def task_add(self, module, args=None, **kwargs):
+        """
+        Add a module call
+
+        :param module: Name of the Ansible module
+        :param args: Ansible module args
+        :param kwargs: Task kwargs (register, etc)
+        """
+        task = {module: args if args else None}
+        task.update(kwargs)
+        self.tasks.append(task)
+
+    @property
+    def file_path(self):
+        return self.root / f'{self.name}.yml'
+
+    def yaml_dump(self, value):
+        try:
+            return yaml.dump(value, width=1000, sort_keys=False)
+        except TypeError:  # python36
+            return yaml.dump(value, width=1000)
+
+    @property
+    def yaml(self):
+        plays = copy.deepcopy(self.plays)
+        for play in plays:
+            for role in play.get('roles', []):
+                if 'tasks' not in role:
+                    # actual role to include
+                    continue
+                # create role on the fly
+                tasks = role.pop('tasks')
+                role_path = self.root / role['role']
+                tasks_path = role_path / 'tasks'
+                if not tasks_path.exists():
+                    tasks_path.mkdir(parents=True)
+                with (tasks_path / 'main.yml').open('w+') as f:
+                    f.write(self.yaml_dump(list(tasks)))
+        return self.yaml_dump(plays)
+
+    def write(self):
+        with open(self.file_path, 'w+') as f:
+            f.write(self.yaml)
+
+    def __call__(self, *args, fails=False, exception=False):
+        """
+        Actually execute the playbook
+
+        :param args: Any extra ansible args
+        :param fails: Playbook failure is not accepted by default, set this to
+                      True to allow a playbook to fail.
+        :param exception: Exception during playbook run is not accepted by
+                          default, set this to True to allow an exception to
+                          pop in the playbook.
+        """
+        os.environ['ANSIBLE_STDOUT_CALLBACK'] = 'yaml'
+        os.environ['ANSIBLE_FORCE_COLOR'] = '1'
+        if not self.file_path.exists():
+            self.write()
+        result = ansible_playbook(*list(args) + [str(self.file_path)])
+        assert result['success'] if not fails else not result['success']
+        if not exception:
+            check_ansible_output_for_exception(result['exception'])
+        return result

cli2-4.0.0/cli2/ansible/pytest.py

@@ -0,0 +1,7 @@
+import pytest
+from .playbook import Playbook
+
+
+@pytest.fixture
+def playbook(tmp_path, request):
+    return Playbook(tmp_path, name=request.node.originalname)