python-flashapi 0.1.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

flashapi/features/export.py

@@ -0,0 +1,143 @@
+"""Export functionality — CSV (built-in), XLSX and PDF (optional deps)."""
+
+from __future__ import annotations
+
+import csv
+import io
+from typing import Any
+
+
+def export_csv(items: list[dict[str, Any]], fields: list[str]) -> bytes:
+    output = io.BytesIO()
+    output.write(b"\xef\xbb\xbf")  # UTF-8 BOM for Excel compatibility
+    wrapper = io.TextIOWrapper(output, encoding="utf-8", newline="")
+    writer = csv.DictWriter(wrapper, fieldnames=fields, extrasaction="ignore", delimiter=";")
+    writer.writeheader()
+    for item in items:
+        writer.writerow({k: item.get(k, "") for k in fields})
+    wrapper.flush()
+    wrapper.detach()
+    return output.getvalue()
+
+
+def export_xlsx(items: list[dict[str, Any]], fields: list[str]) -> bytes:
+    try:
+        import openpyxl
+        from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+        from openpyxl.utils import get_column_letter
+    except ImportError:
+        msg = "openpyxl is required for XLSX export: pip install openpyxl"
+        raise ImportError(msg)
+
+    wb = openpyxl.Workbook()
+    ws = wb.active
+
+    header_font = Font(bold=True, color="FFFFFF", size=11)
+    header_fill = PatternFill(start_color="2563EB", end_color="2563EB", fill_type="solid")
+    header_alignment = Alignment(horizontal="center", vertical="center")
+    thin_border = Border(
+        left=Side(style="thin"),
+        right=Side(style="thin"),
+        top=Side(style="thin"),
+        bottom=Side(style="thin"),
+    )
+
+    for col_idx, field in enumerate(fields, 1):
+        cell = ws.cell(row=1, column=col_idx, value=field)
+        cell.font = header_font
+        cell.fill = header_fill
+        cell.alignment = header_alignment
+        cell.border = thin_border
+
+    for row_idx, item in enumerate(items, 2):
+        for col_idx, field in enumerate(fields, 1):
+            cell = ws.cell(row=row_idx, column=col_idx, value=item.get(field, ""))
+            cell.border = thin_border
+            cell.alignment = Alignment(vertical="center")
+
+    for col_idx, field in enumerate(fields, 1):
+        max_length = len(str(field))
+        for row in ws.iter_rows(min_row=2, min_col=col_idx, max_col=col_idx):
+            for cell in row:
+                if cell.value:
+                    max_length = max(max_length, len(str(cell.value)))
+        ws.column_dimensions[get_column_letter(col_idx)].width = min(max_length + 3, 50)
+
+    ws.auto_filter.ref = ws.dimensions
+
+    output = io.BytesIO()
+    wb.save(output)
+    return output.getvalue()
+
+
+def export_pdf(items: list[dict[str, Any]], fields: list[str]) -> bytes:
+    try:
+        from reportlab.lib import colors
+        from reportlab.lib.pagesizes import A4, landscape
+        from reportlab.lib.styles import getSampleStyleSheet
+        from reportlab.lib.units import mm
+        from reportlab.platypus import Paragraph, SimpleDocTemplate, Spacer, Table, TableStyle
+    except ImportError:
+        msg = "reportlab is required for PDF export: pip install reportlab"
+        raise ImportError(msg)
+
+    output = io.BytesIO()
+    page_size = landscape(A4)
+    doc = SimpleDocTemplate(
+        output,
+        pagesize=page_size,
+        leftMargin=10 * mm,
+        rightMargin=10 * mm,
+        topMargin=15 * mm,
+        bottomMargin=15 * mm,
+    )
+
+    styles = getSampleStyleSheet()
+    elements = []
+
+    title = Paragraph("Export", styles["Title"])
+    elements.append(title)
+    elements.append(Spacer(1, 5 * mm))
+
+    table_data = [fields]
+    for item in items:
+        row = [str(item.get(f, "")) if item.get(f) is not None else "" for f in fields]
+        table_data.append(row)
+
+    available_width = page_size[0] - 20 * mm
+    col_count = len(fields)
+    col_width = available_width / col_count if col_count else available_width
+
+    table = Table(table_data, colWidths=[col_width] * col_count, repeatRows=1)
+    table.setStyle(TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#2563EB")),
+        ("TEXTCOLOR", (0, 0), (-1, 0), colors.white),
+        ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
+        ("FONTSIZE", (0, 0), (-1, 0), 8),
+        ("FONTSIZE", (0, 1), (-1, -1), 7),
+        ("ALIGN", (0, 0), (-1, 0), "CENTER"),
+        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+        ("GRID", (0, 0), (-1, -1), 0.5, colors.HexColor("#E5E7EB")),
+        ("ROWBACKGROUNDS", (0, 1), (-1, -1), [colors.white, colors.HexColor("#F9FAFB")]),
+        ("TOPPADDING", (0, 0), (-1, -1), 4),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 4),
+        ("LEFTPADDING", (0, 0), (-1, -1), 4),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 4),
+    ]))
+
+    elements.append(table)
+    doc.build(elements)
+    return output.getvalue()
+
+
+EXPORTERS = {
+    "csv": export_csv,
+    "xlsx": export_xlsx,
+    "pdf": export_pdf,
+}
+
+CONTENT_TYPES = {
+    "csv": "text/csv",
+    "xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "pdf": "application/pdf",
+}

flashapi/features/filtering.py

@@ -1,33 +1,124 @@
-from __future__ import annotations
-
-from typing import Any
-
-RESERVED_PARAMS = {"page", "page_size", "sort", "search"}
-
-
-def apply_filters(
-    items: list[dict[str, Any]],
-    filters: dict[str, str],
-    valid_fields: set[str],
-) -> list[dict[str, Any]]:
-    """Filter items by exact field match."""
-    active_filters = {
-        k: v for k, v in filters.items()
-        if k not in RESERVED_PARAMS and k in valid_fields
-    }
-
-    if not active_filters:
-        return items
-
-    result = []
-    for item in items:
-        match = True
-        for field_name, value in active_filters.items():
-            item_value = item.get(field_name)
-            if str(item_value) != str(value):
-                match = False
-                break
-        if match:
-            result.append(item)
-
-    return result
+from __future__ import annotations
+
+from typing import Any
+
+RESERVED_PARAMS = {"page", "size", "sort", "search", "deleted", "expand", "format", "fields"}
+
+OPERATORS = frozenset({
+    "eq", "neq", "gt", "gte", "lt", "lte",
+    "contains", "startswith", "endswith", "isnull", "in",
+})
+
+
+def _parse_filter_key(key: str) -> tuple[str, str]:
+    """Parse 'field.operator' into (field_name, operator). Default operator is 'eq'."""
+    dot = key.rfind(".")
+    if dot > 0 and dot < len(key) - 1:
+        possible_op = key[dot + 1:]
+        if possible_op in OPERATORS:
+            return key[:dot], possible_op
+    return key, "eq"
+
+
+def _convert(value: str, item_value: Any) -> Any:
+    """Convert string value to the same type as the item's field value."""
+    if item_value is None:
+        return value
+    target_type = type(item_value)
+    if target_type is str:
+        return value
+    if target_type is int:
+        try:
+            return int(value)
+        except (ValueError, TypeError):
+            return value
+    if target_type is float:
+        try:
+            return float(value)
+        except (ValueError, TypeError):
+            return value
+    if target_type is bool:
+        return value.lower() in ("true", "1", "yes")
+    return value
+
+
+def _match_operator(item_value: Any, op: str, filter_value: str) -> bool:
+    """Evaluate a single filter operator against an item's field value."""
+    if op == "isnull":
+        is_null = item_value is None
+        return is_null if filter_value.lower() in ("true", "1", "yes") else not is_null
+
+    if op == "in":
+        parts = [p.strip() for p in filter_value.split(",")]
+        str_val = str(item_value) if item_value is not None else ""
+        converted = []
+        for p in parts:
+            converted.append(_convert(p, item_value))
+        return item_value in converted or str_val in parts
+
+    if item_value is None:
+        return False
+
+    if op == "eq":
+        converted = _convert(filter_value, item_value)
+        return item_value == converted or str(item_value) == str(filter_value)
+
+    if op == "neq":
+        converted = _convert(filter_value, item_value)
+        return item_value != converted and str(item_value) != str(filter_value)
+
+    if op == "contains":
+        return filter_value.lower() in str(item_value).lower()
+
+    if op == "startswith":
+        return str(item_value).lower().startswith(filter_value.lower())
+
+    if op == "endswith":
+        return str(item_value).lower().endswith(filter_value.lower())
+
+    # Comparison operators
+    converted = _convert(filter_value, item_value)
+    try:
+        if op == "gt":
+            return item_value > converted
+        if op == "gte":
+            return item_value >= converted
+        if op == "lt":
+            return item_value < converted
+        if op == "lte":
+            return item_value <= converted
+    except TypeError:
+        return False
+
+    return False
+
+
+def apply_filters(
+    items: list[dict[str, Any]],
+    filters: dict[str, str],
+    valid_fields: set[str],
+) -> list[dict[str, Any]]:
+    """Filter items using operators: ?field.operator=value (default operator: eq)."""
+    parsed_filters: list[tuple[str, str, str]] = []
+    for key, value in filters.items():
+        if key in RESERVED_PARAMS:
+            continue
+        field_name, op = _parse_filter_key(key)
+        if field_name in valid_fields:
+            parsed_filters.append((field_name, op, value))
+
+    if not parsed_filters:
+        return items
+
+    result = []
+    for item in items:
+        match = True
+        for field_name, op, value in parsed_filters:
+            item_value = item.get(field_name)
+            if not _match_operator(item_value, op, value):
+                match = False
+                break
+        if match:
+            result.append(item)
+
+    return result

flashapi/features/health.py

@@ -0,0 +1,69 @@
+"""
+Health check endpoints for production monitoring.
+
+Provides /health (liveness) and /ready (readiness) endpoints for Kubernetes,
+load balancers, and monitoring systems.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+class HealthCheck:
+    """Health check manager with liveness and readiness probes."""
+
+    def __init__(self) -> None:
+        self._start_time = time.time()
+        self._ready = False
+        self._checks: dict[str, callable] = {}
+
+    def mark_ready(self) -> None:
+        """Mark the application as ready to receive traffic."""
+        self._ready = True
+
+    def register_check(self, name: str, check_fn: callable) -> None:
+        """Register a custom readiness check (e.g., database connection)."""
+        self._checks[name] = check_fn
+
+    def liveness(self) -> dict[str, Any]:
+        """
+        Liveness probe — is the application running?
+        Returns 200 if alive, should return 5xx if deadlocked/crashed.
+        """
+        uptime = int(time.time() - self._start_time)
+        return {"status": "ok", "uptime": uptime}
+
+    def readiness(self) -> tuple[dict[str, Any], int]:
+        """
+        Readiness probe — is the application ready to serve traffic?
+        Returns 200 if ready, 503 if not yet ready or dependencies failing.
+        """
+        if not self._ready:
+            return {"status": "not_ready", "reason": "Application still initializing"}, 503
+
+        failed_checks = []
+        for name, check_fn in self._checks.items():
+            try:
+                if not check_fn():
+                    failed_checks.append(name)
+            except Exception as e:
+                failed_checks.append(f"{name}: {e}")
+
+        if failed_checks:
+            return {
+                "status": "not_ready",
+                "failed_checks": failed_checks,
+            }, 503
+
+        uptime = int(time.time() - self._start_time)
+        return {"status": "ready", "uptime": uptime, "checks_passed": len(self._checks)}, 200
+
+
+_health = HealthCheck()
+
+
+def get_health_check() -> HealthCheck:
+    """Get the global health check instance."""
+    return _health

flashapi/features/pagination.py

@@ -1,20 +1,20 @@
-from __future__ import annotations
-
-from typing import Any
-
-DEFAULT_PAGE_SIZE = 20
-MAX_PAGE_SIZE = 100
-
-
-def paginate(
-    items: list[dict[str, Any]],
-    page: int = 1,
-    page_size: int = DEFAULT_PAGE_SIZE,
-) -> tuple[list[dict[str, Any]], int]:
-    """Return a page slice and total count."""
-    page_size = min(max(1, page_size), MAX_PAGE_SIZE)
-    page = max(1, page)
-    total = len(items)
-    start = (page - 1) * page_size
-    end = start + page_size
-    return items[start:end], total
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_SIZE = 20
+MAX_SIZE = 100
+
+
+def paginate(
+    items: list[dict[str, Any]],
+    page: int = 0,
+    size: int = DEFAULT_SIZE,
+) -> tuple[list[dict[str, Any]], int]:
+    """Return a page slice and total count. Page is 0-indexed."""
+    size = min(max(1, size), MAX_SIZE)
+    page = max(0, page)
+    total = len(items)
+    start = page * size
+    end = start + size
+    return items[start:end], total

flashapi/features/rate_limit.py

@@ -0,0 +1,45 @@
+"""Rate limiting — in-memory sliding window per IP."""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+
+
+class RateLimiter:
+    """Simple in-memory rate limiter (per-IP, sliding window)."""
+
+    def __init__(self, limit: int = 100, window: int = 60) -> None:
+        self._limit = limit
+        self._window = window
+        self._requests: dict[str, list[float]] = defaultdict(list)
+
+    @property
+    def limit(self) -> int:
+        return self._limit
+
+    @property
+    def window(self) -> int:
+        return self._window
+
+    def check(self, key: str) -> tuple[bool, int, int]:
+        """Check if request is allowed.
+
+        Returns (allowed, remaining, reset_seconds).
+        """
+        now = time.time()
+        window_start = now - self._window
+
+        requests = self._requests[key]
+        self._requests[key] = [t for t in requests if t > window_start]
+        requests = self._requests[key]
+
+        remaining = max(0, self._limit - len(requests))
+        reset = int(self._window - (now - requests[0])) if requests else self._window
+
+        if len(requests) >= self._limit:
+            return False, 0, reset
+
+        self._requests[key].append(now)
+        remaining = max(0, self._limit - len(self._requests[key]))
+        return True, remaining, reset

flashapi/features/search.py

@@ -1,25 +1,25 @@
-from __future__ import annotations
-
-from typing import Any
-
-
-def apply_search(
-    items: list[dict[str, Any]],
-    query: str | None,
-    searchable_fields: set[str],
-) -> list[dict[str, Any]]:
-    """Filter items where any searchable field contains the query string."""
-    if not query:
-        return items
-
-    query_lower = query.lower()
-    result = []
-
-    for item in items:
-        for field_name in searchable_fields:
-            value = item.get(field_name, "")
-            if value and query_lower in str(value).lower():
-                result.append(item)
-                break
-
-    return result
+from __future__ import annotations
+
+from typing import Any
+
+
+def apply_search(
+    items: list[dict[str, Any]],
+    query: str | None,
+    searchable_fields: set[str],
+) -> list[dict[str, Any]]:
+    """Filter items where any searchable field contains the query string."""
+    if not query:
+        return items
+
+    query_lower = query.lower()
+    result = []
+
+    for item in items:
+        for field_name in searchable_fields:
+            value = item.get(field_name, "")
+            if value and query_lower in str(value).lower():
+                result.append(item)
+                break
+
+    return result

flashapi/features/sorting.py

@@ -1,21 +1,23 @@
-from __future__ import annotations
-
-from typing import Any
-
-
-def apply_sorting(
-    items: list[dict[str, Any]],
-    sort: str | None,
-    valid_fields: set[str],
-) -> list[dict[str, Any]]:
-    """Sort items by field. Prefix with - for descending."""
-    if not sort:
-        return items
-
-    descending = sort.startswith("-")
-    field_name = sort.lstrip("-")
-
-    if field_name not in valid_fields:
-        return items
-
-    return sorted(items, key=lambda x: x.get(field_name, ""), reverse=descending)
+from __future__ import annotations
+
+from typing import Any
+
+
+def apply_sorting(
+    items: list[dict[str, Any]],
+    sort: str | None,
+    valid_fields: set[str],
+) -> list[dict[str, Any]]:
+    """Sort items by field. Format: 'field,asc' or 'field,desc'."""
+    if not sort:
+        return items
+
+    parts = sort.split(",", 1)
+    field_name = parts[0].strip()
+    direction = parts[1].strip().lower() if len(parts) > 1 else "asc"
+    descending = direction == "desc"
+
+    if field_name not in valid_fields:
+        return items
+
+    return sorted(items, key=lambda x: x.get(field_name, ""), reverse=descending)

flashapi/features/webhooks.py

@@ -0,0 +1,84 @@
+"""Webhook dispatcher — async delivery with retry."""
+
+from __future__ import annotations
+
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+
+class WebhookDispatcher:
+    """Dispatches webhook events to configured URLs asynchronously."""
+
+    def __init__(
+        self,
+        urls: list[str],
+        *,
+        retry_count: int = 3,
+        timeout: int = 10,
+    ) -> None:
+        self._urls = urls
+        self._retry_count = retry_count
+        self._timeout = timeout
+        self.sent = 0
+        self.failed = 0
+        self.retries = 0
+
+    def dispatch(
+        self,
+        event: str,
+        entity: str,
+        entity_id: str | int,
+        data: dict[str, Any],
+    ) -> None:
+        if not self._urls:
+            return
+
+        payload = {
+            "event": event,
+            "entity": entity,
+            "entityId": str(entity_id),
+            "data": data,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        headers = {
+            "Content-Type": "application/json",
+            "X-FlashAPI-Event": event,
+            "X-FlashAPI-Entity": entity,
+        }
+
+        for url in self._urls:
+            thread = threading.Thread(
+                target=self._send_with_retry,
+                args=(url, payload, headers),
+                daemon=True,
+            )
+            thread.start()
+
+    def _send_with_retry(self, url: str, payload: dict, headers: dict) -> None:
+        import json
+        try:
+            import urllib.request
+        except ImportError:
+            return
+
+        data_bytes = json.dumps(payload).encode("utf-8")
+
+        for attempt in range(self._retry_count + 1):
+            try:
+                req = urllib.request.Request(
+                    url,
+                    data=data_bytes,
+                    headers=headers,
+                    method="POST",
+                )
+                with urllib.request.urlopen(req, timeout=self._timeout):
+                    self.sent += 1
+                    return
+            except Exception:
+                if attempt < self._retry_count:
+                    self.retries += 1
+                    time.sleep(2 ** attempt)
+                else:
+                    self.failed += 1