surety-api 0.0.1__py3-none-any.whl

surety/api/__init__.py

@@ -0,0 +1,4 @@
+from .caller import ApiCaller
+from .mock.service import MockServer
+from .method import ApiMethod
+from .schema import HttpMethod

surety/api/caller.py

@@ -0,0 +1,85 @@
+from surety.process import dictionary
+from surety.sdk import Field
+from surety.diff import compare
+
+from surety.api.method import ApiMethod
+
+
+class ApiCaller:
+    method: ApiMethod
+
+    def __init__(self, req_body=None, path_params=None, headers=None,
+                 params=None, cookies=None, updates=None):
+        self.req_body = req_body
+        self.response = None
+        self.path_params = path_params
+        self.headers = headers
+        self.params = params
+        self.cookies = cookies
+        self.updates = updates
+
+    def request(self):
+        req_body = self.req_body
+        params = self.params
+
+        if req_body is None:
+            pass
+        elif isinstance(self.req_body, Field):
+            req_body = self.req_body.value
+
+        if self.updates:
+            req_body = dictionary.merge_with_updates(req_body, self.updates)
+
+        if params is None:
+            pass
+        elif isinstance(self.params, Field):
+            params = self.params.value
+
+        self.response = self.method.call(
+            req_body=req_body,
+            path_params=self.path_params,
+            headers=self.headers,
+            params=params,
+            cookies=self.cookies
+        )
+
+        return self
+
+    def verify_response(self, error_code=None, resp_body=None, normalize=False,
+                        normalize_keys=None, parse_response=None, rules=None):
+        if error_code:
+            assert self.response.status_code == error_code, (
+                f'Unexpected code: {self.response.status_code}\n'
+                f'Response text: {self.response.text}'
+            )
+        else:
+            assert self.response.status_code == 200, (
+                f'Unexpected response code: {self.response.status_code}'
+                f'\nResponse text: {self.response.text}'
+            )
+
+        if resp_body is not None or isinstance(resp_body, Field):
+            content_type = self.response.headers.get('Content-Type')
+
+            if content_type == 'text/csv':
+                result_data = self.response.text
+
+                if parse_response and callable(parse_response):
+                    result_data = parse_response(result_data)
+            else:
+                result_data = self.response.text and self.response.json()
+
+            if isinstance(resp_body, Field):
+                resp_body = resp_body.value
+
+            if normalize or normalize_keys:
+                resp_body = dictionary.normalize(resp_body, result_data, keys=normalize_keys)
+
+            compare(
+                expected=resp_body,
+                actual=result_data,
+                rules=rules,
+                target_name='api response'
+            )
+
+        return self

surety/api/method.py

@@ -0,0 +1,175 @@
+import json
+
+import requests
+
+from surety.process import dictionary
+from surety.sdk import Field
+from surety.diff import compare
+
+from surety.api.mock.data import JsonFilter, MatchType, StringFilter
+from surety.api.schema import Schema, HttpMethod
+
+
+class ApiMethod(Schema):
+    @classmethod
+    def call(cls, req_body=None, session=None, path_params=None, headers=None,
+             params=None, cookies=None):
+        session = session or requests.Session()
+
+        if params is None:
+            params = cls.params().value
+
+        if req_body is None:
+            req_body = cls.req_body().value
+
+        if req_body is not None:
+            req_body = json.dumps(req_body)
+
+        url = cls.get_request_url(path_params=path_params)
+        headers = headers or {}
+        headers = dictionary.merge_with_updates(headers, {
+            'Content-Type': 'application/json',
+        })
+
+        return session.request(
+            str(cls.method),
+            url,
+            headers=headers,
+            params=params,
+            data=req_body,
+            cookies=cookies
+        )
+
+    @classmethod
+    def reply(cls, path_params=None, params=None, req_body=None, body=None,
+              status=200, reset=False, cookies=None, headers=None, times=1,
+              no_prefix=False, substr_filter=None, strict=False,
+              default_headers=False):
+        from surety.api.mock.service import MockServer   # pylint: disable=cyclic-import
+        reply_body = body
+
+        if default_headers and headers is None:
+            headers = cls.fe_headers()
+
+        headers = headers or {'Content-Type': 'application/json',}
+
+        if reply_body is None:
+            reply_body = cls.resp_body and cls.resp_body() # pylint: disable=not-callable
+
+        if reply_body not in [None, {}, ''] and isinstance(reply_body, Field):
+            reply_body = reply_body.value
+            reply_body = json.dumps(reply_body)
+
+        if req_body:
+            req_body = JsonFilter().with_values({
+                JsonFilter.Json.name: req_body,
+                JsonFilter.MatchType.name:
+                    MatchType.Strict if strict else MatchType.Partial
+            })
+        elif substr_filter:
+            req_body = StringFilter().with_values({
+                StringFilter.String.name: substr_filter
+            })
+
+        if no_prefix:
+            prefix = ''
+        else:
+            prefix = f'/mockserver/{cls.get_service_name()}'
+
+        return MockServer().reply(
+            method=cls.method,
+            url=f'{prefix}{cls.get_relative_url(path_params)}',
+            params=params,
+            req_body=req_body,
+            body=reply_body,
+            status=status,
+            reset=reset,
+            headers=headers or {},
+            cookies=cookies,
+            times=times
+        )
+
+    @classmethod
+    def reply_corse_options(cls, allow_headers, reset=False, no_prefix=False,
+                            path_params=None, params=None, req_body=None):
+        from surety.api.mock.service import MockServer   # pylint: disable=cyclic-import
+        headers = cls.fe_headers(
+            content_type='Access-Control-Allow-Headers',
+        )
+        headers['Access-Control-Allow-Headers'] = ','.join(allow_headers)
+
+        if no_prefix:
+            prefix = ''
+        else:
+            prefix = f'/mockserver/{cls.get_service_name()}'
+
+        return MockServer().reply(
+            method=HttpMethod.OPTIONS,
+            url=f'{prefix}{cls.get_relative_url(path_params)}',
+            params=params,
+            req_body=req_body,
+            body=None,
+            reset=reset,
+            headers=headers
+        )
+
+    @classmethod
+    def verify_called(cls, expected=None, normalize=False, normalize_keys=None,
+                      path_params=None, timeout=None, body=None, headers=None,
+                      latest=False, params=None, rules=None, header_rules=None):
+        from surety.api.mock.service import MockServer  # pylint: disable=cyclic-import
+
+        expected_value = expected
+
+        if isinstance(expected_value, Field):
+            expected_value = expected_value.value
+        if isinstance(params, Field):
+            params = params.value
+
+        if body:
+            if isinstance(body, str):
+                body = StringFilter().with_values({
+                    StringFilter.String.name: body
+                })
+
+        actual_value, actual_headers, actual_params = MockServer().catch(
+            method=cls.method,
+            url=(f'/mockserver/{cls.get_service_name()}'
+                 f'{cls.get_relative_url(path_params=path_params)}'),
+            body=body,
+            timeout=timeout,
+            latest=latest
+        )
+
+        if normalize or normalize_keys:
+            actual_value = dictionary.normalize(
+                actual_value, expected_value, keys=normalize_keys
+            )
+        compare(
+            actual=actual_value,
+            expected=expected_value,
+            rules=rules or None,
+            target_name='api request'
+        )
+
+        if headers:
+            filtered_headers = {}
+
+            for key in headers:
+                filtered_headers[key] = actual_headers.get(key)
+
+            compare(
+                actual=filtered_headers,
+                expected=headers,
+                rules=header_rules or None,
+                target_name='api request headers'
+            )
+
+        #FIXME parse into object + verify all together
+
+        if params:
+            compare(
+                actual=actual_params,
+                expected=params,
+                target_name='api request params'
+            )

surety/api/mock/data.py

@@ -0,0 +1,95 @@
+from surety.sdk import Bool, Dictionary, Enum, Int, Raw, String
+
+from surety.api.schema import HttpMethod
+
+
+class JsonMatcher(Enum):
+    IGNORE_KEY = '${json-unit.ignore-element}'
+
+
+class HttpRequest(Dictionary):
+    Method = String(name='method')
+    Path = String(name='path')
+    Params = Raw(name='queryStringParameters', required=False)
+    Body = Raw(name='body', required=False)
+
+
+class HttpResponse(Dictionary):
+    StatusCode = Int(name='statusCode')
+    Headers = Raw(name='headers', required=False)
+    Cookies = Raw(name='cookies', required=False)
+    Body = Raw(name='body', required=False)
+
+
+class Command(Enum):
+    Expectation = 'expectation'
+    Reset = 'reset'
+    Retrieve = 'retrieve'
+
+
+class ObjectType(Enum):
+    Requests = 'REQUESTS'
+    ActiveExpectations = 'active_expectations'
+
+
+class Params(Dictionary):
+    Type = String(name='type', required=False)
+
+
+class PathParams(Dictionary):
+    Command = Command(name='command')
+
+
+class Times(Dictionary):
+    RemainingTimes = Int(name='remainingTimes')
+    Unlimited = Bool(name='unlimited', required=False)
+
+
+class ExpectationBody(Dictionary):
+    HttpRequest = HttpRequest(name='httpRequest')
+    HttpResponse = HttpResponse(name='httpResponse')
+    Times = Times(name='times')
+
+
+class RetrieveHttpRequest(Dictionary):
+    Method = HttpMethod(name='method', required=False)
+    Body = Raw(name='body', required=False)
+    Path = String(name='path')
+
+
+class RetrieveBody(Dictionary):
+    HttpRequest = RetrieveHttpRequest(name='httpRequest')
+
+
+class DataResponse(Dictionary):
+    Data = Raw(name='data')
+
+
+class MatchType(Enum):
+    Strict = 'STRICT'
+    Partial = 'ONLY_MATCHING_FIELDS'
+
+
+class JsonFilter(Dictionary):
+    Type = String(name='type', default='JSON')
+    Json = Raw(name='json')
+    MatchType = MatchType(name='matchType', default=MatchType.Partial)
+
+
+class StringFilter(Dictionary):
+    Type = String(name='type', default='STRING')
+    String = String(name='string')
+    SubString = Bool(name='subString', default=True)
+
+
+class TimeToLive(Dictionary):
+    Unlimited = Bool(name='unlimited')
+
+
+class UnaddressedRequest(Dictionary):
+    HttpRequest = HttpRequest(name='httpRequest')
+    HttpResponse = HttpResponse(name='httpResponse', required=False)
+    Id = String(name='id')
+    Priority = Int(name='priority')
+    TimeToLive = TimeToLive(name='timeToLive')
+    Times = Times(name='times', required=False)

surety/api/mock/service.py

@@ -0,0 +1,179 @@
+import waiting
+
+from waiting.exceptions import TimeoutExpired
+
+from surety.sdk import Field
+from surety.config import Cfg
+from surety.api.caller import ApiCaller
+from surety.api.method import ApiMethod
+from surety.api.mock.data import (
+    Command, ExpectationBody, HttpRequest, HttpResponse, ObjectType, Params,
+    PathParams, RetrieveBody, RetrieveHttpRequest, Times, UnaddressedRequest,
+)
+from surety.api.schema import HttpMethod
+
+
+def get_mockserver_url():
+    if 'MockServer' in Cfg:
+        return f'http://{Cfg.MockServer.host}:{Cfg.MockServer.port}'
+
+    return None
+
+
+BASE_URL = get_mockserver_url()
+
+
+class RunCommand(ApiMethod):
+    method = HttpMethod.PUT
+    url = 'mockserver/{command}'
+    path_params = PathParams
+
+
+class MockClient(ApiCaller):
+    method = RunCommand
+
+    def __init__(self, command, params=None, headers=None, body=None):
+        super().__init__(
+            headers=headers,
+            path_params=PathParams().with_values({
+                PathParams.Command.name: command,
+            }),
+            params=params,
+            req_body=body
+        )
+
+
+class MockServer:
+    @staticmethod
+    def _get_client(command, params=None, headers=None, body=None):
+        return MockClient(command, params, headers, body).request()
+
+    def reset(self):
+        self._get_client(command=Command.Reset, headers={})
+
+    def reply(self, method, url, body, status=200, params=None, req_body=None,
+              headers=None, cookies=None, times=1, reset=True):
+        if reset:
+            self.reset()
+
+        self._get_client(
+            command=Command.Expectation,
+            headers=headers,
+            body=ExpectationBody().with_values({
+                ExpectationBody.HttpRequest.name: {
+                    HttpRequest.Method.name: method,
+                    HttpRequest.Path.name: url,
+                    HttpRequest.Params.name: params,
+                    HttpRequest.Body.name: req_body,
+                },
+                ExpectationBody.HttpResponse.name: {
+                    HttpResponse.StatusCode.name: status,
+                    HttpResponse.Headers.name: headers,
+                    HttpResponse.Cookies.name: cookies,
+                    HttpResponse.Body.name: body
+                },
+                ExpectationBody.Times.name: {
+                    Times.RemainingTimes.name: times,
+                    Times.Unlimited.name: False,
+                }
+            })
+        )
+
+    def catch(self, url, body=None, method=None, timeout=None,
+              latest=False):
+        req_body = body
+
+        if isinstance(req_body, Field):
+            req_body = req_body.value
+
+        def catch_request():
+            return self._get_client(
+                command=Command.Retrieve,
+                params=Params().with_values({
+                    Params.Type.name: ObjectType.Requests,
+                }),
+                body=RetrieveBody().with_values({
+                    RetrieveBody.HttpRequest.name:
+                        RetrieveHttpRequest().with_values({
+                            RetrieveHttpRequest.Method.name: method,
+                            RetrieveHttpRequest.Path.name: url,
+                            RetrieveHttpRequest.Body.name: req_body,
+                        }),
+                })
+            ).response.json()
+
+        if timeout is None:
+            caught = catch_request()
+        else:
+            caught = waiting.wait(
+                catch_request,
+                timeout_seconds=timeout,
+                sleep_seconds=0,
+                waiting_for='request'
+            )
+
+        assert caught, 'No requests received'
+
+        if latest:
+            incoming = caught[0]
+        else:
+            assert len(caught) == 1, 'More than one request are caught'
+            incoming = caught[0]
+
+        headers = incoming.get('headers')
+        body = incoming.get('body')
+        params = incoming.get('queryStringParameters')
+
+        if isinstance(body, dict) and 'json' in body:
+            body = body['json']
+
+        return body, headers, params
+
+    def get_unaddressed_requests(self):
+        response = self._get_client(
+            command=Command.Retrieve,
+            params=Params().with_values({
+                Params.Type.name: ObjectType.ActiveExpectations,
+            })
+        ).response.json()
+
+        return [UnaddressedRequest().with_values(resp) for resp in response]
+
+    def wait_for_mocks_to_be_called(self, timeout_seconds=1):
+        try:
+            return waiting.wait(
+                lambda: not self.get_unaddressed_requests(),
+                sleep_seconds=0,
+                timeout_seconds=timeout_seconds,
+                waiting_for='mocks to be called',
+            )
+        except TimeoutExpired:
+            return None
+
+    def verify_all_mocks_called(self, timeout_seconds=1):  # pylint:disable=inconsistent-return-statements
+        try:
+            return waiting.wait(
+                lambda: not self.get_unaddressed_requests(),
+                sleep_seconds=0,
+                timeout_seconds=timeout_seconds,
+                waiting_for='mocks to be called',
+            )
+        except TimeoutExpired:
+            pass
+
+        requests = self.get_unaddressed_requests()
+        parsed_reqs = ''
+
+        for req in requests:
+            body = req.HttpRequest.Body.value
+
+            if body and 'json' in body:
+                body = body['json']
+
+            parsed_reqs += (
+                f'\n{req.HttpRequest.Method.value} '
+                f'{req.HttpRequest.Path.value} {body}'
+                f'\nTimes: {req.Times.RemainingTimes.value}'
+            )
+
+        assert not requests, f'There are unused mocks: {parsed_reqs}'

surety/api/schema.py

@@ -0,0 +1,79 @@
+import inspect
+
+from urllib.parse import urljoin
+
+from surety.process.common import exclude_none_from_kwargs
+from surety.sdk import Dictionary, Enum
+from surety.config import Cfg
+
+
+def get_default_app_url():
+    if 'App' in Cfg:
+        return Cfg.App.get('url')
+
+    return None
+
+
+class HttpMethod(Enum):
+    POST = 'POST'
+    GET = 'GET'
+    HEAD = 'HEAD'
+    PATCH = 'PATCH'
+    DELETE = 'DELETE'
+    PUT = 'PUT'
+    TRACE = 'TRACE'
+    OPTIONS = 'OPTIONS'
+
+
+class Schema:
+    """
+      Additional configuration on module level:
+      SERVICE: service name for mocking
+      BASE_URL: application base url if not Cfg.App.url (default)
+      API_URL: api base url
+    """
+
+    method: HttpMethod
+    url: str
+    path_params = Dictionary
+    params = Dictionary
+    req_body = Dictionary
+    resp_body = Dictionary
+
+    @classmethod
+    def get_relative_url(cls, path_params=None):
+        path_params = path_params or cls.path_params()
+        formatted_url = cls.url.format(**path_params.value)
+        return f'{cls.get_api_base_url()}{formatted_url}'
+
+    @classmethod
+    def get_service_name(cls):
+        parent_module = inspect.getmodule(cls)
+        return getattr(parent_module, 'SERVICE', None)
+
+    @classmethod
+    def get_base_url(cls):
+        parent_module = inspect.getmodule(cls)
+        return getattr(parent_module, 'BASE_URL', get_default_app_url())
+
+    @classmethod
+    def get_api_base_url(cls):
+        parent_module = inspect.getmodule(cls)
+        return getattr(parent_module, 'API_URL', '')
+
+    @classmethod
+    def get_request_url(cls, path_params=None):
+        return urljoin(
+            f'{cls.get_base_url()}',
+            f'{cls.get_relative_url(path_params=path_params)}'
+        )
+
+    @classmethod
+    def fe_headers(cls, app_url=None, content_type='application/json',
+                   set_cookie=None):
+        return exclude_none_from_kwargs({
+            'Access-Control-Allow-Origin': app_url or get_default_app_url(),
+            'Access-Control-Allow-Credentials': 'true',
+            'Content-Type': content_type,
+            'Set-Cookie': set_cookie,
+        })

surety_api-0.0.1.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: surety-api
+Version: 0.0.1
+Summary: Contract-aware API interaction layer for the Surety ecosystem.
+Author-email: Elena Kulgavaya <elena.kulgavaya@gmail.com>
+License: MIT
+Keywords: api,contract-testing,automation,integration-testing,surety
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: deepdiff==8.0.1
+Requires-Dist: surety<1.0,>=0.0.4
+Requires-Dist: surety-config>=0.0.3
+Requires-Dist: surety-diff>=0.0.1
+Requires-Dist: requests
+Requires-Dist: pyyaml
+Requires-Dist: waiting
+Dynamic: license-file
+
+# Surety API
+
+Contract-aware API interaction layer for the Surety ecosystem.
+
+`surety-api` enables structured API testing, mocking, and
+interaction based on Surety contracts.
+
+It bridges declarative contracts and real HTTP communication.
+
+---
+
+## Installation
+
+```bash
+pip install surety-api

surety_api-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+surety/api/__init__.py,sha256=L9CtiC2lk7fVnzAk5dpT7NsA9EqL_xccpNVIcitZZsY,128
+surety/api/caller.py,sha256=o5ZEgrxIX_FYUgjmhH8O-z9m703isuIvbpxRJ9HTV9o,2701
+surety/api/method.py,sha256=R5GReigCdpEnwepCQuNfvSPT3wP5F1nIMaiLRPrXm2c,5630
+surety/api/schema.py,sha256=GLw2JtrTburkXs_4HtBfgleexyo-oGhCv0PE4FyYQG8,2114
+surety/api/mock/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+surety/api/mock/data.py,sha256=01hqX3MKvDkx-LpYG0Gcp4dUblYzlC1EUemgDspT8OU,2397
+surety/api/mock/service.py,sha256=06OzsPBSZMB-Up7czOWsz5jBiNAu1RMXFHJZWvzOxm4,5700
+surety_api-0.0.1.dist-info/licenses/LICENSE,sha256=3TUbLvR5i9BMk3nE-KUtbyBFoL73ES3YioEMOvxselQ,1072
+surety_api-0.0.1.dist-info/METADATA,sha256=xCTfy2b-jL2z0pAUsFkzh_EnuCP_wDz9-CaPIJ-h_oc,1016
+surety_api-0.0.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+surety_api-0.0.1.dist-info/top_level.txt,sha256=a0-FMXVmX6qb_bkdgaQl82FUEQ-xnlMOp3ibsLoxdgs,7
+surety_api-0.0.1.dist-info/RECORD,,

surety_api-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

surety_api-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elena Kulgavaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

surety_api-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+surety