xlwings-server 1.1.0__py3-none-any.whl

xlwings_server/config.py

@@ -0,0 +1,228 @@
+import logging
+import os
+import sys
+import warnings
+from importlib.metadata import version as get_package_version
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import UUID4, computed_field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    PyprojectTomlConfigSettingsSource,
+    SettingsConfigDict,
+)
+
+logger = logging.getLogger(__name__)
+
+# Set before xlwings is imported elsewhere in the application
+os.environ["XLWINGS_ON_SERVER"] = "true"
+
+# Get project directory from environment (set by CLI)
+# Falls back to current working directory if not set (for backward compatibility)
+PROJECT_DIR = Path(os.getenv("XLWINGS_PROJECT_DIR", Path.cwd()))
+
+# Get package directory - must be calculated before any sys.path manipulation
+# Use __file__ which points to the actual config.py location (in site-packages after install)
+PACKAGE_DIR = Path(__file__).parent.resolve()
+
+# Setup sys.path for user overrides
+# This is also done in main.py, but we need it here too because config.py
+# can be imported directly (e.g., from custom_functions) before main.py runs
+if str(PROJECT_DIR) not in sys.path:
+    sys.path.insert(0, str(PROJECT_DIR))
+
+# Settings prefix used for environment variables (required)
+# and pyproject.toml keys (optional)
+ENV_PREFIX = "XLWINGS_"
+
+
+class CaseInsensitivePyprojectTomlSource(PyprojectTomlConfigSettingsSource):
+    """
+    PyprojectToml source that handles case-insensitive keys and strips ENV_PREFIX.
+    E.g., allows 'environment', 'ENVIRONMENT', 'XLWINGS_ENVIRONMENT', etc. to all work.
+    """
+
+    def __call__(self) -> dict[str, Any]:
+        config = super().__call__()
+        normalized = {}
+        prefix_lower = ENV_PREFIX.lower()
+        for k, v in config.items():
+            # Convert to lowercase
+            key = k.lower()
+            # Strip prefix if present (e.g., "xlwings_")
+            if key.startswith(prefix_lower):
+                key = key[len(prefix_lower) :]
+            normalized[key] = v
+        return normalized
+
+
+class Settings(BaseSettings):
+    """
+    xlwings Server settings with support for multiple configuration sources.
+
+    Configuration priority (highest to lowest):
+    1. Environment variables (XLWINGS_*)
+    2. .env file
+    3. pyproject.toml [tool.xlwings_server] section
+    4. Default values defined in this class
+
+    See .env.template for detailed documentation of all settings.
+    """
+
+    def __init__(self, **values):
+        super().__init__(**values)
+        if self.public_addin_store is not None:
+            warnings.warn(
+                "The 'XLWINGS_PUBLIC_ADDIN_STORE' field is deprecated and will be removed in "
+                "future versions. Use 'XLWINGS_CDN_OFFICEJS' instead.",
+                DeprecationWarning,
+            )
+            self.cdn_officejs = self.public_addin_store
+
+    model_config = SettingsConfigDict(
+        env_prefix=ENV_PREFIX,
+        env_file=os.getenv("DOTENV_PATH", PROJECT_DIR / ".env"),
+        extra="ignore",
+        pyproject_toml_table_header=("tool", "xlwings_server"),
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """
+        Define the sources and their priority order.
+        Priority (highest to lowest):
+        1. init_settings - arguments passed to Settings()
+        2. env_settings - environment variables
+        3. dotenv_settings - .env file
+        4. pyproject.toml - [tool.xlwings_server] section
+        5. file_secret_settings - secret files
+        """
+        # CaseInsensitivePyprojectTomlSource looks in PROJECT_DIR for pyproject.toml
+        pyproject_path = PROJECT_DIR / "pyproject.toml"
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            CaseInsensitivePyprojectTomlSource(
+                settings_cls, pyproject_path if pyproject_path.exists() else None
+            ),
+            file_secret_settings,
+        )
+
+    add_security_headers: bool = True
+    auth_providers: list[str] | None = []
+    auth_required_roles: list[str] | None = []
+    auth_entraid_client_id: str | None = None
+    auth_entraid_tenant_id: str | None = None
+    auth_entraid_multitenant: bool = False
+    app_path: str = ""
+    base_dir: Path = Path(__file__).resolve().parent
+    object_cache_url: str | None = None
+    object_cache_expire_at: str | None = "0 12 * * sat"
+    object_cache_enable_compression: bool = True
+    cors_allow_origins: list[str] = []
+    custom_functions_max_retries: int = 3
+    custom_functions_retry_codes: list[int] = [500, 502, 504]
+    custom_headers: dict[str, str] = {}
+    date_format: str | None = None
+    taskpane_html: str = "taskpane.html"
+    enable_alpinejs_csp: bool = True
+    enable_bootstrap: bool = True
+    enable_examples: bool = False
+    enable_excel_online: bool = True
+    enable_hotreload: bool = True
+    enable_htmx: bool = True
+    enable_socketio: bool = True
+    enable_tests: bool = False
+    enable_wasm: bool = False
+    environment: Literal["dev", "qa", "uat", "staging", "prod"] = "prod"
+    functions_namespace: str = "XLWINGS"
+    hostname: str | None = None
+    is_official_lite_addin: bool | None = False
+    cdn_pyodide: bool = True
+    cdn_officejs: bool = False
+    log_level: str = "INFO"
+    # Manifest UUIDs - loaded from pyproject.toml [tool.xlwings_server] or defaults
+    # Run 'xlwings-server init' to generate unique UUIDs in pyproject.toml
+    manifest_id_dev: UUID4 = "0a856eb1-91ab-4f38-b757-23fbe1f73130"
+    manifest_id_qa: UUID4 = "9cda34b1-af68-4dc6-b97c-e63ef6284671"
+    manifest_id_uat: UUID4 = "70428e53-8113-421c-8fe2-9b74fcb94ee5"
+    manifest_id_staging: UUID4 = "34041f4f-9cb4-4830-afb5-db44b2a70e0e"
+    manifest_id_prod: UUID4 = "4f342d85-3a49-41cb-90a5-37b1f2219040"
+    project_name: str = "xlwings Server"
+    public_addin_store: bool | None = None  # Deprecated. Use cdn_officejs instead.
+    request_timeout: int | None = 300  # in seconds
+    secret_key: str | None = None
+    socketio_message_queue_url: str | None = None
+    socketio_server_app: bool = False
+    static_url_path: str = "/static"
+    license_key: str | None = ""
+    xlwings_version: str = get_package_version("xlwings")
+
+    @computed_field
+    @property
+    def jsconfig(self) -> dict:
+        return {
+            "appPath": self.app_path,
+            "authProviders": self.auth_providers,
+            "customFunctionsMaxRetries": self.custom_functions_max_retries,
+            "customFunctionsRetryCodes": self.custom_functions_retry_codes,
+            "environment": self.environment,
+            "isOfficialLiteAddin": self.is_official_lite_addin,
+            "onWasm": self.enable_wasm,
+            "requestTimeout": self.request_timeout,
+            "xlwingsVersion": self.xlwings_version,
+        }
+
+    @computed_field
+    @property
+    def project_dir(self) -> Path:
+        """Project directory - location of user's custom files"""
+        return PROJECT_DIR
+
+    @computed_field
+    @property
+    def package_dir(self) -> Path:
+        """Package directory - location of xlwings-server package files"""
+        return PACKAGE_DIR
+
+
+# Try to import Settings from project directory (user override)
+# Fall back to package Settings if not found
+def _create_settings() -> Settings:
+    """Create settings instance, checking for project-level config override"""
+    try:
+        config_file = PROJECT_DIR / "config.py"
+        if config_file.exists():
+            # Import Settings from project config
+            import importlib
+
+            config_module = importlib.import_module("config")
+            if hasattr(config_module, "Settings"):
+                ProjectSettings = config_module.Settings
+                logger.info("Loaded settings from project config.py")
+                return ProjectSettings()
+    except Exception as e:
+        logger.debug(f"No project config.py found or failed to load: {e}")
+
+    # No project config or import failed, use package Settings
+    return Settings()
+
+
+settings = _create_settings()
+
+# TODO: refactor once xlwings offers a runtime config
+if settings.license_key and not os.getenv("XLWINGS_LICENSE_KEY"):
+    os.environ["XLWINGS_LICENSE_KEY"] = settings.license_key
+
+if settings.date_format:
+    os.environ["XLWINGS_DATE_FORMAT"] = settings.date_format

xlwings_server/custom_functions/__init__.py

@@ -0,0 +1,8 @@
+try:
+    from xlwings_server.config import settings
+except ImportError:
+    # xlwings Wasm
+    from config import settings
+
+if settings.enable_examples:
+    from .examples import *

xlwings_server/custom_functions/examples.py

@@ -0,0 +1,177 @@
+"""
+Make sure to import the desired functions under __init__.py, e.g.:
+from .example import *
+"""
+
+import asyncio
+import datetime as dt
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import numpy as np
+import pandas as pd
+from xlwings.server import arg, func, ret
+
+from . import settings
+
+if not settings.enable_wasm:
+    # Try to import custom_scripts from project directory first (CLI/Azure mode)
+    # Fall back to package location (tests/package mode)
+    try:
+        import custom_scripts
+    except ModuleNotFoundError:
+        import xlwings_server.custom_scripts as custom_scripts
+
+    from xlwings.constants import ObjectHandleIcons
+    from xlwings.ext.sql import _sql
+
+    from xlwings_server import utils
+    from xlwings_server.models import CurrentUser
+
+
+# 1) This is the most basic custom function -- it only requires the @func decorator.
+@func
+def hello(name):
+    return f"Hello {name}!"
+
+
+# 2) Returning a pandas DataFrame and function documentation
+# The function's doc string will turn up in the Function Wizard together with the
+# doc strings from the arg decorators. The sample also shows how to suppress the index
+# of a DataFrame via the ret decorator.
+@func
+@arg("rows", doc="The number of rows in the returned array.")
+@arg("cols", doc="The number of columns in the returned array.")
+def standard_normal(rows, cols):
+    """Returns an array of standard normally distributed pseudo random numbers"""
+    rng = np.random.default_rng()
+    matrix = rng.standard_normal(size=(rows, cols))
+    date_rng = pd.date_range(start=dt.datetime(2025, 6, 15), periods=rows, freq="D")
+    df = pd.DataFrame(
+        matrix, columns=[f"col{i+1}" for i in range(matrix.shape[1])], index=date_rng
+    )
+    return df
+
+
+# 3) Reading a pandas DataFrames
+@func
+@arg("df", pd.DataFrame)
+def correl(df):
+    """Like CORREL, but it works on whole matrices instead of just 2 arrays."""
+    return df.corr()
+
+
+# 4) Type hints: this is the same example as 3), but using type hints instead of
+# decorators. You could also use type hints and decorators together. In this sample, we
+# are storing the Annotated type hint outside of the function, so it is easy to reuse.
+Df = Annotated[pd.DataFrame, {"index": True}]
+
+
+@func
+def correl2(df: Df):
+    """Like CORREL, but it works on whole matrices instead of just 2 arrays."""
+    return df.corr()
+
+
+if not settings.enable_wasm:
+    # 5) Object handles: This returns an object handle to a DataFrame that is generated on
+    # the backend. You can change the `text` and `icon` via annotated type hint or via ret
+    # decorator.
+    @func
+    async def get_df() -> object:
+        """Returns an object handle to the Excel cell (for production, this requires
+        XLWINGS_OBJECT_CACHE_URL)."""
+        return pd.DataFrame(
+            {"A": [1, 2, 3, 4, 5], "B": [10, 8, 6, 4, 2], "C": [10, 9, 8, 7, 6]}
+        )
+
+    # 6) Object handles: demonstrating the use of the "icon" and "text" options. Instead
+    # of using the ret decorator, you could also use an annotated type hint like so:
+    # -> Annotated[object, {"icon": ObjectHandleIcons.table, "text": "healthexp"}]
+    @func
+    @ret(icon=ObjectHandleIcons.table, text="healthexp")
+    async def get_healthexp(
+        csv_url="https://raw.githubusercontent.com/mwaskom/seaborn-data/master/healthexp.csv",
+    ) -> object:
+        """Returns an object handle to the Excel cell (for production, this requires
+        XLWINGS_OBJECT_CACHE_URL)."""
+        return pd.read_csv(csv_url)
+
+    # 7) Object handles: turn an Excel range into a DataFrame object handle. Using an Excel
+    # table as source makes it easy to work with dynamic source ranges. This sample reuses
+    # the Df type hint from above to set index=False.
+    @func
+    async def to_df(df: Df) -> object:
+        return df
+
+    # 8) Object handles: use a pandas DataFrame query by providing a DataFrame via object
+    # handle and the query as string: [NAMESPACE].DF_QUERY(A1, "A > B")
+    @func
+    async def df_query(df: object, query: str) -> Df:
+        return df.query(query)
+
+    # 9) Object handles: Generic function that turns an object handle into Excel values
+    @func
+    async def view(obj: object, head=None):
+        """Converts an object handle to cell values. `head` can be TRUE or an integer, which
+        represents the number of rows from the top that you want to see. TRUE returns the
+        first 5 rows.
+        """
+        if head and isinstance(head, bool):
+            head = 5
+        if isinstance(obj, pd.DataFrame) and head:
+            return obj.iloc[:head, :]
+        elif isinstance(obj, (list, tuple, np.ndarray)) and head:
+            return obj[:head]
+        else:
+            return obj
+
+    # 10) Object handles: Clear the object cache manually
+    @func
+    async def clear_object_cache():
+        """Object handle: Clear the object cache manually"""
+        await utils.clear_object_cache()
+        return "Object cache cleared"
+
+    # 11) Streaming functions (the modern version of RTD functions)
+    @func
+    async def streaming_random(rows, cols):
+        """Streaming function: must be provided as async generator,
+        requires XLWINGS_ENABLE_SOCKETIO=true
+        """
+        rng = np.random.default_rng()
+        while True:
+            matrix = rng.standard_normal(size=(rows, cols))
+            df = pd.DataFrame(
+                matrix, columns=[f"col{i+1}" for i in range(matrix.shape[1])]
+            )
+            yield df
+            await asyncio.sleep(1)
+
+    # 12) To access the current user object, simply add an argument with the CurrentUser
+    # type hint
+    @func
+    def get_current_user(current_user: CurrentUser):
+        return f"{current_user}"
+
+    # 13) In-Excel SQL: query Excel ranges/tables via SQL (SQLite dialect)
+    @func
+    @arg("tables", expand="table", ndim=2)
+    def sql(query, *tables):
+        """In-Excel SQL
+        see: https://docs.xlwings.org/en/latest/extensions.html#in-excel-sql"""
+        return _sql(query, *tables)
+
+    # 14) Custom functions with side effects (experimental)
+    @func
+    async def hello_with_script(name):
+        """This function triggers a custom script, requires XLWINGS_ENABLE_SOCKETIO=true"""
+        await utils.trigger_script(custom_scripts.hello_world, exclude="MySheet")
+        return f"Hello {name}!"
+
+
+# Unit tests
+if settings.enable_tests:
+    sys.path.append(str(Path(__file__).parent.parent.resolve()))
+    from tests.e2e_custom_functions import *

xlwings_server/custom_scripts/__init__.py

@@ -0,0 +1,8 @@
+try:
+    from xlwings_server.config import settings
+except ImportError:
+    # xlwings Wasm
+    from config import settings
+
+if settings.enable_examples:
+    from .examples import *

xlwings_server/custom_scripts/examples.py

@@ -0,0 +1,94 @@
+"""
+Make sure to import the desired functions under __init__.py, e.g.:
+from .example import *
+"""
+
+try:
+    import matplotlib.pyplot as plt
+except ImportError:
+    plt = None
+import sys
+from pathlib import Path
+
+import numpy as np
+import xlwings as xw
+from xlwings.server import script
+
+from . import settings
+
+
+@script
+def hello_world(book: xw.Book):
+    sheet = book.sheets.active
+    cell = sheet["A1"]
+    if cell.value == "Hello package!":
+        cell.value = "Bye package!"
+    else:
+        cell.value = "Hello package!"
+
+
+@script
+def show_alert(book: xw.Book):
+    # callback is optional and only required if you want a JS function to be called
+    # when clicking a button. alertCallback is defined in app/static/js/core/examples.js
+    book.app.alert(
+        "This is an alert!",
+        title="xlwings Server Alert",
+        buttons="ok_cancel",
+        callback="alertCallback",
+    )
+
+
+@script
+def setup_custom_functions(book: xw.Book):
+    prefix = f"{settings.functions_namespace}"
+    if settings.environment != "prod":
+        prefix += f"_{settings.environment}".upper()
+    sheet = book.sheets.add()
+    sheet["A3"].value = f'={prefix}.HELLO("xlwings")'
+    sheet["A5"].value = f"={prefix}.STANDARD_NORMAL(3, 4)"
+    sheet["A10"].value = f"={prefix}.CORREL(A5#)"
+    if not settings.enable_wasm:
+        sheet["A16"].value = f"={prefix}.TO_DF(A5#)"
+        sheet["A18"].value = f"={prefix}.GET_HEALTHEXP()"
+        sheet[
+            "A20"
+        ].value = f"""={prefix}.DF_QUERY(A18, "Country == 'Japan' and Year > 2017")"""
+        sheet["A25"].value = f"={prefix}.VIEW(A18, 3)"
+        sheet["A30"].value = f"={prefix}.STREAMING_RANDOM(3, 4)"
+        sheet["A35"].value = f"={prefix}.GET_CURRENT_USER()"
+        sheet[
+            "A37"
+        ].value = f'={prefix}.SQL("SELECT Year, Country FROM a WHERE Spending_USD < 4600", A20#)'
+        sheet["A40"].value = f'={prefix}.HELLO_WITH_SCRIPT("xlwings")'
+    sheet.activate()
+
+
+@script
+def show_plot(book: xw.Book):
+    """Adopted from
+    https://matplotlib.org/stable/plot_types/stats/hexbin.html#sphx-glr-plot-types-stats-hexbin-py
+    """
+    if not plt:
+        raise xw.XlwingsError("You need to install Matplotlib for this example")
+    plt.style.use("_mpl-gallery-nogrid")
+    rng = np.random.default_rng()
+    x = rng.standard_normal(5000)
+    y = 1.2 * x + rng.standard_normal(5000) / 3
+    fig, ax = plt.subplots()
+    ax.hexbin(x, y, gridsize=20)
+    ax.set(xlim=(-2, 2), ylim=(-3, 3))
+    book.sheets.active.pictures.add(
+        fig, anchor=book.sheets.active["A10"], update=True, name="mplot"
+    )
+
+
+@script
+def show_error(book: xw.Book):
+    raise xw.XlwingsError("This would be your error message")
+
+
+# Unit tests
+if settings.enable_tests:
+    sys.path.append(str(Path(__file__).parent.parent.resolve()))
+    from tests.e2e_custom_scripts import *

xlwings_server/databases.py

@@ -0,0 +1,19 @@
+import redis  # TODO: use redis.asyncio when converters can be used async
+
+from .config import settings
+
+# Redis
+redis_pool = None
+if settings.object_cache_url:
+    redis_pool = redis.ConnectionPool.from_url(settings.object_cache_url)
+
+
+def get_redis_client():
+    if redis_pool is None:
+        yield None
+    else:
+        client = redis.Redis.from_pool(redis_pool)
+        try:
+            yield client
+        finally:
+            client.close()

xlwings_server/dependencies.py

@@ -0,0 +1,126 @@
+import importlib
+import json
+import logging
+from typing import Annotated, Union
+
+import redis
+import xlwings as xw
+from fastapi import Depends, Form, Header, HTTPException, Request, status
+
+from . import models
+from .config import settings
+from .databases import get_redis_client
+
+logger = logging.getLogger(__name__)
+
+
+# Book
+async def parse_book_input(
+    request: Request,
+    form_data: str | None = Form(None, alias="bookData"),
+) -> dict:
+    """Helper dependency to parse either form data (htmx)
+    or body (custom scripts & custom functions) -- couldn't make Body() work"""
+    if form_data:
+        return json.loads(form_data)
+    else:
+        body_bytes = await request.body()
+        if body_bytes:
+            body_str = body_bytes.decode("utf-8")
+            return json.loads(body_str)
+    raise HTTPException(status_code=400, detail="No book data provided")
+
+
+async def get_book(book_data: dict = Depends(parse_book_input)):
+    """Book dependency that returns the calling book and cleans it up again"""
+    book = xw.Book(json=book_data)
+    try:
+        yield book
+    finally:
+        book.close()
+
+
+Book = Annotated[xw.Book, Depends(get_book)]
+
+
+# Users/Auth
+async def authenticate(
+    token_string: str = Header(default="", alias="Authorization"),
+    auth_provider: Union[str, None] = Header(default=None),
+):
+    if not settings.auth_providers:
+        return User(id="n/a", name="Anonymous")
+    if len(settings.auth_providers) == 1:
+        provider = settings.auth_providers[0]
+    elif len(settings.auth_providers) > 1 and not auth_provider:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="With multiple auth providers, you need to provide the Auth-Provider header.",
+        )
+    elif auth_provider not in settings.auth_providers:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Auth-Provider header wasn't found in XLWINGS_AUTH_PROVIDERS setting.",
+        )
+    else:
+        provider = auth_provider
+    logger.info(f"Using auth provider {provider}")
+    # Validate the provider before import to prevent non-literal-import SAST flagging
+    if provider not in settings.auth_providers:
+        raise ValueError(f"Unsupported authentication provider: {provider}")
+    try:
+        # Try to import from project directory first (user override)
+        try:
+            module = importlib.import_module(f"auth.{provider}")
+        except ModuleNotFoundError:
+            # Fall back to package location (default implementation)
+            module = importlib.import_module(f"xlwings_server.auth.{provider}")
+        current_user = await module.validate_token(token_string)
+    except (AttributeError, ModuleNotFoundError):
+        logger.exception(f"Auth provider '{provider}' implementation missing.")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Auth provider '{provider}' implementation missing.",
+        )
+    return current_user
+
+
+async def get_user(request: Request, current_user: models.User = Depends(authenticate)):
+    # Extract IP address and attach it to the user object
+    if "x-forwarded-for" in request.headers:
+        ip_address = request.headers["x-forwarded-for"].split(",")[0].strip()
+    else:
+        ip_address = request.client.host if request.client else None
+    current_user.ip_address = ip_address
+
+    if not settings.auth_providers:
+        return current_user
+    # RBAC
+    has_required_roles = await current_user.has_required_roles(
+        settings.auth_required_roles
+    )
+    if not has_required_roles:
+        missing_roles = ", ".join(
+            set(settings.auth_required_roles).difference(current_user.roles)
+        )
+        msg = f"Auth error: Missing roles for {current_user.name}: {missing_roles}"
+        logger.warning(msg)
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=msg,
+        )
+    # Authorization
+    if not await current_user.is_authorized():
+        msg = f"Auth error: Not authorized for {current_user.name}"
+        logger.warning(msg)
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=msg,
+        )
+    return current_user
+
+
+User = Annotated[models.User, Depends(get_user)]
+
+# Redis
+RedisClient = Annotated[redis.Redis, Depends(get_redis_client)]

xlwings_server/docker_templates/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.gitignore
+.python-version
+.venv
+.env
+.env.*
+*.pyc
+__pycache__
+*.egg-info
+.DS_Store
+certs/
+README.md
+Dockerfile
+.dockerignore
+*.local.*