Use specs just to validate path before call (if validation enabled)

Change way specs are managed (remove specs models)
Reorganize help management and improve formatter

Author: Francesco Faraone

cnct/client/fluent.py

@@ -7,9 +7,8 @@
 from cnct.client.exceptions import ClientError
 from cnct.client.models import Collection, NS
 from cnct.client.utils import get_headers
-# from cnct.help import DefaultFormatter
-from cnct.openapi import OpenAPISpecs
-# from cnct.specs.parser import parse
+from cnct.client.help_formatter import DefaultFormatter
+from cnct.client.openapi import OpenAPISpecs
 
 
 class ConnectClient:
@@ -22,7 +21,7 @@ def __init__(
         endpoint=None,
         use_specs=True,
         specs_location=None,
-        validate_calls=True,
+        validate_using_specs=True,
         default_headers=None,
         default_limit=100,
     ):
@@ -45,13 +44,13 @@ def __init__(
         self.api_key = api_key
         self.default_headers = default_headers or {}
         self._use_specs = use_specs
-        self._validate_calls = validate_calls
+        self._validate_using_specs = validate_using_specs
         self.specs_location = specs_location or CONNECT_SPECS_URL
         self.specs = None
         if self._use_specs:
             self.specs = OpenAPISpecs(self.specs_location)
         self.response = None
-        # self._help_formatter = help_formatter
+        self._help_formatter = DefaultFormatter(self.specs)
 
     def __getattr__(self, name):
         """
@@ -131,7 +130,7 @@ def delete(self, url, **kwargs):
     def execute(self, method, path, **kwargs):
         if (
             self._use_specs
-            and self._validate_calls
+            and self._validate_using_specs
             and not self.specs.exists(method, path)
         ):
             # TODO more info, specs version, method etc
@@ -164,8 +163,12 @@ def execute(self, method, path, **kwargs):
             status_code = self.response.status_code if self.response is not None else None
             raise ClientError(status_code=status_code, **api_error) from re
 
+    def print_help(self, obj):
+        print()
+        print(self._help_formatter.format(obj))
+
     def help(self):
-        self._help_formatter.print_help(self.specs)
+        self.print_help(None)
         return self
 
     def _execute_http_call(self, method, url, kwargs):

cnct/client/help_formatter.py

@@ -0,0 +1,199 @@
+import inflect
+
+from cmr import render
+from cnct.client.models import Action, Collection, NS, Resource, ResourceSet
+
+
+_COL_HTTP_METHOD_TO_METHOD = {
+    'get': '.all(), .filter(), .first(), .last()',
+    'post': '.create()',
+}
+
+
+class DefaultFormatter:
+
+    def __init__(self, specs):
+        self._specs = specs
+        self._p = inflect.engine()
+
+    def format_client(self):
+        lines = [
+            f'# Welcome to {self._specs.title} {self._specs.version}',
+            '## Introduction'
+        ] + self._specs.description.splitlines()
+
+        lines += [
+            '',
+            '## Namespaces'
+        ]
+        for ns in self._specs.get_namespaces():
+            lines.append(f'* {ns}')
+
+        lines += [
+            '',
+            '## Collections'
+        ]
+        for col in self._specs.get_collections():
+            lines.append(f'* {col}')
+
+        return render('\n'.join(lines))
+
+    def format_ns(self, ns):
+        collections = self._specs.get_namespaced_collections(ns.path)
+        if not collections:
+            return render(f'~~{ns.path}~~ **does not exists.**')
+
+        lines = [
+            f'# {ns.path.title()} namespace',
+            f'**path: /{ns.path}**',
+            '## Available collections',
+        ]
+
+        for collection in collections:
+            lines.append(f'* {collection}')
+
+        return render('\n'.join(lines))
+
+    def format_collection(self, collection):
+        col_info = self._specs.get_collection(collection.path)
+        if not col_info:
+            return render(f'~~{collection.path}~~ **does not exists.**')
+
+        if '/' in collection.path:
+            _, collection_name = collection.path.rsplit('/', 1)
+        else:
+            collection_name = collection.path
+
+        lines = [
+            f'# {collection_name.title()} collection',
+            f'**path: /{collection.path}**',
+        ]
+
+        lines.extend(self._format_heading(col_info))
+        lines.append('### Available operations')
+        if 'get' in col_info:
+            lines.append(f'* GET: {_COL_HTTP_METHOD_TO_METHOD["get"]}')
+
+        if 'post' in col_info:
+            lines.append(f'* POST: {_COL_HTTP_METHOD_TO_METHOD["post"]}')
+
+        return render('\n'.join(lines))
+
+    def format_resource(self, resource):
+        res_info = self._specs.get_resource(resource.path)
+        if not res_info:
+            return render(f'~~{resource.path}~~ **does not exists.**')
+
+        resource_name = resource.path.split('/')[-2]
+        resource_name = self._p.singular_noun(resource_name)
+        lines = [
+            f'# {resource_name.title()} resource',
+            f'**path: /{resource.path}**',
+        ]
+
+        lines.extend(self._format_heading(res_info))
+
+        actions = self._specs.get_actions(resource.path)
+        if actions:
+            lines.append('### Available actions')
+            for name, summary in actions:
+                if summary:
+                    lines.append(f'* {name} - {summary}')
+                else:
+                    lines.append(f'* {name}')
+            lines.append('')
+
+        nested = self._specs.get_nested_collections(resource.path)
+        if nested:
+            lines.append('### Available nested collections')
+            for name, summary in nested:
+                if summary:
+                    lines.append(f'* {name} - {summary}')
+                else:
+                    lines.append(f'* {name}')
+
+        return render('\n'.join(lines))
+
+    def format_action(self, action):
+        action_info = self._specs.get_action(action.path)
+        if not action_info:
+            return render(f'~~{action.path}~~ **does not exists.**')
+
+        _, action_name = action.path.rsplit('/', 1)
+
+        lines = [
+            f'# {action_name.title()} action',
+            f'**path: /{action.path}**',
+        ]
+        lines.extend(self._format_heading(action_info))
+        lines.append('## Available methods')
+        for method in ('get', 'post', 'put', 'delete'):
+            if method in action_info:
+                lines.append(f'* {method.upper()}: .{method}()')
+
+        return render('\n'.join(lines))
+
+    def format_resource_set(self, rs):
+        col_info = self._specs.get_collection(rs.path)
+        if not col_info:
+            return render(f'~~{rs.path}~~ **does not exists.**')
+
+        if '/' in rs.path:
+            _, collection_name = rs.path.rsplit('/', 1)
+        else:
+            collection_name = rs.path
+
+        lines = [
+            f'# Search the {collection_name.title()} collection',
+            f'**path: /{rs.path}**',
+        ]
+        lines.extend(self._format_heading(col_info))
+        get_info = col_info['get']
+        params = get_info.get('parameters')
+        if not params:
+            return render('\n'.join(lines))
+        filters = list(sorted(filter(lambda x: '$ref' not in x, params), key=lambda x: x['name']))
+        lines.append(f'Support pagination: *{len(params) > len(filters)}*')
+        if not filters:
+            return render('\n'.join(lines))
+
+        lines.append('## Available filters')
+        for filter_ in filters:
+            lines.append(f'*{filter_["name"]}*')
+            description = filter_['description'].splitlines()
+            for line in description:
+                line = line.strip()
+                if line:
+                    lines.append(f'   {line}')
+            lines.append('')
+
+        return render('\n'.join(lines))
+
+    def format(self, obj):
+        if not self._specs:
+            return render('**No OpenAPI specs available.**')
+
+        if isinstance(obj, NS):
+            return self.format_ns(obj)
+
+        if isinstance(obj, Collection):
+            return self.format_collection(obj)
+
+        if isinstance(obj, Resource):
+            return self.format_resource(obj)
+
+        if isinstance(obj, Action):
+            return self.format_action(obj)
+
+        if isinstance(obj, ResourceSet):
+            return self.format_resource_set(obj)
+
+        return self.format_client()
+
+    def _format_heading(self, info):
+        lines = []
+        for section in ('summary', 'description'):
+            if section in info:
+                lines.append(f'### {section.title()}')
+                lines.append(info[section])
+        return lines

cnct/client/models/base.py

@@ -1,3 +1,4 @@
+from cnct.client.exceptions import ClientError
 from cnct.client.models.resourceset import ResourceSet
 from cnct.client.utils import resolve_attribute
 from cnct.rql import R
@@ -69,7 +70,7 @@ def help(self):
         :return: self
         :rtype: NS
         """
-        # self._client._help_formatter.print_help(self._specs)
+        self._client.print_help(self)
         return self
 
 
@@ -220,7 +221,7 @@ def help(self):
         :return: self
         :rtype: Collection
         """
-        # self._client._help_formatter.print_help(self._specs)
+        self._client.print_help(self)
         return self
 
 
@@ -306,6 +307,15 @@ def action(self, name):
             f'{self._path}/{name}',
         )
 
+    def exists(self):
+        try:
+            self.get()
+            return True
+        except ClientError as ce:
+            if ce.status_code and ce.status_code == 404:
+                return False
+            raise
+
     def get(self, **kwargs):
         """
         Execute a http GET to retrieve this resource.
@@ -375,7 +385,7 @@ def help(self):
         :return: self
         :rtype: Resource
         """
-        # self._client._help_formatter.print_help(self._specs)
+        self._client.print_help(self)
         return self
 
 
@@ -430,7 +440,6 @@ def post(self, payload=None, **kwargs):
         return self._client.execute(
             'post',
             self._path,
-            200,
             **kwargs,
         )
 
@@ -451,7 +460,6 @@ def put(self, payload=None, **kwargs):
         return self._client.execute(
             'put',
             self._path,
-            200,
             **kwargs,
         )
 
@@ -474,5 +482,5 @@ def help(self):
         :return: self
         :rtype: Action
         """
-        # self._client._help_formatter.print_help(self._specs)
+        self._client.print_help(self)
         return self

cnct/client/models/resourceset.py

@@ -428,5 +428,5 @@ def help(self):
         :return: self
         :rtype: ResourceSet
         """
-        # self._client._help_formatter.print_help(self._specs)
+        self._client.print_help(self)
         return self