mimicker 2.1.3__tar.gz → 2.2.3__tar.gz

mimicker-2.2.3/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: mimicker
+Version: 2.2.3
+Summary: A lightweight HTTP mocking server for Python
+License: MIT
+License-File: LICENSE
+Keywords: http,mocking,testing,mock-server,stubbing,ci-cd,http-server,testing-tools,stub-server,purepython
+Author: Amazia Gur
+Author-email: amaziagur@gmail.com
+Requires-Python: >=3.7,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: colorlog (>=6.9.0,<7.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Project-URL: Homepage, https://github.com/mimickerhq/mimicker
+Project-URL: Repository, https://github.com/mimickerhq/mimicker
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mimickerhq/mimicker/main/mimicker.jpg" alt="Mimicker logo"
+       style="width: 200px; height: auto; border-radius: 8px; box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); border: 2px solid black;">
+</p>
+
+<div align="center">
+
+> **Mimicker** – Your lightweight, Python-native HTTP mocking server.
+
+</div>
+
+<div align="center">
+
+[![Mimicker Tests](https://github.com/mimickerhq/mimicker/actions/workflows/test.yml/badge.svg)](https://github.com/mimickerhq/mimicker/actions/workflows/test.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/mimicker.svg)](https://pypi.org/project/mimicker/)
+[![Downloads](https://pepy.tech/badge/mimicker)](https://pepy.tech/project/mimicker)
+[![Last Commit](https://img.shields.io/github/last-commit/mimickerhq/mimicker.svg)](https://github.com/mimickerhq/mimicker/commits/main)
+[![Codecov Coverage](https://codecov.io/gh/mimickerhq/mimicker/branch/main/graph/badge.svg?token=YOUR_CODECOV_TOKEN)](https://codecov.io/gh/mimickerhq/mimicker)
+[![License](http://img.shields.io/:license-apache2.0-red.svg)](http://doge.mit-license.org)
+![Poetry](https://img.shields.io/badge/managed%20with-poetry-blue)
+
+</div>
+
+---
+
+Mimicker is a Python-native HTTP mocking server — no third-party runtime dependencies, ideal for integration tests and CI.
+
+## Quick example
+
+```python
+from mimicker.mimicker import mimicker, get
+
+mimicker(8080).routes(
+    get("/hello").status(200).body({"message": "Hello, World!"})
+)
+```
+
+Or use a YAML config file — no Python needed:
+
+```yaml
+routes:
+  - method: GET
+    path: /hello
+    status: 200
+    body:
+      message: Hello, World!
+```
+
+```bash
+mimicker serve --config stubs.yaml
+```
+
+## Install
+
+```bash
+pip install mimicker
+```
+
+## Documentation
+
+Full docs at **[mimickerhq.github.io/mimicker](https://mimickerhq.github.io/mimicker)**
+
+- [Quickstart](https://mimickerhq.github.io/mimicker/getting-started/quickstart/)
+- [Stubbing Guide](https://mimickerhq.github.io/mimicker/guides/stubbing-guide/) — YAML, Python, and CLI side-by-side
+- [Path & Query Params](https://mimickerhq.github.io/mimicker/guides/path-and-query-params/)
+- [Dynamic Responses](https://mimickerhq.github.io/mimicker/guides/dynamic-responses/)
+- [Docker](https://mimickerhq.github.io/mimicker/ci-cd/docker/)
+- [GitHub Actions](https://mimickerhq.github.io/mimicker/ci-cd/github-actions/)
+- [CLI Reference](https://mimickerhq.github.io/mimicker/reference/cli-reference/)
+- [Python API](https://mimickerhq.github.io/mimicker/reference/python-api/)
+
+## Community
+
+- [Slack](https://join.slack.com/t/mimicker/shared_invite/zt-2yr7vubw4-8Y09YyxZ5j~G2tlQ5uOXKw)
+- [Issues](https://github.com/mimickerhq/mimicker/issues)
+

mimicker-2.2.3/README.md

@@ -0,0 +1,75 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mimickerhq/mimicker/main/mimicker.jpg" alt="Mimicker logo"
+       style="width: 200px; height: auto; border-radius: 8px; box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); border: 2px solid black;">
+</p>
+
+<div align="center">
+
+> **Mimicker** – Your lightweight, Python-native HTTP mocking server.
+
+</div>
+
+<div align="center">
+
+[![Mimicker Tests](https://github.com/mimickerhq/mimicker/actions/workflows/test.yml/badge.svg)](https://github.com/mimickerhq/mimicker/actions/workflows/test.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/mimicker.svg)](https://pypi.org/project/mimicker/)
+[![Downloads](https://pepy.tech/badge/mimicker)](https://pepy.tech/project/mimicker)
+[![Last Commit](https://img.shields.io/github/last-commit/mimickerhq/mimicker.svg)](https://github.com/mimickerhq/mimicker/commits/main)
+[![Codecov Coverage](https://codecov.io/gh/mimickerhq/mimicker/branch/main/graph/badge.svg?token=YOUR_CODECOV_TOKEN)](https://codecov.io/gh/mimickerhq/mimicker)
+[![License](http://img.shields.io/:license-apache2.0-red.svg)](http://doge.mit-license.org)
+![Poetry](https://img.shields.io/badge/managed%20with-poetry-blue)
+
+</div>
+
+---
+
+Mimicker is a Python-native HTTP mocking server — no third-party runtime dependencies, ideal for integration tests and CI.
+
+## Quick example
+
+```python
+from mimicker.mimicker import mimicker, get
+
+mimicker(8080).routes(
+    get("/hello").status(200).body({"message": "Hello, World!"})
+)
+```
+
+Or use a YAML config file — no Python needed:
+
+```yaml
+routes:
+  - method: GET
+    path: /hello
+    status: 200
+    body:
+      message: Hello, World!
+```
+
+```bash
+mimicker serve --config stubs.yaml
+```
+
+## Install
+
+```bash
+pip install mimicker
+```
+
+## Documentation
+
+Full docs at **[mimickerhq.github.io/mimicker](https://mimickerhq.github.io/mimicker)**
+
+- [Quickstart](https://mimickerhq.github.io/mimicker/getting-started/quickstart/)
+- [Stubbing Guide](https://mimickerhq.github.io/mimicker/guides/stubbing-guide/) — YAML, Python, and CLI side-by-side
+- [Path & Query Params](https://mimickerhq.github.io/mimicker/guides/path-and-query-params/)
+- [Dynamic Responses](https://mimickerhq.github.io/mimicker/guides/dynamic-responses/)
+- [Docker](https://mimickerhq.github.io/mimicker/ci-cd/docker/)
+- [GitHub Actions](https://mimickerhq.github.io/mimicker/ci-cd/github-actions/)
+- [CLI Reference](https://mimickerhq.github.io/mimicker/reference/cli-reference/)
+- [Python API](https://mimickerhq.github.io/mimicker/reference/python-api/)
+
+## Community
+
+- [Slack](https://join.slack.com/t/mimicker/shared_invite/zt-2yr7vubw4-8Y09YyxZ5j~G2tlQ5uOXKw)
+- [Issues](https://github.com/mimickerhq/mimicker/issues)

mimicker-2.2.3/mimicker/cli.py

@@ -0,0 +1,274 @@
+import argparse
+import json
+import os
+import re
+import signal
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Optional
+
+from mimicker.config import build_routes, load_config, validate_config
+from mimicker.logger import get_logger
+from mimicker.mimicker import mimicker
+from mimicker.route import Route
+
+_HEALTH_PATH = "/__mimicker__/health"
+_REPORT_PATH = "/__mimicker__/report"
+_AUTO_CONFIG_PATH = "/config/stubs.yaml"
+
+
+def cmd_serve(args):
+    port = args.port
+    routes = []
+
+    # Auto-detect config if not specified
+    config_path = args.config
+    if not config_path and os.path.exists(_AUTO_CONFIG_PATH):
+        config_path = _AUTO_CONFIG_PATH
+        get_logger().info("Auto-loading config from %s", _AUTO_CONFIG_PATH)
+
+    if config_path:
+        try:
+            data = load_config(config_path)
+        except FileNotFoundError:
+            print(f"[ERROR] Config file not found: {config_path}", file=sys.stderr)
+            sys.exit(1)
+        except Exception as e:
+            print(f"[ERROR] Failed to parse config file: {e}", file=sys.stderr)
+            sys.exit(1)
+
+        errors = validate_config(data)
+        if errors:
+            for e in errors:
+                print(f"[ERROR] {e}", file=sys.stderr)
+            sys.exit(1)
+
+        routes = build_routes(data)
+        if port is None:
+            port = int(data.get("port", 8080))
+
+    if port is None:
+        port = 8080
+
+    if args.stub:
+        route = _parse_inline_stub(args.stub)
+        routes.append(route)
+
+    server = mimicker(port)
+    if routes:
+        server.routes(*routes)
+
+    get_logger().info("Serving on port %d. Press Ctrl+C to stop.", port)
+
+    def _shutdown(*_):
+        server.shutdown()
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, _shutdown)
+    try:
+        server._thread.join()
+    except KeyboardInterrupt:
+        server.shutdown()
+
+
+def cmd_wait(args):
+    url = args.url.rstrip("/") + _HEALTH_PATH
+    deadline = time.monotonic() + args.timeout
+    last_error: Optional[Exception] = None
+
+    while time.monotonic() < deadline:
+        try:
+            with urllib.request.urlopen(url, timeout=1) as resp:
+                if resp.status == 200:
+                    print(f"[OK] Mimicker is ready at {args.url}")
+                    sys.exit(0)
+        except Exception as exc:
+            last_error = exc
+        time.sleep(0.2)
+
+    print(
+        f"[ERROR] Mimicker not ready after {args.timeout}s at {args.url}: {last_error}",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def cmd_validate(args):
+    try:
+        data = load_config(args.file)
+    except FileNotFoundError:
+        print(f"[ERROR] File not found: {args.file}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"[ERROR] Failed to parse config: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    errors = validate_config(data)
+    if errors:
+        for e in errors:
+            print(f"[ERROR] {e}", file=sys.stderr)
+        print(f"\nValidation failed with {len(errors)} error(s).", file=sys.stderr)
+        sys.exit(1)
+
+    route_count = len(data.get("routes", []))
+    print(f"[OK] {args.file} is valid ({route_count} route(s) defined)")
+
+
+def cmd_report(args):
+    url = args.url.rstrip("/") + _REPORT_PATH
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:
+            data = json.loads(resp.read())
+    except Exception as e:
+        print(f"[ERROR] Could not reach Mimicker at {args.url}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    fmt = args.format
+    if fmt == "json":
+        print(json.dumps(data, indent=2))
+    elif fmt == "github-summary":
+        _print_github_summary(data)
+    else:
+        _print_text_report(data)
+
+    if args.fail_on_unmatched and data["summary"]["unmatched_requests"] > 0:
+        sys.exit(1)
+
+
+# ── formatters ────────────────────────────────────────────────────────────────
+
+def _print_text_report(data: dict):
+    s = data["summary"]
+    print(f"\nMimicker Report")
+    print(f"  Stubs      : {s['matched_stubs']}/{s['total_stubs']} exercised")
+    print(f"  Unmatched  : {s['unmatched_requests']} request(s)")
+
+    if data["unused_stubs"]:
+        print("\nUnused stubs (never hit):")
+        for stub in data["unused_stubs"]:
+            print(f"  - {stub['method']} {stub['path']}")
+
+    if data["unmatched_requests"]:
+        print("\nUnmatched requests (contract drift):")
+        for req in data["unmatched_requests"]:
+            print(f"  - {req['method']} {req['path']}  [{req['timestamp']}]")
+
+
+def _print_github_summary(data: dict):
+    s = data["summary"]
+    print("## Mimicker Stub Coverage\n")
+    status_icon = "✅" if s["unmatched_requests"] == 0 else "⚠️"
+    print(
+        f"{status_icon} **{s['matched_stubs']}/{s['total_stubs']}** stubs exercised"
+        f" &nbsp;|&nbsp; **{s['unmatched_requests']}** unmatched request(s)\n"
+    )
+
+    print("### Stub Coverage\n")
+    print("| Method | Path | Hits |")
+    print("|--------|------|-----:|")
+    for stub in data["stubs"]:
+        icon = "✅" if stub["hit_count"] > 0 else "❌"
+        print(f"| `{stub['method']}` | `{stub['path']}` | {icon} {stub['hit_count']} |")
+
+    if data["unmatched_requests"]:
+        print("\n### Unmatched Requests (Contract Drift)\n")
+        print("| Method | Path | Timestamp |")
+        print("|--------|------|-----------|")
+        for req in data["unmatched_requests"]:
+            print(f"| `{req['method']}` | `{req['path']}` | {req['timestamp']} |")
+
+
+# ── inline stub parser ────────────────────────────────────────────────────────
+
+def _parse_inline_stub(stub_str: str) -> Route:
+    """Parse inline stub syntax: 'METHOD /path -> STATUS {json_body}'"""
+    m = re.match(r'^(\w+)\s+(/\S*)\s+->\s+(\d+)(?:\s+(.+))?$', stub_str.strip())
+    if not m:
+        print(
+            "[ERROR] Invalid --stub format. Expected: 'METHOD /path -> STATUS {json}'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    method, path, status, body_str = (
+        m.group(1).upper(), m.group(2), int(m.group(3)), m.group(4)
+    )
+    route = Route(method, path).status(status)
+    if body_str:
+        try:
+            route.body(json.loads(body_str))
+        except json.JSONDecodeError:
+            route.body(body_str)
+    return route
+
+
+# ── entry point ───────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="mimicker",
+        description="Mimicker — lightweight HTTP mock server",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # serve
+    p_serve = sub.add_parser("serve", help="Start the mock server")
+    p_serve.add_argument(
+        "--port", type=int, default=None,
+        help="Port to listen on (default: 8080, or value from config file)"
+    )
+    p_serve.add_argument("--config", metavar="FILE", help="YAML or JSON stub config file")
+    p_serve.add_argument(
+        "--stub", metavar="STUB",
+        help="Inline stub: 'METHOD /path -> STATUS {json}'"
+    )
+
+    # wait
+    p_wait = sub.add_parser(
+        "wait", help="Poll the health endpoint until the server is ready"
+    )
+    p_wait.add_argument(
+        "--url", default="http://localhost:8080",
+        help="Server base URL (default: http://localhost:8080)"
+    )
+    p_wait.add_argument(
+        "--timeout", type=float, default=10.0,
+        help="Maximum seconds to wait (default: 10)"
+    )
+
+    # validate
+    p_val = sub.add_parser(
+        "validate", help="Validate a stub config file without starting a server"
+    )
+    p_val.add_argument("file", help="YAML or JSON stub config file to validate")
+
+    # report
+    p_rep = sub.add_parser(
+        "report", help="Fetch and display the stub coverage/drift report"
+    )
+    p_rep.add_argument(
+        "--url", default="http://localhost:8080",
+        help="Server base URL (default: http://localhost:8080)"
+    )
+    p_rep.add_argument(
+        "--format", choices=["text", "json", "github-summary"], default="text",
+        help="Output format (default: text)"
+    )
+    p_rep.add_argument(
+        "--fail-on-unmatched", action="store_true",
+        help="Exit non-zero if any requests were unmatched (for CI gates)"
+    )
+
+    args = parser.parse_args()
+    {
+        "serve": cmd_serve,
+        "wait": cmd_wait,
+        "validate": cmd_validate,
+        "report": cmd_report,
+    }[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

mimicker-2.2.3/mimicker/config.py

@@ -0,0 +1,101 @@
+import json
+import os
+from typing import Any, Dict, List
+
+from mimicker.route import Route
+from mimicker.sequence import SequenceStep
+
+
+_VALID_METHODS = {"GET", "POST", "PUT", "DELETE", "PATCH"}
+
+
+def load_config(path: str) -> Dict[str, Any]:
+    """Load and parse a YAML or JSON stub config file."""
+    _, ext = os.path.splitext(path.lower())
+    with open(path) as f:
+        if ext in (".yaml", ".yml"):
+            try:
+                import yaml
+            except ImportError:
+                raise ImportError(
+                    "PyYAML is required to load YAML config files. "
+                    "Install it with: pip install pyyaml"
+                )
+            data = yaml.safe_load(f)
+        else:
+            data = json.load(f)
+    return data or {}
+
+
+def validate_config(data: Dict[str, Any]) -> List[str]:
+    """Validate config data. Returns a list of human-readable error messages."""
+    errors = []
+    routes = data.get("routes", [])
+    if not isinstance(routes, list):
+        errors.append("'routes' must be a list")
+        return errors
+
+    for i, route in enumerate(routes):
+        prefix = f"routes[{i}]"
+        if not isinstance(route, dict):
+            errors.append(f"{prefix}: must be a mapping")
+            continue
+        method = str(route.get("method", "")).upper()
+        if method not in _VALID_METHODS:
+            errors.append(
+                f"{prefix}: invalid method {route.get('method')!r}. "
+                f"Must be one of {sorted(_VALID_METHODS)}"
+            )
+        if not route.get("path"):
+            errors.append(f"{prefix}: 'path' is required")
+        status = route.get("status", 200)
+        if not isinstance(status, int) or not (100 <= status <= 599):
+            errors.append(f"{prefix}: 'status' must be an HTTP status code integer")
+        if "sequence" in route and not isinstance(route["sequence"], list):
+            errors.append(f"{prefix}: 'sequence' must be a list of step objects")
+
+    return errors
+
+
+def build_routes(data: Dict[str, Any]) -> List[Route]:
+    """Convert validated config data into Route objects."""
+    routes = []
+    for r in data.get("routes", []):
+        method = str(r.get("method", "GET")).upper()
+        path = r.get("path", "/")
+
+        # Append explicit query_params to the path so the existing regex engine handles them
+        if "query_params" in r and isinstance(r["query_params"], dict):
+            qp_str = "&".join(f"{k}={v}" for k, v in r["query_params"].items())
+            path = f"{path}?{qp_str}"
+
+        route = Route(method, path)
+
+        if "status" in r:
+            route.status(int(r["status"]))
+        if "body" in r:
+            route.body(r["body"])
+        if "headers" in r:
+            h = r["headers"]
+            route.headers(list(h.items()) if isinstance(h, dict) else h)
+        if "delay_ms" in r:
+            route.delay(float(r["delay_ms"]) / 1000.0)
+
+        if "sequence" in r:
+            steps = []
+            for step_data in r["sequence"]:
+                s = SequenceStep()
+                if "status" in step_data:
+                    s.status(int(step_data["status"]))
+                if "body" in step_data:
+                    s.body(step_data["body"])
+                if "headers" in step_data:
+                    h = step_data["headers"]
+                    s.headers(list(h.items()) if isinstance(h, dict) else h)
+                if "delay_ms" in step_data:
+                    s.delay(float(step_data["delay_ms"]) / 1000.0)
+                steps.append(s)
+            route.sequence(*steps, cycle=bool(r.get("cycle", False)))
+
+        routes.append(route)
+    return routes

{mimicker-2.1.3 → mimicker-2.2.3}/mimicker/handler.py

@@ -1,12 +1,16 @@
 import http.server
 import json
 from time import sleep
-from typing import Any, Tuple, Optional, Dict, List
+from typing import Any, Dict, List, Optional, Tuple
 from urllib.parse import parse_qs, urlparse
 
 from mimicker.logger import get_logger
 from mimicker.stub_group import Stub, StubGroup
 
+_HEALTH_PATH = "/__mimicker__/health"
+_REPORT_PATH = "/__mimicker__/report"
+_ADMIN_PREFIX = "/__mimicker__/"
+
 
 class MimickerHandler(http.server.SimpleHTTPRequestHandler):
     logger = get_logger()
@@ -34,6 +38,9 @@ class MimickerHandler(http.server.SimpleHTTPRequestHandler):
         self._handle_request("PATCH")
 
     def _handle_request(self, method: str):
+        parsed = urlparse(self.path)
+        clean_path = parsed.path
+
         request_headers = {key.lower(): value for key, value in self.headers.items()}
         request_body = self._get_request_body()
 
@@ -45,8 +52,13 @@ class MimickerHandler(http.server.SimpleHTTPRequestHandler):
 
         if matched_stub:
             self._send_response(matched_stub, method, path_params,
-                                parse_qs(urlparse(self.path).query), request_body,
+                                parse_qs(parsed.query), request_body,
                                 request_headers)
+        elif clean_path == _HEALTH_PATH:
+            # User stubs take precedence; admin handler is the fallback.
+            self._send_admin_json({"status": "up"})
+        elif clean_path == _REPORT_PATH:
+            self._send_admin_json(self.stub_matcher.tracker.report())
         else:
             self.logger.warning("No match for %s %s. Returning 404.", method, self.path)
             self._send_404_response(method)
@@ -62,6 +74,13 @@ class MimickerHandler(http.server.SimpleHTTPRequestHandler):
             f"\nBody:\n{body_str}" if body_str else ""
         )
 
+    def _send_admin_json(self, data: dict):
+        body = json.dumps(data).encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(body)
+
     def _send_response(self, matched_stub: Stub, method: str,
                        path_params: Dict[str, str],
                        query_params: Dict[str, List[str]], request_body: Any,
@@ -124,6 +143,8 @@ class MimickerHandler(http.server.SimpleHTTPRequestHandler):
             self.wfile.write(json.dumps(response).encode('utf-8'))
         elif isinstance(response, str):
             self.wfile.write(response.encode('utf-8'))
+        elif response is None:
+            pass
         else:
             self.wfile.write(str(response).encode('utf-8'))