morphql 0.1.35__tar.gz

morphql-0.1.35/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hyperwindmill
+
+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.

morphql-0.1.35/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: morphql
+Version: 0.1.35
+Summary: Python client for MorphQL — transform data with declarative queries.
+Author: Hyperwindmill
+License: MIT
+Project-URL: Homepage, https://github.com/Hyperwindmill/morphql
+Project-URL: Repository, https://github.com/Hyperwindmill/morphql
+Project-URL: Issues, https://github.com/Hyperwindmill/morphql/issues
+Keywords: morphql,transform,query,json,xml,edi,dsl
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# morphql · Python client
+
+Python client for [MorphQL](https://github.com/Hyperwindmill/morphql) — a declarative DSL for structural data transformation.
+
+Delegates execution to the MorphQL **CLI** or a running **MorphQL server**. Zero external dependencies. Python >= 3.8.
+
+## Installation
+
+```bash
+pip install morphql
+```
+
+## Quick start
+
+```python
+from morphql import MorphQL
+
+# One-shot static call (CLI provider)
+result = MorphQL.execute(
+    "from json to json transform set name = source.firstName",
+    data={"firstName": "Alice"},
+)
+print(result)  # {"name":"Alice"}
+
+# From a .morphql file
+result = MorphQL.execute_file("transform.morphql", data={"x": 1})
+
+# Instance with preset defaults (server provider)
+morph = MorphQL(provider="server", server_url="http://localhost:3000")
+result = morph.run("from json to json transform set x = source.x", data={"x": 42})
+result = morph.run_file("transform.morphql", data={"x": 42})
+```
+
+## Providers
+
+| Provider   | How it works                                      |
+|------------|---------------------------------------------------|
+| `"cli"`    | Runs `morphql` CLI via `subprocess` (default)     |
+| `"server"` | `POST {server_url}/v1/execute` via `urllib`       |
+
+## Options
+
+| Option       | Default                     | Env var               |
+|--------------|-----------------------------|-----------------------|
+| `provider`   | `"cli"`                     | `MORPHQL_PROVIDER`    |
+| `runtime`    | `"node"`                    | `MORPHQL_RUNTIME`     |
+| `cli_path`   | `"morphql"`                 | `MORPHQL_CLI_PATH`    |
+| `node_path`  | `"node"`                    | `MORPHQL_NODE_PATH`   |
+| `qjs_path`   | auto-resolved               | `MORPHQL_QJS_PATH`    |
+| `cache_dir`  | `$TMPDIR/morphql`           | `MORPHQL_CACHE_DIR`   |
+| `server_url` | `"http://localhost:3000"`   | `MORPHQL_SERVER_URL`  |
+| `api_key`    | `None`                      | `MORPHQL_API_KEY`     |
+| `timeout`    | `30` (seconds)              | `MORPHQL_TIMEOUT`     |
+
+Priority: call kwarg > instance default > env var > hardcoded default.
+
+## API
+
+### Static
+
+```python
+MorphQL.execute(query, data=None, **options) -> str
+MorphQL.execute_file(query_file, data=None, **options) -> str
+```
+
+### Instance
+
+```python
+morph = MorphQL(**defaults)
+morph.run(query, data=None, **options) -> str
+morph.run_file(query_file, data=None, **options) -> str
+```
+
+`data` accepts `str` (JSON), `dict`, `list`, or `None`.
+
+## Exceptions
+
+| Situation                  | Exception           |
+|----------------------------|---------------------|
+| `query` missing or empty   | `ValueError`        |
+| Query file not found       | `FileNotFoundError` |
+| CLI exits with error       | `RuntimeError`      |
+| Server HTTP error          | `RuntimeError`      |
+| Server unreachable         | `RuntimeError`      |
+
+## Running tests
+
+```bash
+cd packages/python
+PYTHONPATH=src python -m unittest discover tests/
+# or with pytest:
+pip install pytest
+pytest
+```
+
+## License
+
+MIT

morphql-0.1.35/README.md

@@ -0,0 +1,98 @@
+# morphql · Python client
+
+Python client for [MorphQL](https://github.com/Hyperwindmill/morphql) — a declarative DSL for structural data transformation.
+
+Delegates execution to the MorphQL **CLI** or a running **MorphQL server**. Zero external dependencies. Python >= 3.8.
+
+## Installation
+
+```bash
+pip install morphql
+```
+
+## Quick start
+
+```python
+from morphql import MorphQL
+
+# One-shot static call (CLI provider)
+result = MorphQL.execute(
+    "from json to json transform set name = source.firstName",
+    data={"firstName": "Alice"},
+)
+print(result)  # {"name":"Alice"}
+
+# From a .morphql file
+result = MorphQL.execute_file("transform.morphql", data={"x": 1})
+
+# Instance with preset defaults (server provider)
+morph = MorphQL(provider="server", server_url="http://localhost:3000")
+result = morph.run("from json to json transform set x = source.x", data={"x": 42})
+result = morph.run_file("transform.morphql", data={"x": 42})
+```
+
+## Providers
+
+| Provider   | How it works                                      |
+|------------|---------------------------------------------------|
+| `"cli"`    | Runs `morphql` CLI via `subprocess` (default)     |
+| `"server"` | `POST {server_url}/v1/execute` via `urllib`       |
+
+## Options
+
+| Option       | Default                     | Env var               |
+|--------------|-----------------------------|-----------------------|
+| `provider`   | `"cli"`                     | `MORPHQL_PROVIDER`    |
+| `runtime`    | `"node"`                    | `MORPHQL_RUNTIME`     |
+| `cli_path`   | `"morphql"`                 | `MORPHQL_CLI_PATH`    |
+| `node_path`  | `"node"`                    | `MORPHQL_NODE_PATH`   |
+| `qjs_path`   | auto-resolved               | `MORPHQL_QJS_PATH`    |
+| `cache_dir`  | `$TMPDIR/morphql`           | `MORPHQL_CACHE_DIR`   |
+| `server_url` | `"http://localhost:3000"`   | `MORPHQL_SERVER_URL`  |
+| `api_key`    | `None`                      | `MORPHQL_API_KEY`     |
+| `timeout`    | `30` (seconds)              | `MORPHQL_TIMEOUT`     |
+
+Priority: call kwarg > instance default > env var > hardcoded default.
+
+## API
+
+### Static
+
+```python
+MorphQL.execute(query, data=None, **options) -> str
+MorphQL.execute_file(query_file, data=None, **options) -> str
+```
+
+### Instance
+
+```python
+morph = MorphQL(**defaults)
+morph.run(query, data=None, **options) -> str
+morph.run_file(query_file, data=None, **options) -> str
+```
+
+`data` accepts `str` (JSON), `dict`, `list`, or `None`.
+
+## Exceptions
+
+| Situation                  | Exception           |
+|----------------------------|---------------------|
+| `query` missing or empty   | `ValueError`        |
+| Query file not found       | `FileNotFoundError` |
+| CLI exits with error       | `RuntimeError`      |
+| Server HTTP error          | `RuntimeError`      |
+| Server unreachable         | `RuntimeError`      |
+
+## Running tests
+
+```bash
+cd packages/python
+PYTHONPATH=src python -m unittest discover tests/
+# or with pytest:
+pip install pytest
+pytest
+```
+
+## License
+
+MIT

morphql-0.1.35/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "morphql"
+version = "0.1.35"
+description = "Python client for MorphQL — transform data with declarative queries."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = []
+keywords = ["morphql", "transform", "query", "json", "xml", "edi", "dsl"]
+authors = [{ name = "Hyperwindmill" }]
+
+[project.urls]
+Homepage = "https://github.com/Hyperwindmill/morphql"
+Repository = "https://github.com/Hyperwindmill/morphql"
+Issues = "https://github.com/Hyperwindmill/morphql/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

morphql-0.1.35/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

morphql-0.1.35/src/morphql/__init__.py

@@ -0,0 +1,3 @@
+from .morphql import MorphQL
+
+__all__ = ["MorphQL"]

morphql-0.1.35/src/morphql/morphql.py

@@ -0,0 +1,361 @@
+"""
+MorphQL Python Wrapper
+
+A minimalist Python client for MorphQL — transform data with declarative queries.
+Delegates execution to the MorphQL CLI or server via pluggable providers.
+
+https://github.com/Hyperwindmill/morphql
+License: MIT
+Requires Python >= 3.8. No external dependencies.
+"""
+
+import json
+import os
+import platform
+import subprocess
+import tempfile
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional, Union
+
+
+class MorphQL:
+    PROVIDER_CLI = "cli"
+    PROVIDER_SERVER = "server"
+
+    RUNTIME_NODE = "node"
+    RUNTIME_QJS = "qjs"
+
+    _OPTION_DEFAULTS: Dict[str, Any] = {
+        "provider": PROVIDER_CLI,
+        "runtime": RUNTIME_NODE,
+        "cli_path": "morphql",
+        "node_path": "node",
+        "qjs_path": None,
+        "cache_dir": None,
+        "server_url": "http://localhost:3000",
+        "api_key": None,
+        "timeout": 30,
+    }
+
+    _ENV_MAP: Dict[str, str] = {
+        "provider": "MORPHQL_PROVIDER",
+        "runtime": "MORPHQL_RUNTIME",
+        "cli_path": "MORPHQL_CLI_PATH",
+        "node_path": "MORPHQL_NODE_PATH",
+        "qjs_path": "MORPHQL_QJS_PATH",
+        "cache_dir": "MORPHQL_CACHE_DIR",
+        "server_url": "MORPHQL_SERVER_URL",
+        "api_key": "MORPHQL_API_KEY",
+        "timeout": "MORPHQL_TIMEOUT",
+    }
+
+    def __init__(self, **defaults: Any) -> None:
+        self._defaults = defaults
+
+    # ------------------------------------------------------------------
+    #  Public static API
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def execute(
+        cls,
+        query: str,
+        data: Union[str, dict, list, None] = None,
+        **options: Any,
+    ) -> str:
+        if not query:
+            raise ValueError("MorphQL: 'query' is required")
+        config = cls._resolve_config(options)
+        return cls._dispatch(query, data, config)
+
+    @classmethod
+    def execute_file(
+        cls,
+        query_file: str,
+        data: Union[str, dict, list, None] = None,
+        **options: Any,
+    ) -> str:
+        cls._validate_query_file(query_file)
+        config = cls._resolve_config(options)
+        return cls._dispatch(None, data, config, query_file=query_file)
+
+    # ------------------------------------------------------------------
+    #  Public instance API
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        query: str,
+        data: Union[str, dict, list, None] = None,
+        **options: Any,
+    ) -> str:
+        if not query:
+            raise ValueError("MorphQL: 'query' is required")
+        config = self._resolve_config(options, self._defaults)
+        return self._dispatch(query, data, config)
+
+    def run_file(
+        self,
+        query_file: str,
+        data: Union[str, dict, list, None] = None,
+        **options: Any,
+    ) -> str:
+        self._validate_query_file(query_file)
+        config = self._resolve_config(options, self._defaults)
+        return self._dispatch(None, data, config, query_file=query_file)
+
+    # ------------------------------------------------------------------
+    #  Dispatch
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _dispatch(
+        cls,
+        query: Optional[str],
+        data: Any,
+        config: Dict[str, Any],
+        query_file: Optional[str] = None,
+    ) -> str:
+        if config["provider"] == cls.PROVIDER_SERVER:
+            return cls._execute_via_server(query, data, config, query_file)
+        return cls._execute_via_cli(query, data, config, query_file)
+
+    # ------------------------------------------------------------------
+    #  CLI Provider
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _execute_via_cli(
+        cls,
+        query: Optional[str],
+        data: Any,
+        config: Dict[str, Any],
+        query_file: Optional[str] = None,
+    ) -> str:
+        data_str = cls._normalize_data(data)
+        cache_dir = cls._resolve_cache_dir(config)
+        cmd = cls._resolve_cli_command(config)
+
+        if query_file is not None:
+            args = cmd + ["-Q", query_file, "-i", data_str, "--cache-dir", cache_dir]
+        else:
+            args = cmd + ["-q", query, "-i", data_str, "--cache-dir", cache_dir]
+
+        env = {**os.environ, "NODE_NO_WARNINGS": "1"}
+
+        try:
+            result = subprocess.run(
+                args,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=env,
+                timeout=int(config["timeout"]),
+            )
+        except FileNotFoundError:
+            raise RuntimeError(
+                f"MorphQL: CLI executable not found — {args[0]}"
+            )
+        except subprocess.TimeoutExpired:
+            raise RuntimeError("MorphQL: CLI process timed out")
+
+        if result.returncode != 0:
+            stderr = result.stderr.decode(errors="replace").strip()
+            stdout = result.stdout.decode(errors="replace").strip()
+            msg = stderr if stderr else stdout
+            raise RuntimeError(
+                f"MorphQL CLI error (exit code {result.returncode}): {msg}"
+            )
+
+        return result.stdout.decode(errors="replace").strip()
+
+    @classmethod
+    def _resolve_cli_command(cls, config: Dict[str, Any]) -> list:
+        if config["runtime"] == cls.RUNTIME_QJS:
+            return cls._resolve_qjs_command(config)
+
+        # 1. User-specified custom path
+        if config["cli_path"] != "morphql":
+            return [config["cli_path"]]
+
+        # 2. Bundled morphql.js (next to this package)
+        bundled = os.path.join(os.path.dirname(__file__), "..", "bin", "morphql.js")
+        bundled = os.path.normpath(bundled)
+        if os.path.isfile(bundled):
+            return [config["node_path"], bundled]
+
+        # 3. System-installed morphql binary
+        return [config["cli_path"]]
+
+    @classmethod
+    def _resolve_qjs_command(cls, config: Dict[str, Any]) -> list:
+        qjs_bin = config.get("qjs_path") or cls._maybe_install_qjs(config)
+
+        # Locate the JS bundle
+        bundle = os.path.normpath(
+            os.path.join(os.path.dirname(__file__), "..", "..", "..", "cli", "dist", "qjs", "qjs.js")
+        )
+        if not os.path.isfile(bundle):
+            bundle = os.path.normpath(
+                os.path.join(os.path.dirname(__file__), "..", "bin", "qjs.js")
+            )
+        if not os.path.isfile(bundle):
+            raise RuntimeError(
+                "MorphQL: QuickJS bundle not found. Run build:qjs or place it in bin/qjs.js"
+            )
+
+        return [qjs_bin, "--std", "-m", bundle]
+
+    @classmethod
+    def _maybe_install_qjs(cls, config: Dict[str, Any]) -> str:
+        system = platform.system().lower()
+        machine = platform.machine().lower()
+
+        if "windows" in system:
+            suffix = "-windows-x86_64.exe"
+        elif "darwin" in system:
+            suffix = "-darwin"
+        else:
+            suffix = "-linux-x86_64"
+
+        local_name = "qjs" + suffix
+
+        # 1. Bundled bin/
+        bundled = os.path.normpath(
+            os.path.join(os.path.dirname(__file__), "..", "bin", local_name)
+        )
+        if os.path.isfile(bundled):
+            return os.path.realpath(bundled)
+
+        # 2. Cache dir
+        cache_dir = cls._resolve_cache_dir(config)
+        cached = os.path.join(cache_dir, local_name)
+        if os.path.isfile(cached):
+            return os.path.realpath(cached)
+
+        # 3. Download
+        os.makedirs(cache_dir, exist_ok=True)
+        version = "v0.11.0"
+        url = f"https://github.com/quickjs-ng/quickjs/releases/download/{version}/{local_name}"
+        try:
+            cls._download_file(url, cached)
+            os.chmod(cached, 0o755)
+            return os.path.realpath(cached)
+        except Exception:
+            return "qjs"
+
+    @classmethod
+    def _download_file(cls, url: str, target: str) -> None:
+        try:
+            with urllib.request.urlopen(url, timeout=60) as response:
+                content = response.read()
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"MorphQL: Failed to download {url}: {e}")
+
+        if len(content) < 1000:
+            raise RuntimeError(f"MorphQL: Downloaded file too small from {url}")
+
+        with open(target, "wb") as f:
+            f.write(content)
+
+    @classmethod
+    def _resolve_cache_dir(cls, config: Dict[str, Any]) -> str:
+        if config.get("cache_dir"):
+            return config["cache_dir"]
+        return os.path.join(tempfile.gettempdir(), "morphql")
+
+    # ------------------------------------------------------------------
+    #  Server Provider
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _execute_via_server(
+        cls,
+        query: Optional[str],
+        data: Any,
+        config: Dict[str, Any],
+        query_file: Optional[str] = None,
+    ) -> str:
+        if query_file is not None:
+            with open(query_file, "r", encoding="utf-8") as f:
+                query = f.read().strip()
+
+        # Server expects decoded data, not raw JSON string
+        if isinstance(data, str):
+            try:
+                data = json.loads(data)
+            except (json.JSONDecodeError, ValueError):
+                pass
+
+        payload = json.dumps({"query": query, "data": data}).encode("utf-8")
+        url = config["server_url"].rstrip("/") + "/v1/execute"
+
+        headers = {"Content-Type": "application/json"}
+        if config.get("api_key"):
+            headers["X-API-KEY"] = config["api_key"]
+
+        req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
+
+        try:
+            with urllib.request.urlopen(req, timeout=int(config["timeout"])) as response:
+                body = response.read().decode("utf-8")
+        except urllib.error.HTTPError as e:
+            body = e.read().decode("utf-8", errors="replace")
+            raise RuntimeError(f"MorphQL server returned HTTP {e.code}: {body}")
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"MorphQL server unreachable: {url} — {e.reason}")
+
+        try:
+            response_data = json.loads(body)
+        except json.JSONDecodeError:
+            raise RuntimeError(f"MorphQL server returned invalid JSON: {body}")
+
+        if not response_data.get("success"):
+            msg = response_data.get("message", body)
+            raise RuntimeError(f"MorphQL server error: {msg}")
+
+        return response_data["result"]
+
+    # ------------------------------------------------------------------
+    #  Config Resolution
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _resolve_config(
+        cls,
+        options: Dict[str, Any],
+        defaults: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        config: Dict[str, Any] = {}
+        for key, hardcoded in cls._OPTION_DEFAULTS.items():
+            if key in options:
+                config[key] = options[key]
+            elif defaults and key in defaults:
+                config[key] = defaults[key]
+            else:
+                env_key = cls._ENV_MAP.get(key)
+                env_val = os.environ.get(env_key, "") if env_key else ""
+                if env_val:
+                    config[key] = env_val
+                else:
+                    config[key] = hardcoded
+        return config
+
+    # ------------------------------------------------------------------
+    #  Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _normalize_data(data: Any) -> str:
+        if data is None:
+            return "{}"
+        if isinstance(data, (dict, list)):
+            return json.dumps(data)
+        return str(data)
+
+    @staticmethod
+    def _validate_query_file(path: str) -> None:
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"MorphQL: query file not found: {path}")
+        if not os.access(path, os.R_OK):
+            raise PermissionError(f"MorphQL: query file not readable: {path}")

morphql-0.1.35/src/morphql.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: morphql
+Version: 0.1.35
+Summary: Python client for MorphQL — transform data with declarative queries.
+Author: Hyperwindmill
+License: MIT
+Project-URL: Homepage, https://github.com/Hyperwindmill/morphql
+Project-URL: Repository, https://github.com/Hyperwindmill/morphql
+Project-URL: Issues, https://github.com/Hyperwindmill/morphql/issues
+Keywords: morphql,transform,query,json,xml,edi,dsl
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# morphql · Python client
+
+Python client for [MorphQL](https://github.com/Hyperwindmill/morphql) — a declarative DSL for structural data transformation.
+
+Delegates execution to the MorphQL **CLI** or a running **MorphQL server**. Zero external dependencies. Python >= 3.8.
+
+## Installation
+
+```bash
+pip install morphql
+```
+
+## Quick start
+
+```python
+from morphql import MorphQL
+
+# One-shot static call (CLI provider)
+result = MorphQL.execute(
+    "from json to json transform set name = source.firstName",
+    data={"firstName": "Alice"},
+)
+print(result)  # {"name":"Alice"}
+
+# From a .morphql file
+result = MorphQL.execute_file("transform.morphql", data={"x": 1})
+
+# Instance with preset defaults (server provider)
+morph = MorphQL(provider="server", server_url="http://localhost:3000")
+result = morph.run("from json to json transform set x = source.x", data={"x": 42})
+result = morph.run_file("transform.morphql", data={"x": 42})
+```
+
+## Providers
+
+| Provider   | How it works                                      |
+|------------|---------------------------------------------------|
+| `"cli"`    | Runs `morphql` CLI via `subprocess` (default)     |
+| `"server"` | `POST {server_url}/v1/execute` via `urllib`       |
+
+## Options
+
+| Option       | Default                     | Env var               |
+|--------------|-----------------------------|-----------------------|
+| `provider`   | `"cli"`                     | `MORPHQL_PROVIDER`    |
+| `runtime`    | `"node"`                    | `MORPHQL_RUNTIME`     |
+| `cli_path`   | `"morphql"`                 | `MORPHQL_CLI_PATH`    |
+| `node_path`  | `"node"`                    | `MORPHQL_NODE_PATH`   |
+| `qjs_path`   | auto-resolved               | `MORPHQL_QJS_PATH`    |
+| `cache_dir`  | `$TMPDIR/morphql`           | `MORPHQL_CACHE_DIR`   |
+| `server_url` | `"http://localhost:3000"`   | `MORPHQL_SERVER_URL`  |
+| `api_key`    | `None`                      | `MORPHQL_API_KEY`     |
+| `timeout`    | `30` (seconds)              | `MORPHQL_TIMEOUT`     |
+
+Priority: call kwarg > instance default > env var > hardcoded default.
+
+## API
+
+### Static
+
+```python
+MorphQL.execute(query, data=None, **options) -> str
+MorphQL.execute_file(query_file, data=None, **options) -> str
+```
+
+### Instance
+
+```python
+morph = MorphQL(**defaults)
+morph.run(query, data=None, **options) -> str
+morph.run_file(query_file, data=None, **options) -> str
+```
+
+`data` accepts `str` (JSON), `dict`, `list`, or `None`.
+
+## Exceptions
+
+| Situation                  | Exception           |
+|----------------------------|---------------------|
+| `query` missing or empty   | `ValueError`        |
+| Query file not found       | `FileNotFoundError` |
+| CLI exits with error       | `RuntimeError`      |
+| Server HTTP error          | `RuntimeError`      |
+| Server unreachable         | `RuntimeError`      |
+
+## Running tests
+
+```bash
+cd packages/python
+PYTHONPATH=src python -m unittest discover tests/
+# or with pytest:
+pip install pytest
+pytest
+```
+
+## License
+
+MIT

morphql-0.1.35/src/morphql.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/morphql/__init__.py
+src/morphql/morphql.py
+src/morphql.egg-info/PKG-INFO
+src/morphql.egg-info/SOURCES.txt
+src/morphql.egg-info/dependency_links.txt
+src/morphql.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_server.py

morphql-0.1.35/src/morphql.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

morphql-0.1.35/src/morphql.egg-info/top_level.txt

@@ -0,0 +1 @@
+morphql

morphql-0.1.35/tests/test_cli.py

@@ -0,0 +1,307 @@
+import json
+import subprocess
+import unittest
+from unittest.mock import MagicMock, patch
+
+from morphql import MorphQL
+
+
+def _make_result(stdout: str = "", returncode: int = 0, stderr: str = "") -> MagicMock:
+    m = MagicMock()
+    m.stdout = stdout.encode()
+    m.stderr = stderr.encode()
+    m.returncode = returncode
+    return m
+
+
+class TestCliExecute(unittest.TestCase):
+    @patch("subprocess.run")
+    def test_execute_passes_query_flag(self, mock_run):
+        mock_run.return_value = _make_result('{"ok": true}')
+        result = MorphQL.execute("from json to json transform set x = x", '{"x":1}')
+        args = mock_run.call_args[0][0]
+        self.assertIn("-q", args)
+        self.assertEqual(result, '{"ok": true}')
+
+    @patch("subprocess.run")
+    def test_execute_passes_data_flag(self, mock_run):
+        mock_run.return_value = _make_result("result")
+        MorphQL.execute("from json to json transform set x = x", {"key": "val"})
+        args = mock_run.call_args[0][0]
+        self.assertIn("-i", args)
+        idx = args.index("-i")
+        self.assertEqual(json.loads(args[idx + 1]), {"key": "val"})
+
+    @patch("subprocess.run")
+    def test_execute_none_data_sends_empty_object(self, mock_run):
+        mock_run.return_value = _make_result("{}")
+        MorphQL.execute("from json to json transform set x = x")
+        args = mock_run.call_args[0][0]
+        idx = args.index("-i")
+        self.assertEqual(args[idx + 1], "{}")
+
+    @patch("subprocess.run")
+    def test_execute_raises_on_nonzero_exit(self, mock_run):
+        mock_run.return_value = _make_result("", returncode=1, stderr="syntax error")
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("bad query", "{}")
+        self.assertIn("syntax error", str(ctx.exception))
+
+    @patch("subprocess.run")
+    def test_execute_file_passes_Q_flag(self, mock_run):
+        mock_run.return_value = _make_result("ok")
+        import tempfile, os
+        with tempfile.NamedTemporaryFile(suffix=".morphql", delete=False, mode="w") as f:
+            f.write("from json to json transform set x = x")
+            path = f.name
+        try:
+            MorphQL.execute_file(path, "{}")
+            args = mock_run.call_args[0][0]
+            self.assertIn("-Q", args)
+            self.assertIn(path, args)
+        finally:
+            os.unlink(path)
+
+    def test_execute_file_raises_if_not_found(self):
+        with self.assertRaises(FileNotFoundError):
+            MorphQL.execute_file("/nonexistent/query.morphql")
+
+    def test_execute_raises_if_query_empty(self):
+        with self.assertRaises(ValueError):
+            MorphQL.execute("")
+
+    @patch("subprocess.run")
+    def test_instance_run_uses_preset_defaults(self, mock_run):
+        mock_run.return_value = _make_result("result")
+        morph = MorphQL(provider="cli")
+        morph.run("from json to json transform set x = x", "{}")
+        self.assertTrue(mock_run.called)
+
+    @patch("subprocess.run")
+    def test_node_no_warnings_env_set(self, mock_run):
+        mock_run.return_value = _make_result("ok")
+        MorphQL.execute("from json to json transform set x = x", "{}")
+        env = mock_run.call_args[1]["env"]
+        self.assertEqual(env.get("NODE_NO_WARNINGS"), "1")
+
+
+class TestCliRunFile(unittest.TestCase):
+    @patch("subprocess.run")
+    def test_run_file_passes_Q_flag(self, mock_run):
+        mock_run.return_value = _make_result("ok")
+        import tempfile, os
+        with tempfile.NamedTemporaryFile(suffix=".morphql", delete=False, mode="w") as f:
+            f.write("from json to json transform set x = x")
+            path = f.name
+        try:
+            morph = MorphQL(provider="cli")
+            morph.run_file(path, "{}")
+            args = mock_run.call_args[0][0]
+            self.assertIn("-Q", args)
+            self.assertIn(path, args)
+        finally:
+            os.unlink(path)
+
+    def test_run_file_raises_if_not_found(self):
+        morph = MorphQL(provider="cli")
+        with self.assertRaises(FileNotFoundError):
+            morph.run_file("/nonexistent/query.morphql")
+
+    def test_run_raises_if_query_empty(self):
+        morph = MorphQL(provider="cli")
+        with self.assertRaises(ValueError):
+            morph.run("")
+
+
+class TestCliErrorPaths(unittest.TestCase):
+    @patch("subprocess.run")
+    def test_timeout_raises_runtime_error(self, mock_run):
+        mock_run.side_effect = subprocess.TimeoutExpired(cmd=["morphql"], timeout=30)
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("from json to json transform set x = x", "{}")
+        self.assertIn("timed out", str(ctx.exception))
+
+    @patch("subprocess.run")
+    def test_cli_not_found_raises_runtime_error(self, mock_run):
+        mock_run.side_effect = FileNotFoundError()
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute(
+                "from json to json transform set x = x",
+                "{}",
+                cli_path="/no/such/binary",
+            )
+        self.assertIn("not found", str(ctx.exception))
+
+    @patch("subprocess.run")
+    def test_stderr_preferred_over_stdout_on_error(self, mock_run):
+        mock_run.return_value = _make_result("stdout msg", returncode=1, stderr="stderr msg")
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("bad query", "{}")
+        self.assertIn("stderr msg", str(ctx.exception))
+
+    @patch("subprocess.run")
+    def test_stdout_used_when_stderr_empty(self, mock_run):
+        mock_run.return_value = _make_result("stdout only", returncode=1, stderr="")
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("bad query", "{}")
+        self.assertIn("stdout only", str(ctx.exception))
+
+
+class TestQjsRuntime(unittest.TestCase):
+    """Tests for the QuickJS runtime path."""
+
+    @patch("subprocess.run")
+    @patch("os.path.isfile")
+    def test_qjs_command_uses_qjs_bin_and_bundle(self, mock_isfile, mock_run):
+        """When runtime=qjs and qjs_path is set, command must be [qjs_bin, --std, -m, bundle]."""
+        mock_run.return_value = _make_result("ok")
+        # Make isfile return True for the bundle path so it doesn't raise
+        mock_isfile.return_value = True
+
+        MorphQL.execute(
+            "from json to json transform set x = x",
+            "{}",
+            runtime="qjs",
+            qjs_path="/usr/bin/qjs",
+        )
+
+        args = mock_run.call_args[0][0]
+        self.assertEqual(args[0], "/usr/bin/qjs")
+        self.assertIn("--std", args)
+        self.assertIn("-m", args)
+
+    @patch("subprocess.run")
+    @patch("os.path.isfile")
+    def test_qjs_command_raises_if_bundle_not_found(self, mock_isfile, mock_run):
+        """RuntimeError raised when neither monorepo nor distributed bundle exists."""
+        mock_isfile.return_value = False
+
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute(
+                "from json to json transform set x = x",
+                "{}",
+                runtime="qjs",
+                qjs_path="/usr/bin/qjs",
+            )
+        self.assertIn("bundle not found", str(ctx.exception))
+
+    @patch("subprocess.run")
+    @patch("os.path.isfile")
+    @patch("platform.system", return_value="Linux")
+    @patch("platform.machine", return_value="x86_64")
+    def test_qjs_resolves_linux_binary_suffix(self, mock_machine, mock_system, mock_isfile, mock_run):
+        """On Linux, the bundled binary name must include -linux-x86_64."""
+        # First isfile call (bundled qjs bin) → True so it returns that path
+        # Second isfile call onwards (bundle .js) → True
+        def isfile_side_effect(path):
+            return True
+        mock_isfile.side_effect = isfile_side_effect
+        mock_run.return_value = _make_result("ok")
+
+        MorphQL.execute(
+            "from json to json transform set x = x",
+            "{}",
+            runtime="qjs",
+            # no qjs_path → must auto-resolve
+        )
+
+        args = mock_run.call_args[0][0]
+        # The resolved qjs binary path should contain the linux suffix
+        self.assertTrue(
+            any("linux-x86_64" in str(a) for a in args),
+            f"Expected linux-x86_64 in args: {args}",
+        )
+
+    @patch("morphql.morphql.MorphQL._download_file")
+    @patch("os.chmod")
+    @patch("os.makedirs")
+    @patch("os.path.isfile", return_value=False)
+    @patch("platform.system", return_value="Linux")
+    @patch("platform.machine", return_value="x86_64")
+    def test_qjs_falls_back_to_system_qjs_on_download_failure(
+        self, mock_machine, mock_system, mock_isfile, mock_makedirs, mock_chmod, mock_download
+    ):
+        """If download raises, _maybe_install_qjs must fall back to 'qjs'."""
+        mock_download.side_effect = RuntimeError("network error")
+
+        result = MorphQL._maybe_install_qjs({"cache_dir": None})
+        self.assertEqual(result, "qjs")
+
+    @patch("morphql.morphql.MorphQL._download_file")
+    @patch("os.chmod")
+    @patch("os.makedirs")
+    @patch("os.path.isfile", return_value=False)
+    @patch("platform.system", return_value="Linux")
+    @patch("platform.machine", return_value="x86_64")
+    def test_qjs_download_called_when_not_cached(
+        self, mock_machine, mock_system, mock_isfile, mock_makedirs, mock_chmod, mock_download
+    ):
+        """_download_file must be called with a GitHub URL when no local binary exists."""
+        MorphQL._maybe_install_qjs({"cache_dir": "/tmp/morphql-test"})
+        self.assertTrue(mock_download.called)
+        url = mock_download.call_args[0][0]
+        self.assertIn("quickjs-ng", url)
+        self.assertIn("linux-x86_64", url)
+
+    @patch("urllib.request.urlopen")
+    def test_download_file_raises_on_small_response(self, mock_urlopen):
+        """_download_file must raise RuntimeError if downloaded content is < 1000 bytes."""
+        m = MagicMock()
+        m.read.return_value = b"tiny"
+        m.__enter__ = lambda s: s
+        m.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = m
+
+        import tempfile, os
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            target = f.name
+        try:
+            with self.assertRaises(RuntimeError) as ctx:
+                MorphQL._download_file("https://example.com/qjs", target)
+            self.assertIn("too small", str(ctx.exception))
+        finally:
+            os.unlink(target)
+
+
+class TestConfigResolution(unittest.TestCase):
+    @patch("subprocess.run")
+    def test_env_var_used_as_fallback(self, mock_run):
+        mock_run.return_value = _make_result("ok")
+        import os
+        saved = os.environ.pop("MORPHQL_CLI_PATH", None)
+        os.environ["MORPHQL_CLI_PATH"] = "my-morphql-bin"
+        try:
+            MorphQL.execute("from json to json transform set x = x", "{}")
+            args = mock_run.call_args[0][0]
+            self.assertIn("my-morphql-bin", args)
+        finally:
+            del os.environ["MORPHQL_CLI_PATH"]
+            if saved is not None:
+                os.environ["MORPHQL_CLI_PATH"] = saved
+
+    @patch("subprocess.run")
+    def test_call_kwarg_overrides_instance_default(self, mock_run):
+        """provider='server' kwarg must override instance default provider='cli'."""
+        from unittest.mock import patch as mpatch
+
+        mock_run.return_value = _make_result("should_not_be_called")
+        response_mock = MagicMock()
+        response_mock.read.return_value = json.dumps(
+            {"success": True, "result": "server_result"}
+        ).encode()
+        response_mock.__enter__ = lambda s: s
+        response_mock.__exit__ = MagicMock(return_value=False)
+
+        morph = MorphQL(provider="cli")
+        with mpatch("urllib.request.urlopen", return_value=response_mock):
+            result = morph.run(
+                "from json to json transform set x = x",
+                "{}",
+                provider="server",
+            )
+        self.assertEqual(result, "server_result")
+        mock_run.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

morphql-0.1.35/tests/test_server.py

@@ -0,0 +1,150 @@
+import json
+import unittest
+from io import BytesIO
+from unittest.mock import MagicMock, patch
+
+from morphql import MorphQL
+
+
+def _make_response(body: dict, status: int = 200) -> MagicMock:
+    raw = json.dumps(body).encode()
+    m = MagicMock()
+    m.read.return_value = raw
+    m.status = status
+    m.__enter__ = lambda s: s
+    m.__exit__ = MagicMock(return_value=False)
+    return m
+
+
+class TestServerExecute(unittest.TestCase):
+    @patch("urllib.request.urlopen")
+    def test_execute_returns_result(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response({"success": True, "result": "hello"})
+        result = MorphQL.execute(
+            "from json to json transform set x = x",
+            '{"x": 1}',
+            provider="server",
+        )
+        self.assertEqual(result, "hello")
+
+    @patch("urllib.request.urlopen")
+    def test_payload_contains_query_and_data(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response({"success": True, "result": "ok"})
+        MorphQL.execute(
+            "from json to json transform set x = x",
+            {"a": 1},
+            provider="server",
+        )
+        req = mock_urlopen.call_args[0][0]
+        payload = json.loads(req.data)
+        self.assertEqual(payload["query"], "from json to json transform set x = x")
+        self.assertEqual(payload["data"], {"a": 1})
+
+    @patch("urllib.request.urlopen")
+    def test_json_string_data_is_decoded(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response({"success": True, "result": "ok"})
+        MorphQL.execute(
+            "from json to json transform set x = x",
+            '{"key": "value"}',
+            provider="server",
+        )
+        req = mock_urlopen.call_args[0][0]
+        payload = json.loads(req.data)
+        self.assertEqual(payload["data"], {"key": "value"})
+
+    @patch("urllib.request.urlopen")
+    def test_api_key_header_sent(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response({"success": True, "result": "ok"})
+        MorphQL.execute(
+            "from json to json transform set x = x",
+            "{}",
+            provider="server",
+            api_key="secret123",
+        )
+        req = mock_urlopen.call_args[0][0]
+        self.assertEqual(req.get_header("X-api-key"), "secret123")
+
+    @patch("urllib.request.urlopen")
+    def test_raises_on_success_false(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response(
+            {"success": False, "message": "bad query"}
+        )
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("bad", "{}", provider="server")
+        self.assertIn("bad query", str(ctx.exception))
+
+    @patch("urllib.request.urlopen")
+    def test_uses_correct_endpoint(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response({"success": True, "result": "ok"})
+        MorphQL.execute(
+            "from json to json transform set x = x",
+            "{}",
+            provider="server",
+            server_url="http://myhost:4000",
+        )
+        req = mock_urlopen.call_args[0][0]
+        self.assertEqual(req.full_url, "http://myhost:4000/v1/execute")
+
+    @patch("urllib.request.urlopen")
+    def test_instance_run_server(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response({"success": True, "result": "done"})
+        morph = MorphQL(provider="server", server_url="http://localhost:3000")
+        result = morph.run("from json to json transform set x = x", "{}")
+        self.assertEqual(result, "done")
+
+
+class TestServerErrorPaths(unittest.TestCase):
+    @patch("urllib.request.urlopen")
+    def test_http_error_raises_runtime_error(self, mock_urlopen):
+        import urllib.error
+        err = urllib.error.HTTPError(
+            url="http://localhost:3000/v1/execute",
+            code=500,
+            msg="Internal Server Error",
+            hdrs=None,
+            fp=BytesIO(b'{"message": "server crashed"}'),
+        )
+        mock_urlopen.side_effect = err
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("from json to json transform set x = x", "{}", provider="server")
+        self.assertIn("500", str(ctx.exception))
+
+    @patch("urllib.request.urlopen")
+    def test_url_error_raises_runtime_error(self, mock_urlopen):
+        import urllib.error
+        mock_urlopen.side_effect = urllib.error.URLError(reason="Connection refused")
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("from json to json transform set x = x", "{}", provider="server")
+        self.assertIn("unreachable", str(ctx.exception))
+
+    @patch("urllib.request.urlopen")
+    def test_invalid_json_response_raises_runtime_error(self, mock_urlopen):
+        m = MagicMock()
+        m.read.return_value = b"not json at all"
+        m.__enter__ = lambda s: s
+        m.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = m
+        with self.assertRaises(RuntimeError) as ctx:
+            MorphQL.execute("from json to json transform set x = x", "{}", provider="server")
+        self.assertIn("invalid JSON", str(ctx.exception))
+
+    @patch("urllib.request.urlopen")
+    def test_run_file_via_server(self, mock_urlopen):
+        mock_urlopen.return_value = _make_response({"success": True, "result": "file_result"})
+        import tempfile, os
+        with tempfile.NamedTemporaryFile(suffix=".morphql", delete=False, mode="w") as f:
+            f.write("from json to json transform set x = x")
+            path = f.name
+        try:
+            morph = MorphQL(provider="server")
+            result = morph.run_file(path, "{}")
+            self.assertEqual(result, "file_result")
+            req = mock_urlopen.call_args[0][0]
+            payload = json.loads(req.data)
+            self.assertIn("from json", payload["query"])
+        finally:
+            os.unlink(path)
+
+
+if __name__ == "__main__":
+    unittest.main()