opynrefine 0.1.0__tar.gz

opynrefine-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

opynrefine-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: opynrefine
+Version: 0.1.0
+Summary: Python client and CLI for the OpenRefine API
+Author: Spencer Norris
+Project-URL: Homepage, https://github.com/SpencerNorris/opynrefine
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# opynrefine
+
+Python 3.x client and CLI for working with the [OpenRefine API](https://openrefine.org/docs/technical-reference/openrefine-api).
+
+## Getting Started
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[test]
+```
+
+### CLI usage
+
+```bash
+opynrefine --base-url http://127.0.0.1:3333 list-projects
+opynrefine call core/get-models --params '{"project":"123"}'
+opynrefine create-project "New dataset" data.csv --format-hint text/line-based/*sv --options '{"separator":","}'
+opynrefine apply-operations 123 operations.json
+```
+
+## Tests
+
+Pytest-based tests include unit coverage and an integration test that exercises a running OpenRefine instance on `http://127.0.0.1:3333`. If OpenRefine is not running locally the integration test is skipped automatically.
+
+```bash
+pytest
+```

opynrefine-0.1.0/README.md

@@ -0,0 +1,28 @@
+# opynrefine
+
+Python 3.x client and CLI for working with the [OpenRefine API](https://openrefine.org/docs/technical-reference/openrefine-api).
+
+## Getting Started
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[test]
+```
+
+### CLI usage
+
+```bash
+opynrefine --base-url http://127.0.0.1:3333 list-projects
+opynrefine call core/get-models --params '{"project":"123"}'
+opynrefine create-project "New dataset" data.csv --format-hint text/line-based/*sv --options '{"separator":","}'
+opynrefine apply-operations 123 operations.json
+```
+
+## Tests
+
+Pytest-based tests include unit coverage and an integration test that exercises a running OpenRefine instance on `http://127.0.0.1:3333`. If OpenRefine is not running locally the integration test is skipped automatically.
+
+```bash
+pytest
+```

opynrefine-0.1.0/opynrefine/__init__.py

@@ -0,0 +1,9 @@
+"""Public export surface for opynrefine."""
+from .client import OpenRefineClient, OpenRefineResponse, build_cli_parser, main
+
+__all__ = [
+    "OpenRefineClient",
+    "OpenRefineResponse",
+    "build_cli_parser",
+    "main",
+]

opynrefine-0.1.0/opynrefine/client.py

@@ -0,0 +1,476 @@
+"""
+OpenRefine API client and CLI entry point.
+Documentation for OpenRefine API: https://openrefine.org/docs/technical-reference/openrefine-api
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import signal
+import sys
+import threading
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Optional
+from urllib.parse import parse_qs, urlparse
+
+import requests
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Configure a sane default logging setup if the app has not done so."""
+    if not logging.getLogger().handlers:
+        logging.basicConfig(
+            level=level,
+            format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        )
+    LOGGER.setLevel(level)
+
+
+@dataclass
+class OpenRefineResponse:
+    """Simple wrapper that exposes the low-level :class:`requests.Response`."""
+
+    response: requests.Response
+
+    def json(self) -> Any:
+        return self.response.json()
+
+    @property
+    def text(self) -> str:
+        return self.response.text
+
+    @property
+    def content(self) -> bytes:
+        return self.response.content
+
+
+class CommandProxy:
+    """Fluent builder for OpenRefine command paths."""
+
+    def __init__(self, client: "OpenRefineClient", parts: Optional[Iterable[str]] = None):
+        self._client = client
+        self._parts = list(parts or [])
+
+    def __getattr__(self, attr: str) -> "CommandProxy":
+        if attr.startswith("_"):
+            raise AttributeError(attr)
+        return CommandProxy(self._client, self._parts + [attr.replace("_", "-")])
+
+    def __call__(
+        self,
+        *,
+        method: str = "GET",
+        expect_json: bool = True,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Any] = None,
+        json_body: Optional[Any] = None,
+        files: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> Any:
+        path = "/".join(self._parts)
+        return self._client._request(
+            path,
+            method=method,
+            expect_json=expect_json,
+            params=params,
+            data=data,
+            json_body=json_body,
+            files=files,
+            headers=headers,
+            timeout=timeout,
+        )
+
+
+class OpenRefineClient:
+    """Object-oriented wrapper for the OpenRefine HTTP API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:3333",
+        *,
+        session: Optional[requests.Session] = None,
+        timeout: int = 60,
+        logger: Optional[logging.Logger] = None,
+        auto_register_signals: bool = True,
+    ) -> None:
+        self.base_url = self._normalize_base_url(base_url)
+        self.session = session or requests.Session()
+        self.timeout = timeout
+        self.logger = logger or LOGGER
+        self._stop_event = threading.Event()
+        self._signal_handlers: Dict[int, Any] = {}
+        self._csrf_token: Optional[str] = None
+        if auto_register_signals:
+            self.register_signal_handlers(signal.SIGINT, signal.SIGTERM)
+
+    @property
+    def command(self) -> CommandProxy:
+        return CommandProxy(self)
+
+    def register_signal_handlers(self, *signals_to_handle: signal.Signals) -> None:
+        for sig in signals_to_handle:
+            try:
+                self._signal_handlers[sig] = signal.signal(sig, self._handle_signal)  # type: ignore[assignment]
+            except (ValueError, OSError):  # pragma: no cover - not hit on Windows CI typically
+                self.logger.debug("Unable to register handler for %s", sig)
+
+    def unregister_signal_handlers(self) -> None:
+        for sig, handler in self._signal_handlers.items():
+            try:
+                signal.signal(sig, handler)
+            except (ValueError, OSError):  # pragma: no cover - best effort only
+                self.logger.debug("Unable to restore original handler for %s", sig)
+        self._signal_handlers.clear()
+
+    def close(self) -> None:
+        self.unregister_signal_handlers()
+        self.session.close()
+
+    # Public helper methods -------------------------------------------------
+    def list_projects(self) -> Dict[str, Any]:
+        """Return metadata for all projects."""
+        return self.command.core.get_all_project_metadata()
+
+    def delete_project(self, project_id: str) -> Dict[str, Any]:
+        return self.command.core.delete_project(params={"project": project_id})
+
+    def get_models(self, project_id: str) -> Dict[str, Any]:
+        return self.command.core.get_models(params={"project": project_id})
+
+    def get_rows(self, project_id: str, **options: Any) -> Dict[str, Any]:
+        params = {"project": project_id, **options}
+        return self.command.core.get_rows(params=params)
+
+    def export_rows(self, project_id: str, export_format: str = "tsv", **options: Any) -> str:
+        params = {"project": project_id, "format": export_format, **options}
+        return self.command.core.export_rows(params=params, expect_json=False).text
+
+    def apply_operations(self, project_id: str, operations: Any) -> Dict[str, Any]:
+        payload = json.dumps(operations)
+        return self.command.core.apply_operations(
+            method="POST",
+            data={"project": project_id, "operations": payload},
+        )
+
+    def compute_facets(self, project_id: str, facets: Any) -> Dict[str, Any]:
+        payload = json.dumps(facets)
+        return self.command.core.compute_facets(
+            method="POST",
+            data={"project": project_id, "engine": payload},
+        )
+
+    def create_project_from_url(self, project_name: str, data_url: str, format_options: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        data = {
+            "projectName": project_name,
+            "format": (format_options or {}).get("format"),
+            "options": json.dumps(format_options or {}),
+            "url": data_url,
+        }
+        return self.command.core.create_project_from_url(method="POST", data=data)
+
+    def create_project_from_upload(
+        self,
+        project_name: str,
+        file_path: str,
+        *,
+        format_hint: Optional[str] = None,
+        format_options: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        options_payload = json.dumps(format_options or {}) if format_options else None
+        filename = os.path.basename(file_path)
+        with open(file_path, "rb") as handle:
+            files = {"project-file": (filename, handle)}
+            data: Dict[str, Any] = {"project-name": project_name}
+            if format_hint:
+                data["format"] = format_hint
+            if options_payload:
+                data["options"] = options_payload
+            response = self.command.core.create_project_from_upload(
+                method="POST",
+                data=data,
+                files=files,
+                expect_json=False,
+            )
+        project_id = self._extract_project_id(response.response.url)
+        return {
+            "project_id": project_id,
+            "project_url": response.response.url,
+            "html": response.text,
+        }
+
+    def execute_command(
+        self,
+        command_path: str,
+        *,
+        method: str = "GET",
+        expect_json: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute an arbitrary command path."""
+        return self._request(command_path, method=method, expect_json=expect_json, **kwargs)
+
+    # Internal helpers ------------------------------------------------------
+    def _handle_signal(self, signum: int, frame: Any) -> None:
+        try:
+            name = signal.Signals(signum).name
+        except ValueError:  # pragma: no cover - defensive
+            name = str(signum)
+        self.logger.warning("Received %s signal; aborting new requests", name)
+        self._stop_event.set()
+
+    def _build_url(self, command: str) -> str:
+        command = command.lstrip("/")
+        if not command.startswith("command/"):
+            command = f"command/{command}"
+        return f"{self.base_url}/{command}"
+
+    @staticmethod
+    def _normalize_base_url(value: str) -> str:
+        value = value.rstrip("/")
+        if not value.startswith(("http://", "https://")):
+            value = f"http://{value}"
+        return value
+
+    def _ensure_not_interrupted(self) -> None:
+        if self._stop_event.is_set():
+            raise RuntimeError("OpenRefine client interrupted by signal")
+
+    def _request(
+        self,
+        command: str,
+        *,
+        method: str = "GET",
+        expect_json: bool = True,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Any] = None,
+        json_body: Optional[Any] = None,
+        files: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> Any:
+        self._ensure_not_interrupted()
+        url = self._build_url(command)
+        self.logger.debug("%s %s params=%s", method.upper(), url, params)
+        method_upper = method.upper()
+        params = self._maybe_inject_csrf_token_query(params, method_upper)
+        data = self._maybe_inject_csrf_token_form(data, method_upper)
+        json_body = self._maybe_inject_csrf_token_json(json_body, method_upper)
+        response = self.session.request(
+            method=method,
+            url=url,
+            params=params,
+            data=data,
+            json=json_body,
+            files=files,
+            headers=headers,
+            timeout=timeout or self.timeout,
+        )
+        self.logger.info("%s %s -> %s", method.upper(), url, response.status_code)
+        response.raise_for_status()
+        if expect_json:
+            try:
+                return response.json()
+            except ValueError:
+                self.logger.debug("Response did not contain JSON, returning raw text")
+                return response.text
+        return OpenRefineResponse(response)
+
+    @staticmethod
+    def _extract_project_id(url: str) -> Optional[str]:
+        try:
+            parsed = urlparse(url)
+        except ValueError:
+            return None
+        project_param = parse_qs(parsed.query).get("project")
+        if not project_param:
+            return None
+        return project_param[0]
+
+    def _ensure_csrf_token(self) -> str:
+        if not self._csrf_token:
+            self._csrf_token = self._fetch_csrf_token()
+        return self._csrf_token
+
+    def _fetch_csrf_token(self) -> str:
+        url = f"{self.base_url}/command/core/get-csrf-token"
+        response = self.session.get(url, timeout=self.timeout)
+        response.raise_for_status()
+        payload = response.json()
+        token = payload.get("token")
+        if not token:
+            raise RuntimeError("Failed to obtain CSRF token from OpenRefine")
+        return token
+
+    def _maybe_inject_csrf_token_form(self, data: Optional[Any], method: str) -> Optional[Any]:
+        if method in {"GET", "HEAD"}:
+            return data
+        token = self._ensure_csrf_token()
+        if data is None:
+            return {"csrf_token": token}
+        if isinstance(data, dict):
+            if "csrf_token" not in data:
+                data = dict(data)
+                data["csrf_token"] = token
+            return data
+        if isinstance(data, list):
+            if not any(k == "csrf_token" for k, _ in data):
+                data = list(data)
+                data.append(("csrf_token", token))
+            return data
+        return data
+
+    def _maybe_inject_csrf_token_json(self, json_body: Optional[Any], method: str) -> Optional[Any]:
+        if method in {"GET", "HEAD"} or json_body is None:
+            return json_body
+        token = self._ensure_csrf_token()
+        if isinstance(json_body, dict) and "csrf_token" not in json_body:
+            json_body = dict(json_body)
+            json_body["csrf_token"] = token
+        return json_body
+
+    def _maybe_inject_csrf_token_query(self, params: Optional[Dict[str, Any]], method: str) -> Optional[Dict[str, Any]]:
+        if method in {"GET", "HEAD"}:
+            return params
+        token = self._ensure_csrf_token()
+        if not params:
+            return {"csrf_token": token}
+        if "csrf_token" not in params:
+            params = dict(params)
+            params["csrf_token"] = token
+        return params
+
+
+def _parse_kv_json(value: Optional[str]) -> Optional[Dict[str, Any]]:
+    if not value:
+        return None
+    try:
+        parsed = json.loads(value)
+        if not isinstance(parsed, dict):
+            raise ValueError("Expected a JSON object")
+        return parsed
+    except json.JSONDecodeError as exc:  # pragma: no cover - CLI-only path
+        raise SystemExit(f"Invalid JSON payload provided: {exc}") from exc
+
+
+def _load_json_file(path: str) -> Any:
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            return json.load(handle)
+    except FileNotFoundError as exc:  # pragma: no cover - CLI path
+        raise SystemExit(f"Operations file not found: {path}") from exc
+    except json.JSONDecodeError as exc:  # pragma: no cover
+        raise SystemExit(f"Invalid JSON in {path}: {exc}") from exc
+
+
+def build_cli_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Minimal CLI for the OpenRefine API client")
+    parser.add_argument("--base-url", default="http://127.0.0.1:3333", help="OpenRefine server base URL")
+    parser.add_argument("--timeout", type=int, default=60, help="Request timeout in seconds")
+    parser.add_argument("--log-level", default="INFO", help="Python logging level (default: INFO)")
+
+    subparsers = parser.add_subparsers(dest="action", required=True)
+
+    list_parser = subparsers.add_parser("list-projects", help="List available projects")
+    list_parser.set_defaults(func=_cli_list_projects)
+
+    delete_parser = subparsers.add_parser("delete-project", help="Delete a project by id")
+    delete_parser.add_argument("project_id")
+    delete_parser.set_defaults(func=_cli_delete_project)
+
+    call_parser = subparsers.add_parser("call", help="Execute an arbitrary OpenRefine command")
+    call_parser.add_argument("command_path", help="Path following the /command/ prefix, e.g. core/get-models")
+    call_parser.add_argument("--method", default="GET", help="HTTP method to use")
+    call_parser.add_argument("--params", help="JSON object of query params")
+    call_parser.add_argument("--data", help="JSON object of form data to send")
+    call_parser.add_argument("--expect-json", action="store_true", help="Expect JSON in response (default true)")
+    call_parser.add_argument(
+        "--no-expect-json",
+        dest="expect_json",
+        action="store_false",
+        help="Return raw response wrapper",
+    )
+    call_parser.set_defaults(expect_json=True, func=_cli_call)
+
+    create_parser = subparsers.add_parser("create-project", help="Create a new project from a file upload")
+    create_parser.add_argument("project_name", help="Name for the new project")
+    create_parser.add_argument("file_path", help="Path to the data file to upload")
+    create_parser.add_argument("--format-hint", help="Optional MIME hint like text/line-based/*sv")
+    create_parser.add_argument("--options", help="JSON string of format-specific options")
+    create_parser.set_defaults(func=_cli_create_project)
+
+    apply_parser = subparsers.add_parser("apply-operations", help="Apply a JSON operations file to a project")
+    apply_parser.add_argument("project_id", help="Target project id")
+    apply_parser.add_argument("operations_file", help="Path to the operations JSON file")
+    apply_parser.set_defaults(func=_cli_apply_operations)
+
+    return parser
+
+
+def _cli_list_projects(client: OpenRefineClient, _: argparse.Namespace) -> None:
+    projects = client.list_projects()
+    json.dump(projects, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def _cli_delete_project(client: OpenRefineClient, args: argparse.Namespace) -> None:
+    result = client.delete_project(args.project_id)
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def _cli_call(client: OpenRefineClient, args: argparse.Namespace) -> None:
+    params = _parse_kv_json(args.params)
+    data = _parse_kv_json(args.data)
+    result = client.execute_command(
+        args.command_path,
+        method=args.method,
+        params=params,
+        data=data,
+        expect_json=args.expect_json,
+    )
+    if isinstance(result, OpenRefineResponse):
+        sys.stdout.write(result.text)
+    else:
+        json.dump(result, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+
+
+def _cli_create_project(client: OpenRefineClient, args: argparse.Namespace) -> None:
+    options = _parse_kv_json(args.options)
+    result = client.create_project_from_upload(
+        args.project_name,
+        args.file_path,
+        format_hint=args.format_hint,
+        format_options=options,
+    )
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def _cli_apply_operations(client: OpenRefineClient, args: argparse.Namespace) -> None:
+    operations = _load_json_file(args.operations_file)
+    result = client.apply_operations(args.project_id, operations)
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = build_cli_parser()
+    args = parser.parse_args(argv)
+    configure_logging(getattr(logging, args.log_level.upper(), logging.INFO))
+    client = OpenRefineClient(base_url=args.base_url, timeout=args.timeout)
+    try:
+        args.func(client, args)
+    finally:
+        client.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

opynrefine-0.1.0/opynrefine.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: opynrefine
+Version: 0.1.0
+Summary: Python client and CLI for the OpenRefine API
+Author: Spencer Norris
+Project-URL: Homepage, https://github.com/SpencerNorris/opynrefine
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# opynrefine
+
+Python 3.x client and CLI for working with the [OpenRefine API](https://openrefine.org/docs/technical-reference/openrefine-api).
+
+## Getting Started
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[test]
+```
+
+### CLI usage
+
+```bash
+opynrefine --base-url http://127.0.0.1:3333 list-projects
+opynrefine call core/get-models --params '{"project":"123"}'
+opynrefine create-project "New dataset" data.csv --format-hint text/line-based/*sv --options '{"separator":","}'
+opynrefine apply-operations 123 operations.json
+```
+
+## Tests
+
+Pytest-based tests include unit coverage and an integration test that exercises a running OpenRefine instance on `http://127.0.0.1:3333`. If OpenRefine is not running locally the integration test is skipped automatically.
+
+```bash
+pytest
+```

opynrefine-0.1.0/opynrefine.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+opynrefine/__init__.py
+opynrefine/client.py
+opynrefine.egg-info/PKG-INFO
+opynrefine.egg-info/SOURCES.txt
+opynrefine.egg-info/dependency_links.txt
+opynrefine.egg-info/entry_points.txt
+opynrefine.egg-info/requires.txt
+opynrefine.egg-info/top_level.txt
+tests/test_client.py

opynrefine-0.1.0/opynrefine.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opynrefine-0.1.0/opynrefine.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opynrefine = opynrefine.client:main

opynrefine-0.1.0/opynrefine.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.31
+
+[test]
+pytest>=7

opynrefine-0.1.0/opynrefine.egg-info/top_level.txt

@@ -0,0 +1 @@
+opynrefine

opynrefine-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=67", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opynrefine"
+version = "0.1.0"
+description = "Python client and CLI for the OpenRefine API"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "Spencer Norris" }
+]
+dependencies = [
+  "requests>=2.31",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=7",
+]
+
+[project.urls]
+Homepage = "https://github.com/SpencerNorris/opynrefine"
+
+[project.scripts]
+opynrefine = "opynrefine.client:main"
+
+[tool.pytest.ini_options]
+markers = [
+  "integration: tests that require a running OpenRefine server on http://127.0.0.1:3333",
+]

opynrefine-0.1.0/setup.cfg

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

opynrefine-0.1.0/tests/test_client.py

@@ -0,0 +1,125 @@
+import json
+import signal
+
+import pytest
+import requests
+
+from opynrefine.client import OpenRefineClient, OpenRefineResponse
+
+
+class DummyResponse:
+    def __init__(self, data=None, *, text="", status_code=200, url="http://example/command"):
+        self._data = data
+        self.text = text or (json.dumps(data) if data is not None else "")
+        self.status_code = status_code
+        self.url = url
+        self.content = self.text.encode()  # mimic requests API
+
+    def json(self):
+        if self._data is None:
+            raise ValueError("No JSON available")
+        return self._data
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            raise requests.HTTPError(response=self)
+
+
+class DummySession:
+    def __init__(self, response, csrf_response=None):
+        self._response = response
+        self._csrf_response = csrf_response or DummyResponse({"token": "csrf"})
+        self.last_request = None
+        self.last_get = None
+
+    def request(self, method, url, **kwargs):
+        self.last_request = (method, url, kwargs)
+        return self._response
+
+    def get(self, url, **kwargs):
+        self.last_get = (url, kwargs)
+        return self._csrf_response
+
+    def close(self):
+        return None
+
+
+def test_command_proxy_executes_normalized_path():
+    response = DummyResponse({"ok": True})
+    session = DummySession(response)
+    client = OpenRefineClient("http://example", session=session, auto_register_signals=False)
+
+    result = client.command.core.get_all_project_metadata(params={"foo": "bar"})
+
+    assert result == {"ok": True}
+    method, url, kwargs = session.last_request
+    assert method == "GET"
+    assert url == "http://example/command/core/get-all-project-metadata"
+    assert kwargs["params"] == {"foo": "bar"}
+
+
+def test_signal_interrupt_blocks_requests():
+    response = DummyResponse({"ok": True})
+    session = DummySession(response)
+    client = OpenRefineClient("http://example", session=session, auto_register_signals=False)
+
+    client._handle_signal(signal.SIGINT, None)
+
+    with pytest.raises(RuntimeError):
+        client.command.core.get_models()
+
+
+def test_raw_response_wrapper_returned_when_requested():
+    response = DummyResponse(text="plain text")
+    session = DummySession(response)
+    client = OpenRefineClient("http://example", session=session, auto_register_signals=False)
+
+    result = client.command.core.export_rows(expect_json=False)
+
+    assert isinstance(result, OpenRefineResponse)
+    assert result.text == "plain text"
+
+
+def test_create_project_from_upload_returns_metadata(tmp_path):
+    project_file = tmp_path / "test.csv"
+    project_file.write_text("foo,bar\n1,2\n", encoding="utf-8")
+    response = DummyResponse(text="<html />", url="http://example/project?project=123")
+    session = DummySession(response, csrf_response=DummyResponse({"token": "abc"}))
+    client = OpenRefineClient("http://example", session=session, auto_register_signals=False)
+
+    result = client.create_project_from_upload(
+        "Example Project",
+        str(project_file),
+        format_hint="text/line-based/*sv",
+        format_options={"separator": ","},
+    )
+
+    assert result["project_id"] == "123"
+    assert session.last_get[0] == "http://example/command/core/get-csrf-token"
+    method, url, kwargs = session.last_request
+    assert method == "POST"
+    assert url == "http://example/command/core/create-project-from-upload"
+    assert kwargs["data"]["project-name"] == "Example Project"
+    assert kwargs["data"]["format"] == "text/line-based/*sv"
+    assert json.loads(kwargs["data"]["options"]) == {"separator": ","}
+    assert kwargs["data"]["csrf_token"] == "abc"
+    assert kwargs["params"]["csrf_token"] == "abc"
+    assert kwargs["files"]["project-file"][0] == "test.csv"
+
+
+def test_base_url_without_scheme_is_normalized():
+    client = OpenRefineClient("127.0.0.1:3333", session=DummySession(DummyResponse({})), auto_register_signals=False)
+    assert client.base_url == "http://127.0.0.1:3333"
+
+
+@pytest.mark.integration
+def test_list_projects_against_local_instance():
+    client = OpenRefineClient()
+    try:
+        projects = client.list_projects()
+    except requests.exceptions.RequestException as exc:
+        pytest.skip(f"OpenRefine not running: {exc}")
+    finally:
+        client.close()
+
+    assert isinstance(projects, dict)