xlwings-server 1.1.0__py3-none-any.whl

xlwings_server/docker_templates/Dockerfile

@@ -0,0 +1,60 @@
+# Dockerfile for xlwings Server
+# Use a Python image with uv pre-installed
+FROM ghcr.io/astral-sh/uv:0.9.26-python3.14-trixie-slim
+
+# Setup a non-root user
+RUN groupadd --system --gid 999 nonroot \
+    && useradd --system --gid 999 --uid 999 --create-home nonroot
+
+# Install the project into `/app`
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Ensure installed tools can be executed out of the box
+ENV UV_TOOL_BIN_DIR=/usr/local/bin
+
+# Copy dependency files first for better layer caching
+COPY pyproject.toml uv.lock ./
+
+# Install the project's dependencies using the lockfile and settings
+RUN uv sync --locked --no-install-project --no-dev
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+COPY . /app
+RUN uv sync --locked --no-dev
+
+# Build static files with hashed filenames for cache-busting
+RUN uv run xlwings-server build static
+
+# Place executables in the environment at the front of the path
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Python settings
+ENV PYTHONUNBUFFERED=1
+
+# Default port and workers
+ENV PORT=8000
+ENV WORKERS=1
+EXPOSE 8000
+
+# Reset the entrypoint, don't invoke `uv`
+ENTRYPOINT []
+
+# Use the non-root user to run our application
+USER nonroot
+
+# Uses shell to set PORT and WORKERS, then exec for proper signal handling
+CMD ["sh", "-c", "\
+    exec uvicorn \
+    --host 0.0.0.0 \
+    --port $PORT \
+    --workers $WORKERS \
+    --access-log \
+    xlwings_server.main:main_app \
+    "]

xlwings_server/docker_templates/docker-compose.yaml

@@ -0,0 +1,32 @@
+# This is for local development
+services:
+  xlwings-server:
+    build: .
+    # Allow the server to run with or without certs
+    command: >
+      sh -c '
+        SSL_OPTS=""
+        if [ -f /app/certs/localhost+2-key.pem ] && [ -f /app/certs/localhost+2.pem ]; then
+          SSL_OPTS="--ssl-keyfile /app/certs/localhost+2-key.pem --ssl-certfile /app/certs/localhost+2.pem"
+        fi
+        exec uvicorn \
+          --host 0.0.0.0 \
+          --port 8000 \
+          --reload \
+          --access-log \
+          $$SSL_OPTS \
+          xlwings_server.main:main_app
+      '
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    restart: "no"
+    init: true  # Helps with reload
+    volumes:
+      - ./certs:/app/certs
+      - ./custom_functions:/app/custom_functions
+      - ./custom_scripts:/app/custom_scripts
+      - ./dist:/app/dist
+      - ./static:/app/static
+      - ./templates:/app/templates

xlwings_server/hotreload.py

@@ -0,0 +1,59 @@
+"""
+Uvicorn reloads the app when the Python code is changed. So, we need to reload the
+browser when the app starts to show any changes caused the Python code.
+But, restarting the app takes a lot of time (especially in Docker), so we
+watch HTML, CSS, and JS files separately via Watchfiles. If these files change, we just
+reload the browser without having to restart the Python app.
+"""
+
+from pathlib import Path
+
+from watchfiles import Change, DefaultFilter, awatch
+
+from .config import settings
+
+browser_reload_triggered_by_backend = False
+watching_frontend_files = False
+
+
+class WebFilter(DefaultFilter):
+    allowed_extensions = (".html", ".css", ".js", ".py", ".txt", ".env")
+
+    def __call__(self, change: Change, path: str) -> bool:
+        if not super().__call__(change, path):
+            return False
+
+        path = Path(path)
+        if path.suffix not in self.allowed_extensions:
+            return False
+
+        # Allow HTML/CSS/JS files anywhere
+        if path.suffix in (".html", ".css", ".js"):
+            return True
+
+        # xlwings Wasm
+        if settings.enable_wasm and path.suffix in (".py", ".txt", ".env"):
+            allowed_dirs = ("wasm", "custom_scripts", "custom_functions")
+            return any(dir_name in path.parts for dir_name in allowed_dirs)
+
+        return False
+
+
+async def watch_frontend_files(sio, directory):
+    async for changes in awatch(
+        directory,
+        watch_filter=WebFilter(),
+    ):
+        await sio.emit("reload")
+
+
+async def start_browser_reload_watcher(sio, directory):
+    """Needs to be called from the sio connect event on the backend"""
+    global browser_reload_triggered_by_backend
+    global watching_frontend_files
+    if not browser_reload_triggered_by_backend and not settings.enable_wasm:
+        await sio.emit("reload")
+        browser_reload_triggered_by_backend = True
+    if not watching_frontend_files:
+        sio.start_background_task(watch_frontend_files, sio=sio, directory=directory)
+        watching_frontend_files = True

xlwings_server/main.py

@@ -0,0 +1,242 @@
+import json
+import logging
+import os
+import sys
+from functools import cache
+from pathlib import Path
+
+import socketio
+from fastapi import FastAPI, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import PlainTextResponse
+from fastapi.staticfiles import StaticFiles
+from xlwings import XlwingsError
+
+# CRITICAL: Setup sys.path for user overrides BEFORE importing user modules
+# This is done here (not in CLI) so it works when uvicorn imports this module
+if project_dir := os.getenv("XLWINGS_PROJECT_DIR"):
+    project_dir = Path(project_dir)
+    if str(project_dir) not in sys.path:
+        sys.path.insert(0, str(project_dir))
+
+from xlwings_server.config import PACKAGE_DIR, PROJECT_DIR, settings
+from xlwings_server.object_handles import ObjectCacheConverter
+from xlwings_server.routers import socketio as socketio_router
+from xlwings_server.routers.manifest import router as manifest_router
+from xlwings_server.routers.root import router as root_router
+from xlwings_server.routers.taskpane import router as taskpane_router
+from xlwings_server.routers.xlwings import router as xlwings_router
+from xlwings_server.templates import templates
+
+# Logging
+logging.basicConfig(level=settings.log_level.upper())
+logger = logging.getLogger(__name__)
+
+logger.info(f"Running in '{'Wasm' if settings.enable_wasm else 'Server'}' mode.")
+
+# App
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+
+# Starlette's url_for returns fully qualified URLs causing issues if the reverse proxy
+# handles TLS and the app runs on http (https://github.com/encode/starlette/issues/843)
+def url_for(name: str, **path_params):
+    """Wrapper around url_path_for that strips leading slashes from path parameters"""
+    if name == "static" and "path" in path_params:
+        # Strip leading slash from static file paths to avoid double slashes
+        path_params["path"] = path_params["path"].lstrip("/")
+    return app.url_path_for(name, **path_params)
+
+
+templates.env.globals["url_for"] = url_for
+
+# Register Converter
+ObjectCacheConverter.register(object, "object", "obj")
+
+
+# Custom StaticFiles with file-level override support
+class OverridableStaticFiles(StaticFiles):
+    """StaticFiles that checks user directory first, then falls back to package directory"""
+
+    def __init__(self, package_directory: Path, user_directory: Path, **kwargs):
+        self.package_dir = package_directory
+        self.user_dir = user_directory
+        super().__init__(directory=str(package_directory), **kwargs)
+
+    def lookup_path(self, path: str) -> tuple[str, os.stat_result | None]:
+        # Check user directory first
+        user_path = self.user_dir / path
+        if user_path.is_file():
+            return str(user_path), os.stat(user_path)
+        # Fallback to package directory
+        return super().lookup_path(path)
+
+
+# CORS: Office Scripts and custom functions in Excel on the web require CORS
+# Using app.add_middleware won't add the CORS headers if you handle the root "Exception"
+# in an exception handler (it would require a specific exception type).
+cors_app = CORSMiddleware(
+    app=app,
+    allow_origins=settings.cors_allow_origins,
+    allow_methods=["POST"],
+    allow_headers=["*"],
+    allow_credentials=False,
+)
+main_app = cors_app
+
+# Socket.io
+if settings.enable_socketio:
+    sio_app = socketio.ASGIApp(
+        socketio_router.sio,
+        # Only forward ASGI traffic if there's no message queue and hence 1 worker setup
+        cors_app if not settings.socketio_message_queue_url else None,
+        socketio_path=f"{settings.app_path}/socket.io",
+    )
+    main_app = sio_app if not settings.socketio_message_queue_url else cors_app
+
+
+# Routers
+app.include_router(root_router)
+app.include_router(xlwings_router)
+app.include_router(taskpane_router)
+app.include_router(manifest_router)
+
+
+# User routers (optional custom router)
+try:
+    from routers import custom
+
+    if hasattr(custom, "router"):
+        app.include_router(custom.router)
+        logger.info("Registered custom user router")
+except ModuleNotFoundError:
+    logger.debug("No custom router found (routers/custom.py)")
+except Exception:
+    logger.exception("Failed to load custom router from routers/custom.py")
+
+
+# Security headers
+@cache
+def read_security_headers():
+    with open(settings.base_dir / "security_headers.json", "r") as f:
+        data = json.load(f)
+    return data
+
+
+@app.middleware("http")
+async def add_security_headers(request, call_next):
+    # https://owasp.org/www-project-secure-headers/index.html#configuration-proposal
+    # https://owasp.org/www-project-secure-headers/ci/headers_add.json
+    response = await call_next(request)
+    if not settings.add_security_headers and settings.environment == "dev":
+        # Prevent caching in dev even if security headers are switched off
+        response.headers["Cache-Control"] = "no-store, max-age=0"
+    if settings.add_security_headers:
+        data = read_security_headers()
+
+        # Extract file extension from request URL
+        file_ext = request.url.path.split(".")[-1].lower()
+        image_ext = ("jpg", "jpeg", "png", "gif", "bmp", "webp", "svg")
+
+        for header in data["headers"]:
+            # Excel on Windows doesn't display the icons in the ribbon otherwise
+            if header["name"] == "Cache-Control" and file_ext in image_ext:
+                continue
+            if header["name"] not in (
+                "Permissions-Policy",  # experimental
+                "Clear-Site-Data",  # too aggressive
+                "Content-Security-Policy",  # provide via XLWINGS_CUSTOM_HEADERS
+            ):
+                # Permissions-Policy headers are experimental
+                # Clear-Site-Data is too aggressive
+                response.headers[header["name"]] = header["value"]
+
+        if settings.enable_excel_online:
+            response.headers["Cross-Origin-Resource-Policy"] = "cross-origin"
+            del response.headers["X-Frame-Options"]
+        if settings.cdn_officejs:
+            response.headers["Cross-Origin-Resource-Policy"] = "cross-origin"
+            del response.headers["Cross-Origin-Embedder-Policy"]
+
+    # Custom headers
+    for header_name, header_value in settings.custom_headers.items():
+        response.headers[header_name] = header_value
+
+    return response
+
+
+# Static files: in prod might be served by something like nginx or via
+# https://github.com/matthiask/blacknoise or https://github.com/Archmonger/ServeStatic
+# Auto-detect dist/ directory for production builds with hashed filenames
+dist_static = PROJECT_DIR / "dist" / "static"
+if dist_static.exists() and settings.environment != "dev":
+    app.mount(
+        settings.static_url_path,
+        StaticFiles(directory=dist_static),
+        name="static",
+    )
+    logger.info("Serving static files from dist/ (production build)")
+else:
+    app.mount(
+        settings.static_url_path,
+        OverridableStaticFiles(
+            package_directory=PACKAGE_DIR / "static",
+            user_directory=PROJECT_DIR / "static",
+        ),
+        name="static",
+    )
+
+
+if settings.enable_wasm:
+    # For xlwings Wasm development
+    app.mount(
+        # Use the same path prefix as for static files
+        settings.static_url_path.replace("static", "wasm"),
+        OverridableStaticFiles(
+            package_directory=PACKAGE_DIR / "wasm",
+            user_directory=PROJECT_DIR / "wasm",
+        ),
+        name="wasm",
+    )
+
+    app.mount(
+        # Use the same path prefix as for static files
+        settings.static_url_path.replace("static", "custom_functions"),
+        OverridableStaticFiles(
+            package_directory=PACKAGE_DIR / "custom_functions",
+            user_directory=PROJECT_DIR / "custom_functions",
+        ),
+        name="custom_functions",
+    )
+
+    app.mount(
+        # Use the same path prefix as for static files
+        settings.static_url_path.replace("static", "custom_scripts"),
+        OverridableStaticFiles(
+            package_directory=PACKAGE_DIR / "custom_scripts",
+            user_directory=PROJECT_DIR / "custom_scripts",
+        ),
+        name="custom_scripts",
+    )
+
+if settings.environment == "dev":
+    # Don't cache static files
+    StaticFiles.is_not_modified = lambda *args, **kwargs: False
+
+
+# Exception handlers
+@app.exception_handler(XlwingsError)
+async def xlwings_exception_handler(request, exception):
+    logger.error(exception)
+    msg = str(exception)
+    return PlainTextResponse(msg, status_code=status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+
+@app.exception_handler(Exception)
+async def exception_handler(request, exception):
+    logger.error(exception)
+    if settings.environment == "dev":
+        msg = repr(exception)
+    else:
+        msg = "An error occurred."
+    return PlainTextResponse(msg, status_code=status.HTTP_500_INTERNAL_SERVER_ERROR)

xlwings_server/models/__init__.py

@@ -0,0 +1,14 @@
+# Try to import User model from project directory first (user override)
+# Fall back to package location (default implementation)
+try:
+    from models.user import User
+except ModuleNotFoundError:
+    from .user import User
+
+
+class CurrentUser(User):
+    """
+    Will deliver the current user when used as type hint in a custom function/script
+    """
+
+    pass

xlwings_server/models/user.py

@@ -0,0 +1,53 @@
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+try:
+    from typing import Self
+except ImportError:
+    # Python < 3.11
+    from typing_extensions import Self
+
+logger = logging.getLogger(__name__)
+
+
+class User(BaseModel):
+    """
+    User model. This is set up so that it populates most fields from claims
+    as returned by OIDC tokens (e.g., Entra ID). You can also use the model by setting
+    the attributes directly though.
+    """
+
+    id: str | None = None
+    name: str | None = None
+    domain: str | None = None
+    email: str | None = None
+    roles: list[str] = []
+    ip_address: str | None = None
+    claims: dict[str, Any] = Field({}, repr=False)
+
+    @model_validator(mode="after")
+    def populate_from_claims(self) -> Self:
+        if self.claims:
+            self.id = self.id or self.claims.get("oid")
+            self.name = self.name or self.claims.get("name")
+            self.email = self.email or self.claims.get("preferred_username")
+            self.roles = self.roles or self.claims.get("roles", [])
+            if not self.domain and self.email and "@" in self.email:
+                self.domain = self.email.split("@")[1]
+        return self
+
+    async def has_required_roles(self, required_roles: list[str] | None = None):
+        if required_roles:
+            if set(required_roles).issubset(self.roles):
+                logger.info(f"User has required roles: {self.name}")
+                return True
+            else:
+                return False
+        else:
+            return True
+
+    async def is_authorized(self):
+        """Method that can be overridden to implement a global authorization logic"""
+        return True

xlwings_server/object_handles.py

@@ -0,0 +1,142 @@
+import logging
+import zlib
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
+try:
+    import pandas as pd
+except ImportError:
+    pd = None
+import redis
+from croniter import croniter
+from xlwings import XlwingsError
+from xlwings.constants import ObjectHandleIcons
+from xlwings.conversion import Converter
+
+from .config import settings
+from .routers import xlwings as xlwings_router
+from .serializers import deserialize, serialize
+
+logger = logging.getLogger(__name__)
+
+# Used if XLWINGS_OBJECT_CACHE_URL, i.e., Redis isn't configured.
+# Only useful with a single worker e.g., during development.
+cache = {}
+
+
+class ObjectCacheConverter(Converter):
+    @staticmethod
+    def read_value(cell_address, options):
+        # For custom function args of type Entity, the frontend sends the cell address
+        # instead of the cell value
+        redis_client: redis.Redis = xlwings_router.redis_client_context.get()
+        if settings.object_cache_url and not redis_client:
+            raise XlwingsError("Failed to connect to Redis")
+        key = f"object:{cell_address}"
+        if settings.object_cache_url:
+            value = redis_client.get(key)
+            if not value:
+                raise XlwingsError("Object cache is empty")
+            if settings.object_cache_enable_compression:
+                value = zlib.decompress(value).decode()
+            else:
+                value = value.decode()
+        else:
+            value = cache.get(key)
+            if not value:
+                raise XlwingsError("Object cache is empty")
+        obj = deserialize(value)
+        return obj
+
+    @staticmethod
+    def write_value(obj, options):
+        redis_client: redis.Redis = xlwings_router.redis_client_context.get()
+        if settings.object_cache_url and not redis_client:
+            raise XlwingsError("Failed to connect to Redis")
+        key = f"object:{xlwings_router.caller_address_context.get()}"
+        values = serialize(obj)
+        if settings.object_cache_url:
+            expire_at = None
+            if settings.object_cache_expire_at:
+                cron = croniter(settings.object_cache_expire_at)
+                expire_at = int(cron.get_next())
+            if settings.object_cache_enable_compression:
+                values = zlib.compress(values.encode())
+            redis_client.set(key, values, exat=expire_at)
+        else:
+            logger.warning(
+                "Storing objects in memory. Configure XLWINGS_OBJECT_CACHE_URL "
+                "for production use!"
+            )
+            cache[key] = values
+
+        obj_type = type(obj).__name__
+
+        result = {
+            "type": "Entity",
+            "text": options.get("text", obj_type) or obj_type,
+            "properties": {
+                "Type": {
+                    "type": "String",
+                    "basicValue": obj_type,
+                },
+            },
+            "layouts": {
+                "compact": {
+                    "icon": options.get("icon", ObjectHandleIcons.generic)
+                    or ObjectHandleIcons.generic
+                }
+            },
+        }
+
+        # Shape
+        def get_shape(obj):
+            if pd and isinstance(obj, pd.DataFrame):
+                return f"{obj.shape}"
+            if np and isinstance(obj, np.ndarray):
+                return f"{obj.shape}"
+            elif isinstance(obj, (list, tuple)):
+                if obj and isinstance(obj[0], (list, tuple)):
+                    return f"({len(obj)}, {len(obj[0])})"
+                return f"({len(obj)},)"
+            else:
+                try:
+                    return f"{len(obj)} (length)"
+                except Exception:
+                    return None
+
+        shape_value = get_shape(obj)
+        if shape_value:
+            result["properties"]["Shape"] = {
+                "type": "String",
+                "basicValue": shape_value,
+            }
+
+        # Columns
+        cols_info = None
+        if pd and isinstance(obj, pd.DataFrame):
+            cols_info = ", ".join(f"{col} [{obj[col].dtype}]" for col in obj.columns)
+        if cols_info:
+            result["properties"]["Columns"] = {
+                "type": "String",
+                "basicValue": cols_info,
+            }
+
+        # Index
+        index_info = None
+        if pd and isinstance(obj, pd.DataFrame):
+            index_type = type(obj.index).__name__
+            index_length = len(obj.index)
+            index_start = obj.index[0]
+            index_end = obj.index[-1]
+            index_info = (
+                f"{index_type}: {index_length} entries, {index_start} to {index_end}"
+            )
+        if index_info:
+            result["properties"]["Index"] = {
+                "type": "String",
+                "basicValue": index_info,
+            }
+        return result

xlwings_server/routers/manifest.py

@@ -0,0 +1,82 @@
+import logging
+import os
+import re
+
+from fastapi import APIRouter, Header, Request
+
+from ..config import settings
+from ..templates import TemplateResponse
+
+router = APIRouter(prefix=settings.app_path)
+
+logger = logging.getLogger(__name__)
+
+
+def _get_manifest_response(
+    request: Request, protocol: str, download: bool = False
+) -> TemplateResponse:
+    if settings.hostname:
+        # Settings
+        base_url = f"https://{settings.hostname}"
+    elif os.getenv("RENDER_EXTERNAL_URL"):
+        # Render.com
+        base_url = os.getenv("RENDER_EXTERNAL_URL")
+    elif os.getenv("WEBSITE_HOSTNAME"):
+        # Azure Functions and Azure App Service
+        base_url = f"https://{os.getenv('WEBSITE_HOSTNAME')}"
+    elif os.getenv("CODESPACES"):
+        # GitHub Codespaces
+        base_url = f"https://{os.getenv('CODESPACE_NAME')}-8000.{os.getenv('GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN')}"
+    else:
+        base_url = str(request.base_url)
+        if protocol == "https":
+            base_url = base_url.replace("http://", "https://")
+
+    base_url = str(base_url).rstrip("/")
+
+    manifest_ids = {
+        "dev": settings.manifest_id_dev,
+        "qa": settings.manifest_id_qa,
+        "uat": settings.manifest_id_uat,
+        "staging": settings.manifest_id_staging,
+        "prod": settings.manifest_id_prod,
+    }
+    manifest_id = manifest_ids[settings.environment]
+
+    headers = {}
+    if download:
+        sanitized_name = re.sub(
+            r"[^a-z0-9]+", "-", settings.project_name.lower()
+        ).strip("-")
+        filename = f"{sanitized_name}-{settings.environment}.xml"
+        headers["Content-Disposition"] = f"attachment; filename={filename}"
+
+    return TemplateResponse(
+        request=request,
+        name="manifest.xml",
+        context={
+            "settings": settings,
+            "base_url": base_url,
+            "base_url_with_app_path": f"{base_url}{settings.app_path}",
+            "manifest_id": manifest_id,
+        },
+        media_type="text/plain",
+        headers=headers,
+    )
+
+
+@router.get("/manifest")
+@router.get("/manifest.xml")
+async def manifest(
+    request: Request,
+    protocol: str = Header(default="", alias="X-Forwarded-Proto"),
+):
+    return _get_manifest_response(request, protocol, download=False)
+
+
+@router.get("/manifest/download")
+async def manifest_download(
+    request: Request,
+    protocol: str = Header(default="", alias="X-Forwarded-Proto"),
+):
+    return _get_manifest_response(request, protocol, download=True)