tinycontracts 0.1.0__py3-none-any.whl

tinycontracts/__init__.py

@@ -0,0 +1 @@
+# tinycontracts

tinycontracts/cli.py

@@ -0,0 +1,134 @@
+# cli.py - typer entry point
+import sys
+from pathlib import Path
+
+import typer
+import uvicorn
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from tinycontracts.server import create_app
+
+console = Console()
+
+app = typer.Typer(
+    name="tc",
+    help="serve a folder of json/csv/parquet files as a rest api",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def print_banner(host: str, port: int, resources: list[str], folder: Path):
+    # header
+    console.print()
+    console.print(
+        Panel.fit(
+            "[bold cyan]tinycontracts[/bold cyan]  [dim]v0.1.0[/dim]",
+            border_style="cyan",
+        )
+    )
+    console.print()
+
+    # server info
+    console.print(f"  [dim]folder:[/dim]  {folder.resolve()}")
+    console.print(f"  [dim]server:[/dim]  [green]http://{host}:{port}[/green]")
+    console.print()
+
+    # endpoints table
+    if resources:
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("endpoint", style="green")
+        table.add_column("description", style="dim")
+
+        for name in sorted(resources):
+            table.add_row(f"/{name}", f"query {name}")
+
+        table.add_row("", "")
+        table.add_row("/docs", "swagger ui")
+        table.add_row("/_help", "api help")
+
+        console.print(table)
+    else:
+        console.print("  [yellow]no data files found[/yellow]")
+
+    console.print()
+    console.print("  [dim]press ctrl+c to stop[/dim]")
+    console.print()
+
+
+@app.command()
+def serve(
+    path: str = typer.Argument(..., help="folder containing data files"),
+    port: int = typer.Option(4242, "--port", "-p", help="port to serve on"),
+    host: str = typer.Option("127.0.0.1", "--host", "-H", help="host to bind to"),
+):
+    """serve data files as a rest api"""
+    folder = Path(path)
+
+    # validate folder exists
+    if not folder.exists():
+        console.print(f"\n  [red]error:[/red] path not found: [bold]{folder}[/bold]")
+        console.print(f"  [dim]make sure the path exists and try again[/dim]\n")
+        raise typer.Exit(1)
+
+    # validate it's a directory
+    if not folder.is_dir():
+        console.print(f"\n  [red]error:[/red] not a folder: [bold]{folder}[/bold]")
+        console.print(f"  [dim]tc needs a folder path, not a file[/dim]\n")
+        raise typer.Exit(1)
+
+    # check for data files
+    data_files = (
+        list(folder.glob("*.json"))
+        + list(folder.glob("*.csv"))
+        + list(folder.glob("*.parquet"))
+    )
+    if not data_files:
+        console.print(
+            f"\n  [yellow]warning:[/yellow] no data files in [bold]{folder}[/bold]"
+        )
+        console.print("[dim]add .json, .csv, or .parquet files[/dim]\n")
+
+    # create app
+    try:
+        fastapi_app = create_app(folder)
+        resources = (
+            list(fastapi_app.state.resources.keys())
+            if hasattr(fastapi_app.state, "resources")
+            else []
+        )
+    except PermissionError:
+        console.print(f"\n  [red]error:[/red] permission denied: [bold]{folder}[/bold]")
+        console.print("[dim]check file permissions and try again[/dim]\n")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"\n  [red]error:[/red] failed to load data: {e}\n")
+        raise typer.Exit(1)
+
+    # print startup banner
+    print_banner(host, port, resources, folder)
+
+    # run server
+    try:
+        uvicorn.run(fastapi_app, host=host, port=port, log_level="warning")
+    except KeyboardInterrupt:
+        console.print("\n  [dim]stopped[/dim]\n")
+    except OSError as e:
+        if "address already in use" in str(e).lower() or "10048" in str(e):
+            console.print(f"\n  [red]error:[/red] port {port} already in use")
+            console.print(f"  [dim]try: tc {path} -p {port + 1}[/dim]\n")
+        else:
+            console.print(f"\n  [red]error:[/red] {e}\n")
+        raise typer.Exit(1)
+
+
+@app.command()
+def version():
+    """show version"""
+    console.print("tinycontracts [cyan]v0.1.0[/cyan]")
+
+
+if __name__ == "__main__":
+    app()

tinycontracts/loader.py

@@ -0,0 +1,29 @@
+# loader.py - load json/csv/parquet files
+import json
+from pathlib import Path
+
+import pandas as pd
+
+
+def load_file(path: Path) -> pd.DataFrame:
+    if path.suffix == ".json":
+        data = json.load(path.open())
+        # handle singleton (single object) vs collection (array)
+        if isinstance(data, dict):
+            data = [data]
+        return pd.DataFrame(data)
+    elif path.suffix == ".csv":
+        return pd.read_csv(path)
+    elif path.suffix == ".parquet":
+        return pd.read_parquet(path)
+    else:
+        raise ValueError(f"Unsupported file type: {path.suffix}")
+
+
+def load_folder(folder: Path) -> dict[str, pd.DataFrame]:
+    resources = {}
+    for path in folder.glob("*"):
+        if path.suffix in [".json", ".csv", ".parquet"]:
+            name = path.stem  # filename without extension
+            resources[name] = load_file(path)
+    return resources

tinycontracts/routes.py

@@ -0,0 +1,119 @@
+# routes.py - dynamic route generation
+import pandas as pd
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.responses import PlainTextResponse
+
+
+def create_discovery_routes(
+    app: FastAPI, resources: dict[str, pd.DataFrame], schemas: dict[str, dict]
+):
+    @app.get("/")
+    def list_resources():
+        return {"resources": list(resources.keys())}
+
+    @app.get("/_schema")
+    def get_all_schemas():
+        return schemas
+
+    @app.get("/_help", response_class=PlainTextResponse)
+    def get_help():
+        resource_list = "\n".join(f"  - /{name}" for name in resources.keys())
+        return f"""tinycontracts api
+
+        resources:
+        {resource_list}
+
+        endpoints per resource:
+        GET /{{resource}}          list all rows
+        GET /{{resource}}/{{id}}      get row by id
+        GET /{{resource}}/_schema  get schema
+        GET /{{resource}}/_sample  get random sample
+
+        query parameters:
+        ?field=value   filter by field
+        ?_limit=N      limit results (default 100)
+        ?_offset=N     skip first N results
+        ?_sort=field   sort ascending
+        ?_sort=-field  sort descending
+        ?n=N           sample size (for /_sample)
+
+        global endpoints:
+        GET /          list all resources
+        GET /_schema   all schemas
+        GET /_help     this help text
+        """
+
+
+def create_resource_routes(app: FastAPI, name: str, df: pd.DataFrame, schema: dict):
+    # store df in closure
+    data = df.copy()
+
+    @app.get(f"/{name}/_schema")
+    def get_schema():
+        return schema
+
+    @app.get(f"/{name}/_sample")
+    def get_sample(n: int = 10):
+        sample_size = min(n, len(data))
+        return data.sample(n=sample_size).to_dict(orient="records")
+
+    @app.get(f"/{name}/{{row_id}}")
+    def get_row(row_id: str):
+        # try to find id column
+        id_col = None
+        if "id" in data.columns:
+            id_col = "id"
+        elif len(data.columns) > 0:
+            id_col = data.columns[0]
+
+        if id_col is None:
+            raise HTTPException(status_code=400, detail="no id column found")
+
+        # try to match as int or string
+        try:
+            row_id_int = int(row_id)
+            match = data[data[id_col] == row_id_int]
+        except ValueError:
+            match = data[data[id_col] == row_id]
+
+        if len(match) == 0:
+            raise HTTPException(status_code=404, detail="row not found")
+
+        return match.iloc[0].to_dict()
+
+    @app.get(f"/{name}")
+    def list_rows(
+        request: Request,
+        _limit: int = Query(100, alias="_limit"),
+        _offset: int = Query(0, alias="_offset"),
+        _sort: str = Query(None, alias="_sort"),
+    ):
+        result = data.copy()
+
+        # filter by query params (exclude special params)
+        special_params = {"_limit", "_offset", "_sort"}
+        for key, value in request.query_params.items():
+            if key not in special_params and key in result.columns:
+                # try to cast value to column type
+                try:
+                    if result[key].dtype == "int64":
+                        value = int(value)
+                    elif result[key].dtype == "float64":
+                        value = float(value)
+                    elif result[key].dtype == "bool":
+                        value = value.lower() in ("true", "1", "yes")
+                except ValueError:
+                    pass
+                result = result[result[key] == value]
+
+        # sort
+        if _sort:
+            descending = _sort.startswith("-")
+            col = _sort.lstrip("-")
+            if col in result.columns:
+                result = result.sort_values(col, ascending=not descending)
+
+        # offset and limit
+        result = result.iloc[_offset : _offset + _limit]
+
+        return result.to_dict(orient="records")

tinycontracts/schema.py

@@ -0,0 +1,25 @@
+# schema.py - infer schema from dataframes
+import pandas as pd
+
+
+def infer_column_schema(series: pd.Series) -> str:
+    dtype_str = str(series.dtype)
+
+    if dtype_str in ("object", "str", "string"):
+        return "string"
+    elif "int" in dtype_str:
+        return "integer"
+    elif "float" in dtype_str:
+        return "number"
+    elif dtype_str == "bool":
+        return "boolean"
+    else:
+        # fallback to string for unknown types
+        return "string"
+
+
+def infer_schema(df: pd.DataFrame) -> dict:
+    properties = {}
+    for column in df.columns:
+        properties[column] = {"type": infer_column_schema(df[column])}
+    return {"type": "object", "properties": properties}

tinycontracts/server.py

@@ -0,0 +1,24 @@
+# server.py - fastapi app factory
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from tinycontracts.loader import load_folder
+from tinycontracts.routes import create_discovery_routes, create_resource_routes
+from tinycontracts.schema import infer_schema
+
+
+def create_app(folder: Path) -> FastAPI:
+    resources = load_folder(folder)
+    schemas = {name: infer_schema(df) for name, df in resources.items()}
+
+    app = FastAPI(title="tinycontracts", docs_url="/docs", redoc_url=None)
+    app.state.resources = resources
+    app.state.schemas = schemas
+
+    create_discovery_routes(app, resources, schemas)
+
+    for name, df in resources.items():
+        create_resource_routes(app, name, df, schemas[name])
+
+    return app

tinycontracts-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: tinycontracts
+Version: 0.1.0
+Summary: serve a folder of json/csv/parquet files as a rest api
+Author-email: Aditya Kumar <adityakuma0308@gmail.com>
+License-Expression: MIT
+Keywords: api,cli,csv,fastapi,json,parquet,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: pandas>=3.0.0
+Requires-Dist: pyarrow>=23.0.0
+Requires-Dist: rich>=14.3.2
+Requires-Dist: typer>=0.21.1
+Requires-Dist: uvicorn>=0.40.0
+Description-Content-Type: text/markdown
+
+# tinycontracts
+
+Turn JSON, CSV, and Parquet files into REST APIs instantly.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Usage
+
+```bash
+tinycontracts serve ./data
+```
+
+This scans `./data` for `.json`, `.csv`, and `.parquet` files and serves them as REST endpoints.
+
+## Example
+
+Given this structure:
+```
+data/
+  users.json
+  orders.csv
+  products.parquet
+```
+
+You get:
+```
+GET /users
+GET /orders
+GET /products
+```
+
+## Filtering
+
+Query any field:
+```
+GET /users?role=admin
+GET /orders?status=shipped&customer_id=123
+```
+
+## Schema
+
+Get the inferred JSON schema:
+```
+GET /users/schema
+```

tinycontracts-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tinycontracts/__init__.py,sha256=WEsinRwkR1RI9izRzpTB0MidHLvvZxFE0S6KvkcK2aE,17
+tinycontracts/cli.py,sha256=kir936bXvhjnVRfz4Gm36HmECq3PZLszKrTOvolhwY8,4078
+tinycontracts/loader.py,sha256=CYgvvdTmuioaQeaTZNxLKy0ndFaCjR-xzQoh61FN5q4,884
+tinycontracts/routes.py,sha256=ZVtr7-Sx1IAJIlK9yHgiFzgUa5Wpodsm90jliopQagM,3840
+tinycontracts/schema.py,sha256=tZjLLvQGKi5H4drZZRNCDWY5SWg4_MnYtJWz5hsw8ng,692
+tinycontracts/server.py,sha256=23gJheNqjPHckSeNlquG-G8viJNrMEVItcYxBg-n-t8,728
+tinycontracts-0.1.0.dist-info/METADATA,sha256=erlssWxzSfTqQ5cf-gOL_kcHuWLRbnDilwUczBcoYkM,1438
+tinycontracts-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tinycontracts-0.1.0.dist-info/entry_points.txt,sha256=mBH0FJ35wm3PDzo0sK-0XP0NA53XQ93JpMCYXRBEPiI,45
+tinycontracts-0.1.0.dist-info/RECORD,,

tinycontracts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tinycontracts-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tc = tinycontracts.cli:app