python-log-viewer 0.1.0__py3-none-any.whl

python_log_viewer/auth.py

@@ -0,0 +1,39 @@
+"""
+HTTP Basic Authentication helpers (stdlib only).
+"""
+
+from __future__ import annotations
+
+import base64
+import secrets
+from typing import Optional, Tuple
+
+
+def decode_basic_auth(header_value: str) -> Optional[Tuple[str, str]]:
+    """Decode an ``Authorization: Basic ...`` header.
+
+    Returns ``(username, password)`` or ``None`` on failure.
+    """
+    if not header_value.startswith("Basic "):
+        return None
+    try:
+        decoded = base64.b64decode(header_value[6:]).decode("utf-8")
+        username, password = decoded.split(":", 1)
+        return username, password
+    except Exception:
+        return None
+
+
+def check_credentials(
+    header_value: str,
+    expected_username: str,
+    expected_password: str,
+) -> bool:
+    """Verify Basic-Auth credentials using constant-time comparison."""
+    creds = decode_basic_auth(header_value)
+    if creds is None:
+        return False
+    username, password = creds
+    return secrets.compare_digest(username, expected_username) and secrets.compare_digest(
+        password, expected_password
+    )

python_log_viewer/contrib/__init__.py

@@ -0,0 +1 @@
+# Framework integrations for python-log-viewer.

python_log_viewer/contrib/django/__init__.py

@@ -0,0 +1,4 @@
+# Django integration for python-log-viewer.
+#
+# Add ``"python_log_viewer.contrib.django"`` to ``INSTALLED_APPS`` and include
+# ``python_log_viewer.contrib.django.urls`` in your URL configuration.

python_log_viewer/contrib/django/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class LogViewerConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "python_log_viewer.contrib.django"
+    label = "python_log_viewer"
+    verbose_name = "Log Viewer"

python_log_viewer/contrib/django/urls.py

@@ -0,0 +1,19 @@
+from django.urls import path
+
+from .views import (
+    log_viewer_page,
+    get_log_files,
+    get_log_content,
+    delete_log_file,
+    clear_log_file,
+)
+
+app_name = "log_viewer"
+
+urlpatterns = [
+    path("", log_viewer_page, name="log_viewer"),
+    path("api/files", get_log_files, name="log_viewer_files"),
+    path("api/content", get_log_content, name="log_viewer_content"),
+    path("api/file", delete_log_file, name="log_viewer_delete"),
+    path("api/clear", clear_log_file, name="log_viewer_clear"),
+]

python_log_viewer/contrib/django/views.py

@@ -0,0 +1,163 @@
+"""
+Django views for the log viewer.
+
+Settings (all optional, set in ``settings.py``)::
+
+    LOG_VIEWER_DIR              = BASE_DIR / "logs"  # path to log directory
+    LOG_VIEWER_AUTO_REFRESH     = True
+    LOG_VIEWER_REFRESH_TIMER    = 5000  # ms
+    LOG_VIEWER_AUTO_SCROLL      = True
+    LOG_VIEWER_COLORIZE         = True
+    LOG_VIEWER_USERNAME         = None  # set both to enable Basic Auth
+    LOG_VIEWER_PASSWORD         = None
+    LOG_VIEWER_SUPERUSER_ACCESS = True  # allow Django superusers without Basic Auth
+"""
+
+from __future__ import annotations
+
+import os
+from functools import wraps
+
+from django.conf import settings
+from django.http import HttpResponse, JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_GET, require_POST, require_http_methods
+
+from python_log_viewer.auth import check_credentials
+from python_log_viewer.core import LogDirectory, LogReader
+from python_log_viewer._html import render_html
+
+
+# ---------------------------------------------------------------------------
+# Lazy singletons – created once, reused across requests.
+# ---------------------------------------------------------------------------
+
+def _get_log_dir() -> LogDirectory:
+    path = getattr(settings, "LOG_VIEWER_DIR", None)
+    if path is None:
+        path = os.path.join(settings.BASE_DIR, "logs")
+    return LogDirectory(str(path))
+
+
+def _get_reader() -> LogReader:
+    return LogReader(_get_log_dir())
+
+
+# ---------------------------------------------------------------------------
+# Authentication decorator
+# ---------------------------------------------------------------------------
+
+def _basic_auth_required(view_func):
+    """Decorator: enforce HTTP Basic Auth when credentials are configured.
+
+    Authenticated Django superusers are allowed through automatically when
+    ``LOG_VIEWER_SUPERUSER_ACCESS`` is ``True`` (the default).
+    """
+
+    @wraps(view_func)
+    def _wrapped(request, *args, **kwargs):
+        # Allow Django superusers to bypass Basic Auth
+        superuser_access = getattr(settings, "LOG_VIEWER_SUPERUSER_ACCESS", True)
+        if superuser_access:
+            user = getattr(request, "user", None)
+            if user is not None and getattr(user, "is_authenticated", False) and getattr(user, "is_superuser", False):
+                return view_func(request, *args, **kwargs)
+
+        username = getattr(settings, "LOG_VIEWER_USERNAME", None) or os.getenv("LOG_VIEWER_USERNAME")
+        password = getattr(settings, "LOG_VIEWER_PASSWORD", None) or os.getenv("LOG_VIEWER_PASSWORD")
+
+        if username and password:
+            auth = request.META.get("HTTP_AUTHORIZATION", "")
+            if not check_credentials(auth, username, password):
+                return HttpResponse(
+                    "Authentication required",
+                    status=401,
+                    headers={"WWW-Authenticate": 'Basic realm="Log Viewer"'},
+                )
+
+        return view_func(request, *args, **kwargs)
+
+    return _wrapped
+
+
+# ---------------------------------------------------------------------------
+# Views
+# ---------------------------------------------------------------------------
+
+@_basic_auth_required
+@require_GET
+def log_viewer_page(request):
+    """Serve the log viewer HTML page."""
+    # Read the URL prefix from the request path
+    # (strip trailing /api/... or trailing / to get the mount point)
+    prefix = request.path.rstrip("/")
+
+    html = render_html(
+        base_url=prefix,
+        auto_refresh=getattr(settings, "LOG_VIEWER_AUTO_REFRESH", True),
+        refresh_timer=getattr(settings, "LOG_VIEWER_REFRESH_TIMER", 5000),
+        auto_scroll=getattr(settings, "LOG_VIEWER_AUTO_SCROLL", True),
+        colorize=getattr(settings, "LOG_VIEWER_COLORIZE", True),
+    )
+    return HttpResponse(html, content_type="text/html")
+
+
+@_basic_auth_required
+@require_GET
+def get_log_files(request):
+    """Return a list of available log files with metadata."""
+    try:
+        files = _get_log_dir().list_files()
+        return JsonResponse(
+            {"files": [{"name": f.name, "size": f.size, "modified": f.modified} for f in files]}
+        )
+    except Exception as e:
+        return JsonResponse({"files": [], "error": str(e)})
+
+
+@_basic_auth_required
+@require_GET
+def get_log_content(request):
+    """Return log lines from the selected file as JSON."""
+    try:
+        result = _get_reader().read(
+            file=request.GET.get("file", "app.log"),
+            lines=int(request.GET.get("lines", "500")),
+            level=request.GET.get("level", ""),
+            search=request.GET.get("search", ""),
+        )
+        return JsonResponse(result)
+    except Exception as e:
+        return JsonResponse({"lines": [f"Error reading log file: {e}"], "total": 0})
+
+
+@csrf_exempt
+@_basic_auth_required
+@require_http_methods(["DELETE"])
+def delete_log_file(request):
+    """Permanently delete a log file."""
+    try:
+        file_param = request.GET.get("file", "")
+        if _get_log_dir().delete_file(file_param):
+            return JsonResponse(
+                {"success": True, "message": f"{os.path.basename(file_param)} deleted"}
+            )
+        return JsonResponse({"success": False, "error": "Invalid or missing file"}, status=404)
+    except Exception as e:
+        return JsonResponse({"success": False, "error": str(e)}, status=500)
+
+
+@csrf_exempt
+@_basic_auth_required
+@require_POST
+def clear_log_file(request):
+    """Clear the contents of a log file (truncate to 0 bytes)."""
+    try:
+        file_param = request.GET.get("file", "")
+        if _get_log_dir().clear_file(file_param):
+            return JsonResponse(
+                {"success": True, "message": f"{os.path.basename(file_param)} cleared"}
+            )
+        return JsonResponse({"success": False, "error": "Invalid or missing file"}, status=404)
+    except Exception as e:
+        return JsonResponse({"success": False, "error": str(e)}, status=500)

python_log_viewer/contrib/fastapi.py

@@ -0,0 +1,124 @@
+"""
+FastAPI integration for python-log-viewer.
+
+Usage::
+
+    from fastapi import FastAPI
+    from python_log_viewer.contrib.fastapi import create_log_viewer_router
+
+    app = FastAPI()
+    app.include_router(
+        create_log_viewer_router(
+            log_dir="./logs",
+            prefix="/logs",
+            username="admin",
+            password="secret",
+        )
+    )
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from python_log_viewer.core import LogDirectory, LogReader
+from python_log_viewer._html import render_html
+
+
+def create_log_viewer_router(
+    log_dir: str = "./logs",
+    prefix: str = "/logs",
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    auto_refresh: bool = True,
+    refresh_timer: int = 5000,
+    auto_scroll: bool = True,
+    colorize: bool = True,
+):
+    """Create and return a FastAPI :class:`~fastapi.APIRouter`.
+
+    Parameters
+    ----------
+    log_dir:
+        Path to the directory containing log files.
+    prefix:
+        URL prefix to mount the router at (e.g. ``/logs``).
+    username / password:
+        Enable HTTP Basic Auth when both are provided.
+    auto_refresh / refresh_timer / auto_scroll / colorize:
+        UI defaults.
+    """
+    from fastapi import APIRouter, Depends, HTTPException, Query, Request
+    from fastapi.responses import HTMLResponse, JSONResponse
+    from fastapi.security import HTTPBasic, HTTPBasicCredentials
+
+    from python_log_viewer.auth import check_credentials as _check
+
+    import secrets as _secrets
+
+    directory = LogDirectory(log_dir)
+    reader = LogReader(directory)
+    router = APIRouter(prefix=prefix, tags=["python-log-viewer"])
+
+    # ---- auth dependency ------------------------------------------------
+
+    _security = HTTPBasic(auto_error=False)
+
+    async def _verify(credentials: Optional[HTTPBasicCredentials] = Depends(_security)):
+        if username and password:
+            if credentials is None:
+                raise HTTPException(
+                    status_code=401,
+                    detail="Authentication required",
+                    headers={"WWW-Authenticate": 'Basic realm="Log Viewer"'},
+                )
+            if not (
+                _secrets.compare_digest(credentials.username, username)
+                and _secrets.compare_digest(credentials.password, password)
+            ):
+                raise HTTPException(
+                    status_code=401,
+                    detail="Invalid credentials",
+                    headers={"WWW-Authenticate": 'Basic realm="Log Viewer"'},
+                )
+
+    # ---- routes ---------------------------------------------------------
+
+    @router.get("/", response_class=HTMLResponse, dependencies=[Depends(_verify)])
+    async def index():
+        return render_html(
+            base_url=prefix,
+            auto_refresh=auto_refresh,
+            refresh_timer=refresh_timer,
+            auto_scroll=auto_scroll,
+            colorize=colorize,
+        )
+
+    @router.get("/api/files", dependencies=[Depends(_verify)])
+    async def api_files():
+        files = directory.list_files()
+        return {"files": [{"name": f.name, "size": f.size, "modified": f.modified} for f in files]}
+
+    @router.get("/api/content", dependencies=[Depends(_verify)])
+    async def api_content(
+        file: str = Query("app.log"),
+        lines: int = Query(500),
+        level: str = Query(""),
+        search: str = Query(""),
+    ):
+        return reader.read(file=file, lines=lines, level=level, search=search)
+
+    @router.delete("/api/file", dependencies=[Depends(_verify)])
+    async def api_delete(file: str = Query("")):
+        if directory.delete_file(file):
+            return {"success": True, "message": f"{os.path.basename(file)} deleted"}
+        return JSONResponse({"success": False, "error": "Invalid or missing file"}, status_code=404)
+
+    @router.post("/api/clear", dependencies=[Depends(_verify)])
+    async def api_clear(file: str = Query("")):
+        if directory.clear_file(file):
+            return {"success": True, "message": f"{os.path.basename(file)} cleared"}
+        return JSONResponse({"success": False, "error": "Invalid or missing file"}, status_code=404)
+
+    return router

python_log_viewer/contrib/flask.py

@@ -0,0 +1,124 @@
+"""
+Flask integration for python-log-viewer.
+
+Usage::
+
+    from flask import Flask
+    from python_log_viewer.contrib.flask import create_log_viewer_blueprint
+
+    app = Flask(__name__)
+    app.register_blueprint(
+        create_log_viewer_blueprint(
+            log_dir="./logs",
+            url_prefix="/logs",
+            username="admin",
+            password="secret",
+        )
+    )
+"""
+
+from __future__ import annotations
+
+import os
+from functools import wraps
+from typing import Optional
+
+from python_log_viewer.core import LogDirectory, LogReader
+from python_log_viewer._html import render_html
+
+
+def create_log_viewer_blueprint(
+    log_dir: str = "./logs",
+    url_prefix: str = "/logs",
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    auto_refresh: bool = True,
+    refresh_timer: int = 5000,
+    auto_scroll: bool = True,
+    colorize: bool = True,
+):
+    """Create and return a Flask :class:`~flask.Blueprint` for the log viewer.
+
+    Parameters
+    ----------
+    log_dir:
+        Path to the directory containing log files.
+    url_prefix:
+        URL prefix to mount the blueprint at (e.g. ``/logs``).
+    username / password:
+        Enable HTTP Basic Auth when both are provided.
+    auto_refresh / refresh_timer / auto_scroll / colorize:
+        UI defaults.
+    """
+    from flask import Blueprint, jsonify, request, Response
+
+    from python_log_viewer.auth import check_credentials
+
+    directory = LogDirectory(log_dir)
+    reader = LogReader(directory)
+    bp = Blueprint("log_viewer", __name__, url_prefix=url_prefix)
+
+    # ---- auth decorator -------------------------------------------------
+
+    def _auth_required(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            if username and password:
+                auth = request.headers.get("Authorization", "")
+                if not check_credentials(auth, username, password):
+                    return Response(
+                        "Authentication required",
+                        401,
+                        {"WWW-Authenticate": 'Basic realm="Log Viewer"'},
+                    )
+            return fn(*args, **kwargs)
+        return wrapper
+
+    # ---- routes ---------------------------------------------------------
+
+    @bp.route("/", methods=["GET"])
+    @_auth_required
+    def index():
+        html = render_html(
+            base_url=url_prefix,
+            auto_refresh=auto_refresh,
+            refresh_timer=refresh_timer,
+            auto_scroll=auto_scroll,
+            colorize=colorize,
+        )
+        return Response(html, content_type="text/html")
+
+    @bp.route("/api/files", methods=["GET"])
+    @_auth_required
+    def api_files():
+        files = directory.list_files()
+        return jsonify({"files": [{"name": f.name, "size": f.size, "modified": f.modified} for f in files]})
+
+    @bp.route("/api/content", methods=["GET"])
+    @_auth_required
+    def api_content():
+        result = reader.read(
+            file=request.args.get("file", "app.log"),
+            lines=int(request.args.get("lines", "500")),
+            level=request.args.get("level", ""),
+            search=request.args.get("search", ""),
+        )
+        return jsonify(result)
+
+    @bp.route("/api/file", methods=["DELETE"])
+    @_auth_required
+    def api_delete():
+        file_param = request.args.get("file", "")
+        if directory.delete_file(file_param):
+            return jsonify({"success": True, "message": f"{os.path.basename(file_param)} deleted"})
+        return jsonify({"success": False, "error": "Invalid or missing file"}), 404
+
+    @bp.route("/api/clear", methods=["POST"])
+    @_auth_required
+    def api_clear():
+        file_param = request.args.get("file", "")
+        if directory.clear_file(file_param):
+            return jsonify({"success": True, "message": f"{os.path.basename(file_param)} cleared"})
+        return jsonify({"success": False, "error": "Invalid or missing file"}), 404
+
+    return bp

python_log_viewer/core.py

@@ -0,0 +1,165 @@
+"""
+Framework-agnostic core logic for reading and managing log files.
+
+No external dependencies – only the Python standard library.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class LogFileInfo:
+    """Metadata for a single log file."""
+
+    name: str  # relative path from the log directory
+    size: int
+    modified: float
+
+
+class LogDirectory:
+    """Represents a directory tree of log files.
+
+    Parameters
+    ----------
+    path:
+        Absolute or relative path to the root log directory.
+    """
+
+    def __init__(self, path: str) -> None:
+        self.path = os.path.abspath(path)
+
+    # ------------------------------------------------------------------
+    # Listing
+    # ------------------------------------------------------------------
+
+    def list_files(self) -> List[LogFileInfo]:
+        """Walk *self.path* and return metadata for every regular file."""
+        if not os.path.isdir(self.path):
+            return []
+
+        files: list[LogFileInfo] = []
+        for root, _dirs, filenames in os.walk(self.path):
+            for entry in sorted(filenames):
+                filepath = os.path.join(root, entry)
+                if os.path.isfile(filepath):
+                    rel = os.path.relpath(filepath, self.path)
+                    stat = os.stat(filepath)
+                    files.append(
+                        LogFileInfo(name=rel, size=stat.st_size, modified=stat.st_mtime)
+                    )
+        files.sort(key=lambda f: f.name)
+        return files
+
+    # ------------------------------------------------------------------
+    # Safe path resolution
+    # ------------------------------------------------------------------
+
+    def _safe_resolve(self, relative: str) -> Optional[str]:
+        """Return the absolute path if *relative* stays inside *self.path*.
+
+        Returns ``None`` when the path escapes the log directory.
+        """
+        safe = os.path.normpath(relative)
+        if safe.startswith("..") or os.path.isabs(safe):
+            return None
+        full = os.path.realpath(os.path.join(self.path, safe))
+        if not full.startswith(os.path.realpath(self.path)):
+            return None
+        if not os.path.isfile(full):
+            return None
+        return full
+
+    # ------------------------------------------------------------------
+    # File mutations
+    # ------------------------------------------------------------------
+
+    def delete_file(self, relative: str) -> bool:
+        """Permanently remove a log file. Returns *True* on success."""
+        resolved = self._safe_resolve(relative)
+        if resolved is None:
+            return False
+        os.remove(resolved)
+        return True
+
+    def clear_file(self, relative: str) -> bool:
+        """Truncate a log file to zero bytes. Returns *True* on success."""
+        resolved = self._safe_resolve(relative)
+        if resolved is None:
+            return False
+        open(resolved, "w", encoding="utf-8").close()
+        return True
+
+
+class LogReader:
+    """Read and filter log entries from a file inside a :class:`LogDirectory`.
+
+    Parameters
+    ----------
+    log_dir:
+        A :class:`LogDirectory` instance.
+    """
+
+    _LEVEL_KEYWORDS = frozenset({"INFO", "WARNING", "ERROR", "DEBUG", "CRITICAL"})
+
+    def __init__(self, log_dir: LogDirectory) -> None:
+        self.log_dir = log_dir
+
+    def read(
+        self,
+        file: str,
+        *,
+        lines: int = 500,
+        level: str = "",
+        search: str = "",
+    ) -> dict:
+        """Return filtered log entries as a dict.
+
+        Returns
+        -------
+        dict
+            ``{"lines": [...], "total": int}`` on success, or
+            ``{"lines": [...], "total": 0, "error": "..."}`` on failure.
+        """
+        resolved = self.log_dir._safe_resolve(file)
+        if resolved is None:
+            return {"lines": [], "total": 0, "error": "Invalid or missing file"}
+
+        try:
+            with open(resolved, "r", encoding="utf-8") as fh:
+                raw_lines = fh.readlines()
+        except Exception as exc:
+            return {"lines": [f"Error reading log file: {exc}"], "total": 0}
+
+        # Group multi-line entries
+        entries: list[str] = []
+        for line in raw_lines:
+            stripped = line.rstrip()
+            if stripped and (
+                stripped[0].isdigit()
+                or stripped.split()[0] in self._LEVEL_KEYWORDS
+            ):
+                entries.append(stripped)
+            elif entries:
+                entries[-1] += "\n" + stripped
+            else:
+                entries.append(stripped)
+
+        # Level filter
+        if level:
+            upper = level.upper()
+            entries = [e for e in entries if upper in e]
+
+        # Text search
+        if search:
+            lower = search.lower()
+            entries = [e for e in entries if lower in e.lower()]
+
+        total = len(entries)
+        if lines > 0:
+            entries = entries[-lines:]
+
+        return {"lines": entries, "total": total}