sparql-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparql-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: CLI tool for querying SPARQL endpoints
 Project-URL: Homepage, https://github.com/vladistan/sparql-cli
 Project-URL: Repository, https://github.com/vladistan/sparql-cli

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/config.example.toml

@@ -13,6 +13,17 @@ url = "https://dbpedia.org/sparql"
 endpoint_type = "virtuoso"
 timeout = 30.0
 
+# --- Writable Endpoint Example ---
+# For endpoints that support SPARQL UPDATE (INSERT, DELETE, LOAD, etc.),
+# set update_url to the update endpoint. If omitted, sparql-cli derives it:
+# 1. Explicit update_url (if set)
+# 2. Replace /query with /update in the endpoint URL
+# 3. Use the endpoint URL as-is (fallback)
+[endpoints.fuseki-local]
+url = "http://localhost:3030/dataset/query"
+# update_url = "http://localhost:3030/dataset/update"  # auto-derived from url
+timeout = 30.0
+
 [endpoints.uniprot]
 url = "https://sparql.uniprot.org/sparql"
 endpoint_type = "generic"

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/pyproject.toml

@@ -2,12 +2,9 @@
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
-[tool.hatch.build.targets.wheel]
-packages = ["sparql"]
-
 [project]
 name = "sparql-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "CLI tool for querying SPARQL endpoints"
 readme = "README.md"
 authors = [
@@ -32,13 +29,16 @@ dev = [
   "ruff>=0.1.0"
 ]
 
+[project.scripts]
+sparql = "sparql.cli.main:app"
+
 [project.urls]
 Homepage = "https://github.com/vladistan/sparql-cli"
 Repository = "https://github.com/vladistan/sparql-cli"
 Issues = "https://github.com/vladistan/sparql-cli/issues"
 
-[project.scripts]
-sparql = "sparql.cli.main:app"
+[tool.hatch.build.targets.wheel]
+packages = ["sparql"]
 
 [tool.mypy]
 python_version = "3.13"

sparql_cli-0.1.4/sparql/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.3"

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/sparql/cli/commands/query.py

@@ -186,6 +186,7 @@ def query(
         username=resolved.username,
         password=resolved.password,
         digest_auth=resolved.auth_type == AuthType.DIGEST,
+        http_method=resolved.http_method.value,
     )
 
     # Resolve output format with precedence:

sparql_cli-0.1.4/sparql/cli/commands/update.py

@@ -0,0 +1,171 @@
+"""Update command for executing SPARQL UPDATE operations against endpoints."""
+
+import sys
+
+import sentry_sdk
+import typer
+
+from sparql._version import __version__
+from sparql.core.client import SPARQLClient
+from sparql.core.config import AuthType, load_config, resolve_config
+from sparql.core.exceptions import ConfigError, NetworkError
+from sparql.core.exceptions import TimeoutError as SPARQLTimeoutError
+from sparql.core.exit_codes import ExitCode
+from sparql.core.logging import get_logger
+from sparql.core.query_source import resolve_query_source
+
+
+def _get_global_options(
+    ctx: typer.Context | None,
+) -> tuple[str | None, str | None]:
+    if ctx and ctx.obj:
+        return (
+            ctx.obj.get("profile"),
+            ctx.obj.get("endpoint"),
+        )
+    return None, None
+
+
+def update(
+    ctx: typer.Context,
+    update_file: str | None = typer.Argument(  # noqa: B008
+        None,
+        help="SPARQL update file (.ru) or inline update string",
+    ),
+    endpoint: str | None = typer.Option(  # noqa: B008
+        None,
+        "--endpoint",
+        "-E",
+        help="SPARQL endpoint URL (overrides config)",
+    ),
+    profile: str | None = typer.Option(  # noqa: B008
+        None,
+        "--profile",
+        "-P",
+        help="Use named endpoint profile from config",
+    ),
+    execute: str | None = typer.Option(  # noqa: B008
+        None,
+        "--execute",
+        "-e",
+        help="Execute inline SPARQL update",
+    ),
+    timeout: float | None = typer.Option(  # noqa: B008
+        None,
+        "--timeout",
+        "-t",
+        help="Update timeout in seconds (overrides config)",
+    ),
+    user: str | None = typer.Option(  # noqa: B008
+        None,
+        "--user",
+        "-u",
+        help="Username for authentication (overrides config)",
+    ),
+    password: str | None = typer.Option(  # noqa: B008
+        None,
+        "--password",
+        "-p",
+        help="Password for authentication (overrides config)",
+    ),
+    digest_auth: bool = typer.Option(  # noqa: B008
+        False,
+        "--digest",
+        help="Use HTTP Digest Authentication instead of Basic",
+    ),
+    verbose: bool = typer.Option(  # noqa: B008
+        False,
+        "--verbose",
+        help="Show endpoint and update before execution",
+    ),
+) -> None:
+    """Execute a SPARQL UPDATE operation against an endpoint.
+
+    Update can be provided via file, -e inline, or stdin.
+    Sends POST with Content-Type: application/sparql-update.
+    """
+    stdin = None
+    if not sys.stdin.isatty():
+        stdin = sys.stdin
+
+    try:
+        update_text = resolve_query_source(
+            inline=execute,
+            file_path=update_file,
+            stdin=stdin,
+        )
+    except ConfigError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(ExitCode.INPUT_ERROR) from e
+
+    # Merge global options (command-specific takes precedence)
+    global_profile, global_endpoint = _get_global_options(ctx)
+    profile = profile or global_profile
+    endpoint = endpoint or global_endpoint
+
+    # Resolve configuration with precedence
+    try:
+        config = load_config()
+        cli_auth_type = AuthType.DIGEST if digest_auth else None
+        resolved = resolve_config(
+            config,
+            profile=profile,
+            cli_endpoint=endpoint,
+            cli_timeout=timeout,
+            cli_username=user,
+            cli_password=password,
+            cli_auth_type=cli_auth_type,
+        )
+    except ConfigError as e:
+        typer.echo(f"Config error: {e}", err=True)
+        raise typer.Exit(ExitCode.CONFIG_ERROR) from e
+
+    logger = get_logger("update")
+
+    if verbose:
+        typer.echo(f"Update endpoint: {resolved.update_endpoint}", err=True)
+        typer.echo(f"Timeout: {resolved.timeout}s", err=True)
+        typer.echo("Update:", err=True)
+        typer.echo(update_text, err=True)
+        typer.echo("---", err=True)
+
+    client = SPARQLClient(
+        endpoint_url=resolved.endpoint,
+        timeout=resolved.timeout,
+        user_agent=resolved.user_agent or f"sparql-cli/{__version__}",
+        username=resolved.username,
+        password=resolved.password,
+        digest_auth=resolved.auth_type == AuthType.DIGEST,
+        http_method=resolved.http_method.value,
+    )
+
+    logger.debug(
+        "update.execute",
+        endpoint=resolved.update_endpoint,
+        update_bytes=len(update_text),
+    )
+
+    try:
+        with sentry_sdk.start_span(
+            op="sparql.update", name="SPARQL UPDATE"
+        ):
+            result = client.execute_update(
+                update_text, resolved.update_endpoint
+            )
+
+        if result.success:
+            typer.echo(f"Update successful (HTTP {result.status_code})")
+            logger.debug("update.complete", status_code=result.status_code)
+        else:
+            typer.echo(
+                f"Update failed (HTTP {result.status_code}): "
+                f"{result.message}",
+                err=True,
+            )
+            raise typer.Exit(ExitCode.NETWORK_ERROR)
+    except SPARQLTimeoutError as e:
+        typer.echo(f"Timeout: {e}", err=True)
+        raise typer.Exit(ExitCode.TIMEOUT) from e
+    except NetworkError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(ExitCode.NETWORK_ERROR) from e

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/sparql/cli/main.py

@@ -17,6 +17,7 @@ from sparql.cli.commands.convenience import (
     predicates,
 )
 from sparql.cli.commands.query import query
+from sparql.cli.commands.update import update
 from sparql.core.logging import setup_logging
 from sparql.core.monitoring import setup_sentry
 
@@ -152,6 +153,7 @@ def test_sentry() -> None:
 
 # Register commands
 app.command()(query)
+app.command()(update)
 app.command()(graphs)
 app.command()(classes)
 app.command()(predicates)

sparql_cli-0.1.4/sparql/core/client.py

@@ -0,0 +1,227 @@
+"""SPARQL endpoint client using httpx."""
+
+import re
+from collections.abc import Iterator
+
+import httpx
+import sentry_sdk
+
+from sparql.core.exceptions import NetworkError
+from sparql.core.exceptions import TimeoutError as SPARQLTimeoutError
+from sparql.core.logging import get_logger
+from sparql.core.models import BindingValue, QueryResult, UpdateResult
+
+
+def _is_rdf_query(query: str) -> bool:
+    """Detect if query is CONSTRUCT or DESCRIBE (returns RDF graph)."""
+    query_upper = query.strip().upper()
+    # Match CONSTRUCT or DESCRIBE at start (after optional PREFIX declarations)
+    return bool(re.search(r"\b(CONSTRUCT|DESCRIBE)\b", query_upper))
+
+
+class SPARQLClient:
+    """Executes SPARQL queries against remote endpoints.
+
+    Supports both GET and POST methods. GET is required for some endpoints
+    (e.g., Virtuoso), while POST is standard for most SPARQL endpoints.
+    """
+
+    def __init__(
+        self,
+        endpoint_url: str,
+        timeout: float,
+        user_agent: str,
+        username: str | None = None,
+        password: str | None = None,
+        digest_auth: bool = False,
+        http_method: str = "POST",
+    ) -> None:
+        self.endpoint_url = endpoint_url
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self.http_method = http_method
+        self._logger = get_logger("client")
+        self.auth: httpx.DigestAuth | tuple[str, str] | None = None
+        if username and password:
+            if digest_auth:
+                self.auth = httpx.DigestAuth(username, password)
+            else:
+                self.auth = (username, password)
+
+    def _http_error_message(self, e: httpx.HTTPStatusError) -> str:
+        """Build diagnostic context from HTTP status, redirects, and response body."""
+        msg = f"HTTP {e.response.status_code} from {self.endpoint_url}"
+        if e.response.status_code == 302:
+            location = e.response.headers.get("Location", "")
+            if location:
+                msg += f"\nRedirect to: {location[:200]}"
+                msg += "\n(Endpoint redirected - may not support this query)"
+        elif e.response.status_code in (400, 500):
+            body = e.response.text[:500] if e.response.text else ""
+            if body:
+                msg += f"\nResponse: {body}"
+        return msg
+
+    def execute(self, query: str) -> Iterator[QueryResult]:
+        """Execute SELECT/ASK query returning tabular results.
+
+        Yields QueryResult objects with bindings. First result includes
+        variable ordering from head.vars. Subsequent results omit variables.
+        """
+        self._logger.debug(
+            "query.execute",
+            endpoint=self.endpoint_url,
+            query_bytes=len(query),
+            http_method=self.http_method,
+        )
+        try:
+            with sentry_sdk.start_span(op="http.client", name="SPARQL SELECT/ASK"):
+                with httpx.Client(timeout=self.timeout, auth=self.auth) as client:
+                    headers = {
+                        "Accept": "application/sparql-results+json",
+                        "User-Agent": self.user_agent,
+                    }
+
+                    if self.http_method == "GET":
+                        response = client.get(
+                            self.endpoint_url,
+                            params={"query": query},
+                            headers=headers,
+                        )
+                    else:
+                        response = client.post(
+                            self.endpoint_url,
+                            data={"query": query},
+                            headers=headers,
+                        )
+                    response.raise_for_status()
+
+                    data = response.json()
+
+                    # ASK queries return {"head": {}, "boolean": true/false}
+                    # per SPARQL 1.1 Results JSON spec — no "results" key.
+                    if "boolean" in data:
+                        value = "true" if data["boolean"] else "false"
+                        bv = BindingValue(type="literal", value=value)
+                        yield QueryResult(
+                            bindings={"boolean": bv},
+                            variables=["boolean"],
+                        )
+                        return
+
+                    variables = data.get("head", {}).get("vars", [])
+
+                    for idx, result_row in enumerate(data["results"]["bindings"]):
+                        bindings = {
+                            var: BindingValue(**value_dict)
+                            for var, value_dict in result_row.items()
+                        }
+                        # Include variable order only in first result
+                        if idx == 0:
+                            yield QueryResult(bindings=bindings, variables=variables)
+                        else:
+                            yield QueryResult(bindings=bindings)
+
+        except httpx.TimeoutException as e:
+            raise SPARQLTimeoutError(
+                f"Query timed out after {self.timeout}s: {self.endpoint_url}"
+            ) from e
+        except httpx.HTTPStatusError as e:
+            raise NetworkError(self._http_error_message(e)) from e
+        except httpx.RequestError as e:
+            raise NetworkError(f"Failed to connect to {self.endpoint_url}: {e}") from e
+
+    def execute_update(
+        self, update: str, update_endpoint: str
+    ) -> UpdateResult:
+        """Execute a SPARQL UPDATE operation (INSERT, DELETE, LOAD, etc.).
+
+        Uses POST with Content-Type: application/sparql-update.
+        Returns UpdateResult instead of raising on HTTP 4xx errors,
+        since update failures are expected operational outcomes.
+        """
+        self._logger.debug(
+            "update.execute",
+            endpoint=update_endpoint,
+            update_bytes=len(update),
+        )
+        try:
+            with sentry_sdk.start_span(
+                op="http.client", name="SPARQL UPDATE"
+            ):
+                with httpx.Client(
+                    timeout=self.timeout, auth=self.auth
+                ) as client:
+                    headers = {
+                        "Content-Type": "application/sparql-update",
+                        "User-Agent": self.user_agent,
+                    }
+                    response = client.post(
+                        update_endpoint,
+                        content=update,
+                        headers=headers,
+                    )
+                    response.raise_for_status()
+                    return UpdateResult(
+                        success=True,
+                        status_code=response.status_code,
+                        message=response.text,
+                    )
+        except httpx.HTTPStatusError as e:
+            return UpdateResult(
+                success=False,
+                status_code=e.response.status_code,
+                message=e.response.text[:500],
+            )
+        except httpx.TimeoutException as e:
+            raise SPARQLTimeoutError(
+                f"Update timed out after {self.timeout}s: "
+                f"{update_endpoint}"
+            ) from e
+        except httpx.RequestError as e:
+            raise NetworkError(
+                f"Failed to connect to {update_endpoint}: {e}"
+            ) from e
+
+    def execute_rdf(self, query: str, accept_header: str) -> str:
+        """Execute CONSTRUCT/DESCRIBE query returning server-serialized RDF graph."""
+        self._logger.debug(
+            "query.execute_rdf",
+            endpoint=self.endpoint_url,
+            accept=accept_header,
+            query_bytes=len(query),
+            http_method=self.http_method,
+        )
+        try:
+            with sentry_sdk.start_span(
+                op="http.client", name="SPARQL CONSTRUCT/DESCRIBE"
+            ):
+                with httpx.Client(timeout=self.timeout, auth=self.auth) as client:
+                    headers = {
+                        "Accept": accept_header,
+                        "User-Agent": self.user_agent,
+                    }
+
+                    if self.http_method == "GET":
+                        response = client.get(
+                            self.endpoint_url,
+                            params={"query": query},
+                            headers=headers,
+                        )
+                    else:
+                        response = client.post(
+                            self.endpoint_url,
+                            data={"query": query},
+                            headers=headers,
+                        )
+                    response.raise_for_status()
+                    return response.text
+
+        except httpx.TimeoutException as e:
+            raise SPARQLTimeoutError(
+                f"Query timed out after {self.timeout}s: {self.endpoint_url}"
+            ) from e
+        except httpx.HTTPStatusError as e:
+            raise NetworkError(self._http_error_message(e)) from e
+        except httpx.RequestError as e:
+            raise NetworkError(f"Failed to connect to {self.endpoint_url}: {e}") from e

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/sparql/core/config.py

@@ -31,6 +31,13 @@ class EndpointType(str, Enum):
     GRAPHDB = "graphdb"
 
 
+class HTTPMethod(str, Enum):
+    """HTTP methods for SPARQL queries."""
+
+    GET = "GET"
+    POST = "POST"
+
+
 class EndpointProfile(BaseModel):
     """Named endpoint configuration with optional authentication."""
 
@@ -41,6 +48,8 @@ class EndpointProfile(BaseModel):
     username: str | None = None
     password: str | None = None
     auth_type: AuthType = AuthType.NONE
+    http_method: HTTPMethod | None = None
+    update_url: str | None = None
 
     # Server-specific parameters
     database: str | None = None  # MarkLogic database name
@@ -150,6 +159,9 @@ class ResolvedConfig(BaseModel):
     password: str | None = None
     auth_type: AuthType = AuthType.NONE
     user_agent: str | None = None
+    http_method: HTTPMethod = HTTPMethod.POST
+
+    update_endpoint: str = ""
 
     # Server-specific parameters
     database: str | None = None
@@ -158,6 +170,32 @@ class ResolvedConfig(BaseModel):
     reasoning: bool | None = None
 
 
+def _derive_update_url(endpoint_url: str, explicit_update_url: str | None) -> str:
+    """Derive SPARQL UPDATE endpoint URL.
+
+    Priority: explicit update_url > replace /query path segment > endpoint as-is.
+    Only replaces /query in the URL path, not in the hostname.
+    """
+    if explicit_update_url:
+        return explicit_update_url
+
+    # Split at ://  to isolate scheme from rest, then find path
+    scheme_sep = endpoint_url.find("://")
+    if scheme_sep == -1:
+        return endpoint_url
+    after_scheme = endpoint_url[scheme_sep + 3 :]
+    slash_pos = after_scheme.find("/")
+    if slash_pos == -1:
+        return endpoint_url
+
+    host = endpoint_url[: scheme_sep + 3 + slash_pos]
+    path = after_scheme[slash_pos:]
+
+    if "/query" in path:
+        return host + path.replace("/query", "/update", 1)
+    return endpoint_url
+
+
 def resolve_config(
     config: AppConfig,
     *,
@@ -228,6 +266,18 @@ def resolve_config(
     # Resolve format: CLI > Config default
     format_value = cli_format or config.default_format
 
+    # Resolve HTTP method: Profile > Auto-detect from endpoint type
+    # VIRTUOSO endpoints require GET, all others default to POST
+    if profile_config.http_method is not None:
+        http_method = profile_config.http_method
+    elif profile_config.endpoint_type == EndpointType.VIRTUOSO:
+        http_method = HTTPMethod.GET
+    else:
+        http_method = HTTPMethod.POST
+
+    # Derive update endpoint URL
+    update_endpoint = _derive_update_url(endpoint, profile_config.update_url)
+
     return ResolvedConfig(
         endpoint=endpoint,
         endpoint_type=profile_config.endpoint_type,
@@ -237,6 +287,8 @@ def resolve_config(
         password=password,
         auth_type=auth_type,
         user_agent=profile_config.user_agent,
+        http_method=http_method,
+        update_endpoint=update_endpoint,
         database=profile_config.database,
         namespace=profile_config.namespace,
         repository=profile_config.repository,

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/sparql/core/models.py

@@ -55,8 +55,17 @@ class QueryResult(BaseModel):
 
 
 class EndpointConfig(BaseModel):
-    """Configuration for a SPARQL endpoint connection."""
-
     url: HttpUrl
     timeout: float = Field(default=30.0, gt=0)
     user_agent: str = "sparql-cli/1.0"
+
+
+class UpdateResult(BaseModel):
+    """Captures the outcome of INSERT, DELETE, LOAD, CLEAR, DROP operations.
+
+    Unlike queries, updates don't return bindings - only success/failure status.
+    """
+
+    success: bool
+    status_code: int
+    message: str

{sparql_cli-0.1.2 → sparql_cli-0.1.4}/sparql/core/query_source.py

@@ -11,6 +11,26 @@ from typing import TextIO
 
 from sparql.core.exceptions import ConfigError
 
+_QUERY_KEYWORDS = ("SELECT", "ASK", "CONSTRUCT", "DESCRIBE", "PREFIX")
+_UPDATE_KEYWORDS = (
+    "INSERT", "DELETE", "LOAD", "CLEAR", "DROP", "CREATE", "COPY", "MOVE", "ADD",
+)
+_ALL_SPARQL_KEYWORDS = _QUERY_KEYWORDS + _UPDATE_KEYWORDS
+
+
+def is_update_query(query: str) -> bool:
+    """Check whether a SPARQL string is an UPDATE operation.
+
+    Handles PREFIX declarations before the actual UPDATE keyword.
+    """
+    import re
+
+    # Strip PREFIX declarations (single or multi-line)
+    text = re.sub(
+        r"(?i)\bPREFIX\s+\S+\s+<[^>]*>\s*", "", query.strip()
+    ).strip().upper()
+    return text.startswith(_UPDATE_KEYWORDS)
+
 
 def resolve_query_source(
     inline: str | None,
@@ -33,8 +53,7 @@ def resolve_query_source(
         # Convert to string first to check for inline SPARQL
         # (must happen before Path conversion to preserve // in URLs)
         path_str = str(file_path)
-        sparql_keywords = ("SELECT", "ASK", "CONSTRUCT", "DESCRIBE", "PREFIX")
-        if path_str.upper().startswith(sparql_keywords):
+        if path_str.upper().startswith(_ALL_SPARQL_KEYWORDS):
             return path_str.strip()
         # It's a file path
         path = file_path if isinstance(file_path, Path) else Path(file_path)