Fix/added tests improvements and documentation (#2)

* fix: Modified coverage

* feat: Generated doc strings

* feat: Updated README.md

* fix: Fixed order of arguments in methods

Author: micmurawski

README.md

@@ -37,4 +37,34 @@ auth_backend = AuthSession(
 storage_client = OSDUAPI.client('storage', auth_backend=auth_backend)
 response = storage_client.get_record_versions(id="123")
 
-```
+```
+# Available services
+
+```python
+from osdu_client.client import OSDUAPI
+OSDUAPI.print_available_services()
+```
+
+```bash
+|      Name      |    Versions    |
+===================================
+|    dataset     |     latest     |
+|  entitlements  |     latest     |
+|      file      |     latest     |
+|    indexer     |     latest     |
+|     legal      |     latest     |
+|  notification  |     latest     |
+|   partition    |     latest     |
+|     policy     |     latest     |
+|      pws       |     latest     |
+|      rafs      |     v1, v2     |
+|    register    |     latest     |
+|     schema     |     latest     |
+|      sdms      |     latest     |
+|     search     |     latest     |
+|     secret     |     latest     |
+|    storage     |     latest     |
+|    wellbore    |     v2, v3     |
+|  welldelivery  |     latest     |
+```
+

gen/client_generator.py

@@ -68,7 +68,6 @@ def get_type_for_param(param: dict, swagger: dict | None = None) -> str:
     all_of = get_path(param, "allOf.0.$ref", None)
     any_of = get_path(param, "anyOf", None)
 
-    
     if any_of:
         types = []
         _list = any_of
@@ -86,6 +85,8 @@ def get_type_for_param(param: dict, swagger: dict | None = None) -> str:
             types.append(
                 COMPLEX_TYPES_MAP[(_type, items_type)]
             )
+        if len(types) == 1:
+            return types[0]
         return "Union[%s]" % ", ".join(types)
 
     while ref_path or all_of:
@@ -171,8 +172,8 @@ def create_headers_block(required_header_params_without_special, optional_header
         "headers = self.auth.get_headers()",
         "if data_partition_id:",
         f"{INDENT}headers['data-partition-id'] = data_partition_id",
-        #"if tenant:",
-        #f"{INDENT}headers['tenant'] = tenant"
+        # "if tenant:",
+        # f"{INDENT}headers['tenant'] = tenant"
     ]
     if required_header_params_without_special:
         lines.append(
@@ -326,12 +327,8 @@ def get_name_from_name_map(method: str, path: str, method_names_file: str):
 
 
 def create_method_name(method: str, path: str, name_parts: list[str], swagger: dict, method_names_file: str) -> str:
-    # try:
     summary = swagger["paths"][path][method].get("summary")
     description = swagger["paths"][path][method].get("description", "")
-    # except TypeError as e:
-    #    print(name_parts, path)
-    #    raise e
     name = get_name_from_name_map(method, path, method_names_file)
 
     if name:
@@ -447,7 +444,7 @@ def create_validation_block(path: str, method: str, swagger: dict, name: str) ->
         model_class = schema_path.rsplit("/", 1)[-1]
         lines = [
             "if self.validation:",
-            "%svalidate_data(request_data, %s, %sAPIError)" % (INDENT, model_class, name),
+            "%svalidate_data(request_data, %s)" % (INDENT, model_class),
         ]
         return "\n".join(lines)
     return ""
@@ -493,7 +490,7 @@ def create_method(swagger: dict, name: str, method: str, path: str, path_templat
 
     body_required, body_not_required = get_body_params(swagger, params, request_body)
 
-    sig = create_method_sig(swagger, name, params, body_required, body_not_required) + "\n"
+    sig = create_method_sig(swagger, name, params, body_required, body_not_required, method, path) + "\n"
 
     body = create_method_body(path, method, params, body_required,
                               body_not_required, path_template, class_name, swagger)
@@ -513,33 +510,77 @@ def parse_request_body(swagger: dict, props: list[dict]) -> list[str]:
     return result
 
 
-def create_method_sig(swagger: dict, name: str, params: list[str], body_required: list[str], body_not_required: list[str]) -> str:
+def generate_doc_string(name, path_params, body_required, body_not_required, swagger, method, path, indent_offset: int = 1):
+    description = swagger['paths'][path][method].get("description", "")
+    description = re.sub('<[^<]+>', "", description)
+    lines_1 = [
+        (INDENT*(indent_offset))+'"""',
+        (INDENT*(indent_offset))+description,
+        (INDENT*(indent_offset))+"Args:",
+        (INDENT*(indent_offset+1))+"data_partition_id (str): identifier of the data partition to query. If None sets by auth session.",
+    ]
+    for path_param in path_params:
+        name = convert_to_snake_case(path_param["name"])
+        _type = get_type_for_param(path_param, swagger)
+        lines_1.append(
+            (INDENT*(indent_offset+1)) + f"{name} ({_type}): {path_param.get('description', '')}"
+        )
+
+    for param in body_required:
+        name = convert_to_snake_case(param["name"])
+        _type = get_type_for_param(param, swagger)
+        lines_1.append(
+            (INDENT*(indent_offset+1)) + f"{name} ({_type}): {param.get('description', '')}"
+        )
+
+    for param in body_not_required:
+        name = convert_to_snake_case(param["name"])
+        _type = get_type_for_param(param, swagger)
+        lines_1.append(
+            (INDENT*(indent_offset+1)) + f"{name} ({_type}): {param.get('description', '')}"
+        )
+
+    lines_2 = [
+        (INDENT*(indent_offset))+"Returns:",
+        (INDENT*(indent_offset+1))+"response data (dict)",
+        (INDENT*(indent_offset))+"Raises:",
+        (INDENT*(indent_offset+1))+"OSDUValidation: if request values are wrong.",
+        (INDENT*(indent_offset+1))+"OSDUAPIError: if response is 4XX or 5XX",
+        (INDENT*(indent_offset))+'"""'
+    ]
+    result = "\n".join(lines_1 + lines_2)
+    return result
+
+
+def create_method_sig(swagger: dict, name: str, params: list[str], body_required: list[str], body_not_required: list[str], method: str, path: str) -> str:
     path_params = [
         p for p in params if p['name'] not in SPECIAL_HEADERS and p["in"] != "body"
     ]
     elements = [name, ]
     sig = ""
-    _input_parameters_strings = []
+    _input_parameters_strings = [param_to_function_argument(p)
+                                 for p in path_params]
 
     if body_required:
         _input_parameters_strings += parse_request_body(swagger, body_required)
+
     if body_not_required:
         _input_parameters_strings += parse_request_body(swagger, body_not_required)
-    
-    _input_parameters_strings += [param_to_function_argument(p) for p in sorted(path_params, key=lambda x: 0 if x.get("required") else 1)]
-    
+
     if _input_parameters_strings:
         sig += ", ".join(_input_parameters_strings)
 
     if sig:
         elements.append(sig)
 
+    doc = generate_doc_string(name, path_params, body_required, body_not_required,
+                              swagger, method, path, indent_offset=1)
     try:
         if len(elements) > 1:
             sig = "def %s(self, *, %s, data_partition_id: str | None = None) -> dict:" % tuple(elements)
         else:
             sig = "def %s(self, data_partition_id: str | None = None) -> dict:" % tuple(elements)
-        return sig
+        return sig + "\n" + doc
     except Exception as e:
         raise Exception(elements, len(elements)) from e
 

gen/helpers.py

@@ -1,7 +1,7 @@
 import json
 import os
-import sys
 import re
+import sys
 from subprocess import PIPE, Popen
 from typing import Any
 

gen/requirements.txt

@@ -3,3 +3,4 @@ ruff
 datamodel-code-generator
 PyYAML
 pydantic
+lxml

gen/run_generation.py

@@ -9,8 +9,8 @@
 WORKDIR = os.getcwd()
 
 SERVICES = {
-    "Entitlements": "https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/raw/master/docs/api/entitlements_openapi.yaml?ref_type=heads",
     "SDMS": "https://community.opengroup.org/osdu/platform/domain-data-mgmt-services/seismic/seismic-dms-suite/seismic-store-service/-/raw/master/app/sdms/docs/api/openapi.osdu.yaml?ref_type=heads",
+    "Entitlements": "https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/raw/master/docs/api/entitlements_openapi.yaml?ref_type=heads",
     "Storage": "https://community.opengroup.org/osdu/platform/system/storage/-/raw/master/docs/api/storage_openapi.yaml?ref_type=heads",
     "Search": "https://community.opengroup.org/osdu/platform/system/search-service/-/raw/master/docs/api/search_openapi.yaml?ref_type=heads",
     "Indexer": "https://community.opengroup.org/osdu/platform/system/indexer-service/-/raw/master/docs/api/indexer_openapi.yaml?ref_type=heads",
@@ -65,7 +65,7 @@ def remove_path_if_empty(path: str):
                 swagger_path,
                 models_path+".py",
             )
-        if not os.path.exists(os.path.join(module_path, "client.py")):
+        if not os.path.exists(os.path.join(module_path, "client.py")) or True:
             generate_clients(
                 swagger_path,
                 name,

osdu_client/client.py

@@ -39,8 +39,48 @@ def get_service_client(name: str, version: str | None = None) -> type[OSDUAPICli
 class OSDUAPI:
     @staticmethod
     def client(service_name, auth_backend: AuthBackendInterface, version: str | None = None, validation: bool = True) -> OSDUAPIClient:
+        """Creates client instance for given service.
+            Args:
+                service_name (str): The OSDU API service name, to check available services call list_available_services method.
+                auth_backend (AuthBackendInterface): class object that implements AuthBackendInterface and stores all auth headers.
+                version (str): Version of the service API client. If None method will produce the latest client.
+                validation (bool): Disable to turn-off request body validation done before client makes a request. By default True
+            Returns:
+                Instance of OSDUAPIClient for given service_name
+            Raises:
+                OSDUClientError: if bad arguments provided
+
+        """
         client_class = get_service_client(service_name, version)
         return client_class(
             auth_backend=auth_backend,
             validation=validation,
         )
+
+    @classmethod
+    def print_available_services(cls):
+        """
+        Prints available services for client
+        """
+        print("|      Name      |    Versions    |")
+        print("===================================")
+        for k, v in cls.list_available_services():
+            print("|", end="")
+            space = 16 - len(k)
+            print((" "*(space//2))+k+(" "*((space//2) + space % 2)), end="")
+            print("|", end="")
+            versions_str = str(v)[1:-1].replace("'", "")
+            versions_str = versions_str if len(versions_str) else "latest"
+            space = 16 - len(versions_str)
+            print(" "*(space//2)+versions_str+(" "*((space//2) + space % 2)), end="")
+            print("|")
+
+    @staticmethod
+    def list_available_services() -> list[tuple[str, list[str]]]:
+        """
+        Returns list of available services for client
+        Returns:
+            list of available services for API versions (list[tuple[str, list[str]]])
+        """
+        module = import_module("osdu_client.services")
+        return [(k, v) for k, v in module.SERVICES.items()]

osdu_client/exceptions.py

@@ -5,3 +5,7 @@ class OSDUClientError(Exception):
 
 class OSDUAPIError(OSDUClientError):
     pass
+
+
+class OSDUValidation(OSDUClientError):
+    pass

osdu_client/services/__init__.py

@@ -0,0 +1,22 @@
+from osdu_client.services import rafs, wellbore
+
+SERVICES = {
+    "dataset": [],
+    "entitlements": [],
+    "file": [],
+    "indexer": [],
+    "legal": [],
+    "notification": [],
+    "partition": [],
+    "policy": [],
+    "pws": [],
+    "rafs": list(rafs.VERSIONS.keys()),
+    "register": [],
+    "schema": [],
+    "sdms": [],
+    "search": [],
+    "secret": [],
+    "storage": [],
+    "wellbore": list(wellbore.VERSIONS.keys()),
+    "welldelivery": [],
+}