csvql-query 2.6.2__py3-none-win_amd64.whl

csvql/__init__.py

@@ -0,0 +1,146 @@
+"""
+csvql — fast CSV querying from Python.
+
+Usage::
+
+    import csvql
+
+    # Returns a list of dicts
+    rows = csvql.query("SELECT category, COUNT(*) FROM 'sales.csv' GROUP BY category")
+    # [{"category": "Electronics", "COUNT(*)": "42"}, ...]
+
+    # Returns raw CSV string (header + rows)
+    csv_text = csvql.query_csv("SELECT * FROM 'data.csv' WHERE amount > 100")
+
+    # Optional pandas integration (pandas not required)
+    df = csvql.query_df("SELECT region, SUM(revenue) FROM 'data.csv' GROUP BY region")
+"""
+
+import ctypes
+import csv
+import io
+import json
+from typing import Any
+
+from ._loader import load
+
+
+def query(sql: str) -> list[dict[str, Any]]:
+    """Run a SQL query and return results as a list of dicts.
+
+    Args:
+        sql: SQL string, e.g. ``"SELECT * FROM 'data.csv' WHERE age > 30"``
+
+    Returns:
+        List of row dicts, e.g. ``[{"name": "Alice", "age": "31"}, ...]``
+        All values are strings (CSV has no type information).
+
+    Raises:
+        RuntimeError: if the query fails (bad SQL, file not found, etc.)
+    """
+    lib = load()
+    out = ctypes.c_void_p(None)
+    rc = lib.csvql_query_json(sql.encode(), ctypes.byref(out))
+    addr = out.value
+    if rc != 0:
+        raw = ctypes.string_at(addr) if addr else b"unknown error"
+        if addr:
+            lib.csvql_free(addr)
+        raise RuntimeError(raw.decode(errors="replace"))
+    if not addr:
+        return []
+    raw = ctypes.string_at(addr)
+    lib.csvql_free(addr)
+    return json.loads(raw.decode())
+
+
+def query_csv(sql: str) -> str:
+    """Run a SQL query and return results as a CSV string (header + rows).
+
+    Args:
+        sql: SQL string.
+
+    Returns:
+        CSV text with a header row, e.g. ``"name,age\\nAlice,31\\n"``
+
+    Raises:
+        RuntimeError: if the query fails.
+    """
+    lib = load()
+    out = ctypes.c_void_p(None)
+    rc = lib.csvql_query_csv(sql.encode(), ctypes.byref(out))
+    addr = out.value
+    if rc != 0:
+        raw = ctypes.string_at(addr) if addr else b"unknown error"
+        if addr:
+            lib.csvql_free(addr)
+        raise RuntimeError(raw.decode(errors="replace"))
+    if not addr:
+        return ""
+    raw = ctypes.string_at(addr)
+    lib.csvql_free(addr)
+    return raw.decode()
+
+
+def query_df(sql: str):
+    """Run a SQL query and return a pandas DataFrame.
+
+    Requires pandas to be installed. All columns will be ``object`` dtype
+    (strings) — cast as needed after calling this function.
+
+    Args:
+        sql: SQL string.
+
+    Returns:
+        ``pandas.DataFrame``
+
+    Raises:
+        ImportError: if pandas is not installed.
+        RuntimeError: if the query fails.
+    """
+    try:
+        import pandas as pd
+    except ImportError as e:
+        raise ImportError("pandas is required for query_df(). Install it with: pip install pandas") from e
+
+    csv_text = query_csv(sql)
+    return pd.read_csv(io.StringIO(csv_text))
+
+
+def query_tuples(sql: str) -> tuple[list[str], list[tuple[str, ...]]]:
+    """Run a SQL query and return (headers, rows) as plain tuples.
+
+    Useful when you want array-of-arrays access (``row[0]``) instead of
+    dicts, or when memory overhead of dicts matters.
+
+    Args:
+        sql: SQL string.
+
+    Returns:
+        A ``(headers, rows)`` tuple where ``headers`` is a list of column
+        name strings and ``rows`` is a list of string tuples — one per row.
+
+    Raises:
+        RuntimeError: if the query fails.
+
+    Example::
+
+        headers, rows = csvql.query_tuples("SELECT name, age FROM 'data.csv'")
+        # headers: ['name', 'age']
+        # rows:    [('Alice', '30'), ('Bob', '25'), ...]
+        for row in rows:
+            print(row[0], row[1])
+    """
+    csv_text = query_csv(sql)
+    if not csv_text:
+        return [], []
+    reader = csv.reader(io.StringIO(csv_text))
+    all_rows = list(reader)
+    if not all_rows:
+        return [], []
+    headers = all_rows[0]
+    data = [tuple(r) for r in all_rows[1:] if r]
+    return headers, data
+
+
+__all__ = ["query", "query_csv", "query_df", "query_tuples"]

csvql/_loader.py

@@ -0,0 +1,90 @@
+"""
+Locates and loads libcsvql (.dll on Windows, .dylib on macOS, .so elsewhere).
+
+Search order:
+  1. Same directory as this file (installed wheel — lib bundled alongside .py)
+  2. zig-out/ relative to the repo root (development build)
+  3. Directories listed in CSVQL_LIB_PATH environment variable
+"""
+
+import ctypes
+import os
+import sys
+from pathlib import Path
+
+_lib_cache: ctypes.CDLL | None = None
+
+
+def _lib_name() -> str:
+    if sys.platform == "win32":
+        # Zig names the Windows shared library csvql.dll — no "lib" prefix.
+        return "csvql.dll"
+    if sys.platform == "darwin":
+        return "libcsvql.dylib"
+    return "libcsvql.so"
+
+
+def _candidate_dirs() -> list[Path]:
+    dirs: list[Path] = []
+
+    # 1. Next to this .py file (wheel install)
+    dirs.append(Path(__file__).parent)
+
+    # 2. zig-out/ — walk up from this file looking for build.zig.
+    #    Zig installs a .so/.dylib into zig-out/lib, but puts a Windows DLL
+    #    in zig-out/bin alongside the executables (only the import library
+    #    csvql.lib lands in lib/). Check both so a development build is
+    #    found on every platform.
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "build.zig").exists():
+            dirs.append(parent / "zig-out" / "lib")
+            dirs.append(parent / "zig-out" / "bin")
+            break
+
+    # 3. CSVQL_LIB_PATH env override
+    env_path = os.environ.get("CSVQL_LIB_PATH")
+    if env_path:
+        dirs.append(Path(env_path))
+
+    return dirs
+
+
+def load() -> ctypes.CDLL:
+    global _lib_cache
+    if _lib_cache is not None:
+        return _lib_cache
+
+    name = _lib_name()
+    for d in _candidate_dirs():
+        candidate = d / name
+        if candidate.exists():
+            lib = ctypes.CDLL(str(candidate))
+            _setup_signatures(lib)
+            _lib_cache = lib
+            return lib
+
+    searched = "\n  ".join(str(d / name) for d in _candidate_dirs())
+    raise FileNotFoundError(
+        f"Could not find {name}. Searched:\n  {searched}\n"
+        "Run `zig build lib -Doptimize=ReleaseFast` to build it, "
+        "or set CSVQL_LIB_PATH to its directory."
+    )
+
+
+def _setup_signatures(lib: ctypes.CDLL) -> None:
+    """Declare argument and return types for all exported functions."""
+    lib.csvql_query_json.argtypes = [
+        ctypes.c_char_p,
+        ctypes.POINTER(ctypes.c_void_p),
+    ]
+    lib.csvql_query_json.restype = ctypes.c_int
+
+    lib.csvql_query_csv.argtypes = [
+        ctypes.c_char_p,
+        ctypes.POINTER(ctypes.c_void_p),
+    ]
+    lib.csvql_query_csv.restype = ctypes.c_int
+
+    lib.csvql_free.argtypes = [ctypes.c_void_p]
+    lib.csvql_free.restype = None

csvql_query-2.6.2.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: csvql-query
+Version: 2.6.2
+Summary: Fast CSV querying from Python — powered by a Zig/SIMD engine
+License: MIT
+Project-URL: Homepage, https://github.com/melihbirim/csvql
+Project-URL: Repository, https://github.com/melihbirim/csvql
+Keywords: csv,query,sql,fast,simd,agent,ai,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+
+# csvql-query
+
+[![CI](https://github.com/melihbirim/csvql/actions/workflows/ci.yml/badge.svg)](https://github.com/melihbirim/csvql/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/melihbirim/csvql/blob/main/LICENSE.md)
+[![PyPI](https://img.shields.io/pypi/v/csvql-query)](https://pypi.org/project/csvql-query/)
+
+**Query CSV files with SQL from Python — powered by a Zig/SIMD engine.**
+
+Zero-copy mmap reads + SIMD parsing happen before Python ever sees the data.
+Faster than DuckDB on typical workloads, no dependencies required.
+
+## Installation
+
+```bash
+pip install csvql-query
+```
+
+## Quick Start
+
+```python
+import csvql
+
+# Returns a list of dicts (like csv.DictReader, but with SQL)
+rows = csvql.query("SELECT name, salary FROM 'employees.csv' WHERE salary > 100000 ORDER BY salary DESC")
+# [{'name': 'Alice', 'salary': '185000'}, ...]
+
+# Raw CSV string
+csv_str = csvql.query_csv("SELECT * FROM 'data.csv' LIMIT 10")
+
+# pandas DataFrame (pandas must be installed)
+df = csvql.query_df("SELECT category, COUNT(*) as n FROM 'sales.csv' GROUP BY category")
+
+# (headers, rows) tuples — no dependencies
+headers, rows = csvql.query_tuples("SELECT name, age FROM 'users.csv' WHERE age > 25")
+```
+
+## API
+
+| Function | Returns | Description |
+|---|---|---|
+| `query(sql)` | `list[dict]` | Execute SQL, get list of dicts |
+| `query_csv(sql)` | `str` | Execute SQL, get raw CSV string |
+| `query_df(sql)` | `DataFrame` | Execute SQL, get pandas DataFrame |
+| `query_tuples(sql)` | `(list[str], list[tuple])` | Execute SQL, get (headers, rows) |
+
+## SQL Support
+
+The SQL path is embedded in the query string (same as the CLI):
+
+```python
+# Filtering, ordering, limiting
+csvql.query("SELECT name, city FROM 'data.csv' WHERE age > 30 ORDER BY name LIMIT 5")
+
+# Aggregation
+csvql.query("SELECT department, AVG(salary) FROM 'emp.csv' GROUP BY department")
+
+# Unix pipes — use '-' as the filename
+import subprocess, sys
+# or just pass stdin data via the engine directly
+```
+
+Full SQL reference: [SIMPLE_QUERY_LANGUAGE.md](https://github.com/melihbirim/csvql/blob/main/SIMPLE_QUERY_LANGUAGE.md)
+
+## Performance
+
+- mmap + SIMD parsing — data is never copied into Python memory
+- Parallel chunk processing on multi-core machines
+- Typically 5–9x faster than DuckDB on 1M-row CSVs
+
+## Requirements
+
+- Python ≥ 3.10
+- macOS (x86_64 / arm64) or Linux (x86_64)
+- `pandas` optional — only needed for `query_df()`
+
+## Links
+
+- [GitHub](https://github.com/melihbirim/csvql)
+- [CLI Installation](https://github.com/melihbirim/csvql#installation)
+- [SQL Reference](https://github.com/melihbirim/csvql/blob/main/SIMPLE_QUERY_LANGUAGE.md)

csvql_query-2.6.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+csvql/__init__.py,sha256=kHEihvCYuuJb-0RQIWi_4wp-5UVFi3dPMvO9LPR7Pck,4177
+csvql/_loader.py,sha256=pWlOb6xEevlRNYqtQv8loQJpqtxhAM1nWBoZ2TCHgkE,2776
+csvql_query-2.6.2.dist-info/METADATA,sha256=Z3IA185CWmYbBEWZx3XJ5K3dEiPxNyFqqtdqvcfla5Y,3770
+csvql_query-2.6.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+csvql_query-2.6.2.dist-info/top_level.txt,sha256=iVE80iZxyPJ-SsWu0-vcYeu_8yAKnru0E7PaX6ZeoMM,6
+csvql_query-2.6.2.dist-info/RECORD,,

csvql_query-2.6.2.dist-info/WHEEL

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

csvql_query-2.6.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+csvql