xlwings-server 1.1.0__py3-none-any.whl

xlwings_server/templates/examples/navigation/taskpane_three.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block content %}
+  <div class="container-fluid ps-3">
+    {% include "examples/navigation/_navigation.html" %}
+    <h1>This is Page 3</h1>
+  </div>
+{% endblock content %}

xlwings_server/templates/examples/navigation/taskpane_two.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block content %}
+  <div class="container-fluid ps-3">
+    {% include "examples/navigation/_navigation.html" %}
+    <h1>This is Page 2</h1>
+  </div>
+{% endblock content %}

xlwings_server/templates/examples/pictures/README.md

@@ -0,0 +1,42 @@
+# Pictures via htmx and Bootstrap dropdown
+
+This sample populates a Bootstrap dropdown (see https://getbootstrap.com/docs/5.3/components/dropdowns/#single-button) with the names of the png pictures in the `app/static/images/ribbon/examples` directory.
+When you select a picture name from the dropdown, it displays it below.
+
+To try it out, replace `app/routers/taskpane.py` with the following code:
+
+```python
+from fastapi import APIRouter, Form, Request
+
+from ..config import settings
+from ..templates import TemplateResponse
+
+router = APIRouter(prefix=settings.app_path)
+
+
+@router.get("/taskpane")
+@router.get("/taskpane.html")
+async def taskpane(request: Request):
+    directory = settings.static_dir / "images" / "ribbon" / "examples"
+    picture_names = []
+    for path in directory.glob("*.png"):
+        picture_names.append(path.name)
+    return TemplateResponse(
+        request=request,
+        name="examples/pictures/taskpane_pictures.html",
+        context={"picture_names": picture_names},
+    )
+
+
+@router.post("/picture")
+async def picture(request: Request, picture_name: str = Form(None)):
+    return TemplateResponse(
+        request=request,
+        name="examples/pictures/_picture.html",
+        context={"picture_name": picture_name},
+    )
+```
+
+This sample also depends on:
+
+- pictures in `app/static/images/ribbon/examples`

xlwings_server/templates/examples/pictures/_picture.html

@@ -0,0 +1,4 @@
+<img
+  src="{{ url_for('static', path='/images/ribbon/examples/' + picture_name) }}"
+  class="img-fluid"
+  alt="{{ picture_name }}" />

xlwings_server/templates/examples/pictures/taskpane_pictures.html

@@ -0,0 +1,26 @@
+{% extends "base.html" %}
+
+{% block content %}
+  <div class="container-fluid pt-3 ps-3">
+    <h1>A picture is worth a thousand words</h1>
+    <div class="dropdown">
+      <button class="btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
+        Select a picture
+      </button>
+      <ul class="dropdown-menu">
+        {% for name in picture_names %}
+          <li>
+            <a
+              class="dropdown-item"
+              hx-post="{{ url_for('picture') }}"
+              hx-target="#picture"
+              hx-vals='{"picture_name": "{{ name }}"}'
+              >{{ name }}</a
+            >
+          </li>
+        {% endfor %}
+      </ul>
+    </div>
+    <div id="picture" class="mt-4"></div>
+  </div>
+{% endblock content %}

xlwings_server/templates/manifest.xml

@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
+  xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
+  <Id>{{ manifest_id }}</Id>
+  <Version>1.0.0.0</Version>
+  <ProviderName>xlwings</ProviderName>
+  <DefaultLocale>en-US</DefaultLocale>
+  <DisplayName DefaultValue="{{ settings.project_name }}{{ ' [' + settings.environment + ']' if settings.environment != 'prod'}}" />
+  <Description DefaultValue="{{ settings.project_name }}{{ ' [' + settings.environment + ']' if settings.environment != 'prod'}}" />
+  <IconUrl DefaultValue="{{ base_url }}{{ settings.static_url_path }}/images/xlwings-32.png" />
+  <HighResolutionIconUrl DefaultValue="{{ base_url }}{{ settings.static_url_path }}/images/xlwings-64.png" />
+  <SupportUrl DefaultValue="https://www.xlwings.org/contact" />
+  <AppDomains>
+    <AppDomain>{{ base_url_with_app_path }}</AppDomain>
+  </AppDomains>
+  <Hosts>
+    <Host Name="Workbook" />
+  </Hosts>
+  <!-- SharedRuntime for Custom Functions -->
+  <Requirements>
+    <Sets DefaultMinVersion="1.1">
+      <Set Name="SharedRuntime" MinVersion="1.1" />
+    </Sets>
+  </Requirements>
+  <DefaultSettings>
+    <SourceLocation DefaultValue="{{ base_url_with_app_path }}/taskpane.html" />
+  </DefaultSettings>
+  <Permissions>ReadWriteDocument</Permissions>
+  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
+    <Hosts>
+      <Host xsi:type="Workbook">
+        <!-- Custom Functions -->
+        <Runtimes>
+          <Runtime resid="Taskpane.Url" lifetime="long" />
+        </Runtimes>
+        <AllFormFactors>
+          <ExtensionPoint xsi:type="CustomFunctions">
+            <Script>
+              <SourceLocation resid="Functions.Script.Url" />
+            </Script>
+            <Page>
+              <SourceLocation resid="Taskpane.Url" />
+            </Page>
+            <Metadata>
+              <SourceLocation resid="Functions.Metadata.Url" />
+            </Metadata>
+            {% if settings.functions_namespace or settings.environment != 'prod' %}
+            <Namespace resid="Functions.Namespace" />
+            {% endif %}
+          </ExtensionPoint>
+        </AllFormFactors>
+
+        <DesktopFormFactor>
+          <!-- FunctionFile is used to bind functions directly to Ribbon buttons -->
+          <FunctionFile resid="Taskpane.Url" />
+          <ExtensionPoint xsi:type="PrimaryCommandSurface">
+            <CustomTab id="MyTab">
+              <Group id="MyCommandsGroup">
+                <Label resid="MyCommandsGroup.Label" />
+                <Icon>
+                  <bt:Image size="16" resid="Icon.16x16" />
+                  <bt:Image size="32" resid="Icon.32x32" />
+                  <bt:Image size="80" resid="Icon.80x80" />
+                </Icon>
+
+                <!-- Ribbon button that calls a function -->
+                <Control xsi:type="Button" id="MyFunctionButton">
+                  <!-- Label for your button. resid must point to a ShortString resource -->
+                  <Label resid="MyFunctionButton.Label" />
+                  <Supertip>
+                    <!-- ToolTip title. resid must point to a ShortString resource -->
+                    <Title resid="MyFunctionButton.Label" />
+                    <!-- ToolTip description. resid must point to a LongString resource -->
+                    <Description resid="MyFunctionButton.Tooltip" />
+                  </Supertip>
+                  <Icon>
+                    <bt:Image size="16" resid="Icon.16x16" />
+                    <bt:Image size="32" resid="Icon.32x32" />
+                    <bt:Image size="80" resid="Icon.80x80" />
+                  </Icon>
+                  <!--Action type must be ExecuteFunction -->
+                  <Action xsi:type="ExecuteFunction">
+                    <!-- This is the name that you use in Office.actions.associate() to connect it to a function -->
+                    <FunctionName>hello-ribbon</FunctionName>
+                  </Action>
+                </Control>
+
+                <!-- Ribbon button that opens the task pane -->
+                <Control xsi:type="Button" id="MyTaskpaneButton">
+                  <Label resid="MyTaskpaneButton.Label" />
+                  <Supertip>
+                    <Title resid="MyTaskpaneButton.Label" />
+                    <Description resid="MyTaskpaneButton.Tooltip" />
+                  </Supertip>
+                  <Icon>
+                    <bt:Image size="16" resid="Icon.16x16" />
+                    <bt:Image size="32" resid="Icon.32x32" />
+                    <bt:Image size="80" resid="Icon.80x80" />
+                  </Icon>
+                  <!-- Action type must be ShowTaskpane -->
+                  <Action xsi:type="ShowTaskpane">
+                    <TaskpaneId>ButtonId1</TaskpaneId>
+                    <!-- resid must point to a Url Resource -->
+                    <SourceLocation resid="Taskpane.Url" />
+                  </Action>
+                </Control>
+              </Group>
+              <Label resid="MyTab.TabLabel" />
+            </CustomTab>
+          </ExtensionPoint>
+        </DesktopFormFactor>
+      </Host>
+    </Hosts>
+
+    <Resources>
+      <bt:Images>
+        <bt:Image id="Icon.16x16" DefaultValue="{{ base_url }}{{ settings.static_url_path }}/images/xlwings-16.png" />
+        <bt:Image id="Icon.32x32" DefaultValue="{{ base_url }}{{ settings.static_url_path }}/images/xlwings-32.png" />
+        <bt:Image id="Icon.80x80" DefaultValue="{{ base_url }}{{ settings.static_url_path }}/images/xlwings-80.png" />
+      </bt:Images>
+      <bt:Urls>
+        <!-- This must point to the HTML document with the task pane -->
+        <bt:Url id="Taskpane.Url" DefaultValue="{{ base_url_with_app_path }}/taskpane.html" />
+        <bt:Url id="Functions.Script.Url" DefaultValue="{{ base_url_with_app_path }}/xlwings/custom-functions-code.js" />
+        <bt:Url id="Functions.Metadata.Url" DefaultValue="{{ base_url_with_app_path }}/xlwings/custom-functions-meta.json" />
+      </bt:Urls>
+      <bt:ShortStrings>
+        {% if settings.functions_namespace or settings.environment != 'prod' %}
+        <bt:String id="Functions.Namespace" DefaultValue="{{ settings.functions_namespace|upper }}{{ '_' if settings.functions_namespace and settings.environment != 'prod'}}{{ settings.environment|upper if settings.environment != 'prod'}}" />
+        {% endif %}
+        <bt:String id="MyTab.TabLabel" DefaultValue="{{ settings.project_name }}{{ ' [' + settings.environment + ']' if settings.environment != 'prod'}}" />
+        <bt:String id="MyCommandsGroup.Label" DefaultValue="MyGroup" />
+        <bt:String id="MyFunctionButton.Label" DefaultValue="Hello World" />
+        <bt:String id="MyTaskpaneButton.Label" DefaultValue="Show Taskpane" />
+      </bt:ShortStrings>
+      <bt:LongStrings>
+        <bt:String id="MyFunctionButton.Tooltip" DefaultValue="Click to call the hello function" />
+        <bt:String id="MyTaskpaneButton.Tooltip" DefaultValue="Click to show the task pane" />
+      </bt:LongStrings>
+    </Resources>
+
+    {% if "entraid" in settings.auth_providers %}
+    <WebApplicationInfo>
+      <Id>{{ settings.auth_entraid_client_id }}</Id>
+      <Resource>api://{{ base_url_with_app_path|replace("https://", "") }}/{{ settings.auth_entraid_client_id }}</Resource>
+      <Scopes>
+        <Scope>openid</Scope>
+        <Scope>profile</Scope>
+      </Scopes>
+    </WebApplicationInfo>
+    {% endif %}
+  </VersionOverrides>
+</OfficeApp>

xlwings_server/templates/taskpane.html

@@ -0,0 +1 @@
+{% extends "base.html" %}

xlwings_server/templates/xlwings_alert.html

@@ -0,0 +1,27 @@
+{% extends "alert_base.html" %}
+
+{% block content %}
+  <div id="callback" data-callback="{{ callback }}"></div>
+  <div class="container-fluid">
+    <div class="d-flex flex-column pb-3 px-2 vh-100">
+      <h1 class="pt-4">{{ title }}</h1>
+      <p>{{ prompt|replace("\n", "<br>"|safe) }}</p>
+      <div class="mt-auto">
+        <div class="float-end">
+          {% if "ok" in buttons %}
+            <button id="ok" type="button" class="btn btn-primary btn-xl-alert">OK</button>
+          {% endif %}
+          {% if "yes" in buttons %}
+            <button id="yes" type="button" class="btn btn-primary btn-xl-alert">Yes</button>
+          {% endif %}
+          {% if "no" in buttons %}
+            <button id="no" type="button" class="btn btn-outline-secondary btn-xl-alert">No</button>
+          {% endif %}
+          {% if "cancel" in buttons %}
+            <button id="cancel" type="button" class="btn btn-outline-secondary btn-xl-alert">Cancel</button>
+          {% endif %}
+        </div>
+      </div>
+    </div>
+  </div>
+{% endblock content %}

xlwings_server/templates.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import typing
+
+from fastapi import Request
+from jinja2 import ChoiceLoader, FileSystemLoader
+from jinja2_fragments.fastapi import Jinja2Blocks
+from starlette.background import BackgroundTask
+
+from xlwings_server.config import PACKAGE_DIR, PROJECT_DIR, settings
+
+# Create Jinja2 loader that checks dist templates first (if exists),
+# then project templates, then package templates
+loaders = []
+dist_templates = PROJECT_DIR / "dist" / "templates"
+if dist_templates.exists() and settings.environment != "dev":
+    loaders.append(FileSystemLoader(dist_templates))
+loaders.extend(
+    [
+        FileSystemLoader(PROJECT_DIR / "templates"),
+        FileSystemLoader(PACKAGE_DIR / "templates"),
+    ]
+)
+loader = ChoiceLoader(loaders)
+
+
+templates = Jinja2Blocks(
+    directory=PROJECT_DIR / "templates",
+    loader=loader,
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+# Align with FastAPIs changes to the function signature
+def TemplateResponse(
+    request: Request,
+    name: str,
+    context: dict[str, typing.Any] | None = None,
+    status_code: int = 200,
+    headers: typing.Mapping[str, str] | None = None,
+    media_type: str | None = None,
+    background: BackgroundTask | None = None,
+    block_names: str | list[str] | None = None,
+    **kwargs: typing.Any,
+):
+    if context is None:
+        context = {}
+    context["request"] = request
+    context["settings"] = settings
+    return templates.TemplateResponse(
+        name,
+        context,
+        status_code,
+        headers,
+        media_type,
+        background,
+        block_name=block_names if isinstance(block_names, str) else None,
+        block_names=block_names if isinstance(block_names, list) else [],
+        **kwargs,
+    )

xlwings_server/utils.py

@@ -0,0 +1,32 @@
+import logging
+
+import redis
+
+from . import object_handles
+from .config import settings
+from .routers import socketio as socketio_router, xlwings as xlwings_router
+
+logger = logging.getLogger(__name__)
+
+
+async def trigger_script(script, **options):
+    sid = xlwings_router.socketio_id_context.get()
+    if not isinstance(script, str):
+        script = script.__name__
+    await socketio_router.sio.emit(
+        "xlwings:trigger-script",
+        {"script_name": script, **options},
+        to=sid,
+    )
+    logger.info(f"Script '{script}' triggered for sid '{sid}' with config: {options}")
+
+
+async def clear_object_cache():
+    if settings.object_cache_url:
+        redis_client: redis.Redis = xlwings_router.redis_client_context.get()
+        keys = redis_client.scan_iter(match="object:*")
+        for key in keys:
+            redis_client.delete(key)
+        logger.info("Cleared all keys starting with 'object:' from the Redis cache")
+    else:
+        object_handles.cache = {}

xlwings_server/wasm/config.py

@@ -0,0 +1,24 @@
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv(".env")
+
+# xlwings depends on this, so set before importing xlwings
+os.environ["XLWINGS_ON_SERVER"] = "true"
+
+
+def read_bool(env_name: str, default: str = "false") -> bool:
+    return os.getenv(env_name, default).lower() == "true"
+
+
+class Settings:
+    enable_examples: bool = read_bool("XLWINGS_ENABLE_EXAMPLES")
+    enable_wasm: bool = True
+    enable_tests: bool = read_bool("XLWINGS_ENABLE_TESTS")
+    environment: str = os.getenv("XLWINGS_ENVIRONMENT", "prod")
+    functions_namespace: str = os.getenv("XLWINGS_FUNCTIONS_NAMESPACE", "XLWINGS")
+    is_official_lite_addin: bool = read_bool("XLWINGS_IS_OFFICIAL_LITE_ADDIN")
+
+
+settings = Settings()

xlwings_server/wasm/main.py

@@ -0,0 +1,236 @@
+from config import settings  # noqa: F401, I001 Must be first import to load env vars
+import platform
+import traceback
+import importlib.util
+import sys
+import contextlib
+from io import StringIO
+import ast
+import inspect
+from textwrap import dedent
+
+import custom_functions
+import custom_scripts
+import js  # type: ignore
+import pyodide_js  # type: ignore
+import xlwings as xw
+import xlwings.server
+from pyodide.ffi import to_js  # type: ignore
+
+try:
+    import matplotlib as mpl
+
+    mpl.use("agg")
+except ImportError:
+    mpl = None
+
+
+# xlwings <0.33.13 doesn't have custom_scripts_meta
+if not hasattr(xlwings.server, "custom_scripts_meta"):
+    xlwings.server.custom_scripts_meta = lambda module: []
+
+
+class HtmlOutput:
+    def __init__(self, div_id):
+        self.div_id = div_id
+        self.buffer = StringIO()
+
+    def write(self, text):
+        self.buffer.write(text)
+        content = self.buffer.getvalue()
+        div = js.document.getElementById(self.div_id)
+        if div:
+            js.document.getElementById(self.div_id).innerHTML = f"<pre>{content}</pre>"
+            # Scroll to bottom
+            outputContainer = js.document.querySelector("#output-container")
+            if outputContainer:
+                outputContainer.scrollTop = outputContainer.scrollHeight
+
+    def flush(self):
+        pass
+
+
+if settings.is_official_lite_addin:
+    html_output = HtmlOutput("output")
+    try:
+        import pyodide_http  # type: ignore
+    except ImportError:
+        pyodide_http = None
+    if pyodide_http:
+        pyodide_http.patch_all()  # Fixes pd.read_csv()
+
+
+# Print Python and Pyodide versions
+def print_versions():
+    if settings.is_official_lite_addin:
+        html_output = HtmlOutput("output")
+        with (
+            contextlib.redirect_stdout(html_output),
+            contextlib.redirect_stderr(html_output),
+        ):
+            print(
+                f"Python {platform.python_version()}|Pyodide {pyodide_js.version}|xlwings {xw.__version__}"
+            )
+
+
+def create_module_from_string(module_string, module_name, html_output=None):
+    spec = importlib.util.spec_from_loader(
+        module_name,
+        loader=None,
+    )
+    module = importlib.util.module_from_spec(spec)
+    if html_output:
+        with (
+            contextlib.redirect_stdout(html_output),
+            contextlib.redirect_stderr(html_output),
+        ):
+            exec(module_string, module.__dict__)
+    else:
+        exec(module_string, module.__dict__)
+    sys.modules[module_name] = module
+    return module
+
+
+async def custom_functions_call(data):
+    if settings.is_official_lite_addin:
+        import main_editor
+
+        module = main_editor
+    else:
+        module = custom_functions
+
+    data = data.to_py()
+    try:
+        if settings.is_official_lite_addin:
+            with (
+                contextlib.redirect_stdout(html_output),
+                contextlib.redirect_stderr(html_output),
+            ):
+                result = await xlwings.server.custom_functions_call(
+                    data,
+                    module=module,
+                )
+        else:
+            result = await xlwings.server.custom_functions_call(
+                data,
+                module=module,
+            )
+    except Exception as e:
+        result = {"error": str(e), "details": traceback.format_exc()}
+    # Note: converts None to undefined
+    return to_js(result, dict_converter=js.Object.fromEntries)
+
+
+async def custom_scripts_call(data, script_name):
+    if settings.is_official_lite_addin:
+        import main_editor
+
+        module = main_editor
+    else:
+        module = custom_scripts
+
+    book = xw.Book(json=data.to_py())
+    try:
+        if settings.is_official_lite_addin:
+            with (
+                contextlib.redirect_stdout(html_output),
+                contextlib.redirect_stderr(html_output),
+            ):
+                book = await xlwings.server.custom_scripts_call(
+                    module=module,
+                    script_name=script_name,
+                    typehint_to_value={xw.Book: book},
+                )
+        else:
+            book = await xlwings.server.custom_scripts_call(
+                module=module,
+                script_name=script_name,
+                typehint_to_value={xw.Book: book},
+            )
+        result = book.json()
+        return to_js(result, dict_converter=js.Object.fromEntries)
+    except Exception as e:
+        error_traceback = traceback.format_exc()
+        if settings.is_official_lite_addin:
+            error_output = HtmlOutput(
+                "output"
+            )  # Clear output before writing out an error
+            error_output.write(f'<span style="color: red">{error_traceback}</span>')
+            return to_js({"actions": []}, dict_converter=js.Object.fromEntries)
+        else:
+            result = {"error": str(e), "details": error_traceback}
+            return to_js(result, dict_converter=js.Object.fromEntries)
+
+
+def custom_scripts_meta():
+    if settings.is_official_lite_addin:
+        import main_editor
+
+        module = main_editor
+    else:
+        module = custom_scripts
+    scripts_meta = xlwings.server.custom_scripts_meta(module)
+    return to_js(scripts_meta, dict_converter=js.Object.fromEntries)
+
+
+def get_xlwings_scripts(code_string, script_button_text):
+    try:
+        tree = ast.parse(code_string)
+    except:  # noqa: E722
+        return to_js([script_button_text])
+    xlwings_functions = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in node.decorator_list:
+                decorator_str = ast.unparse(decorator)
+                if "script" in decorator_str:
+                    xlwings_functions.append(node.name)
+                    break
+
+    # If currently selected script is still here, return it at beginning
+    if script_button_text in xlwings_functions:
+        remaining = [x for x in xlwings_functions if x != script_button_text]
+        return to_js([script_button_text] + remaining)
+
+    return to_js(xlwings_functions)
+
+
+html_output = HtmlOutput("output")
+
+
+def custom_functions_meta(module_string):
+    try:
+        module = create_module_from_string(module_string, "main")
+    except Exception as e:  # noqa: E722
+        js.console.log(f"Parsing error [custom_functions_meta]: {e}")
+        return to_js({}, dict_converter=js.Object.fromEntries)
+    return to_js(
+        xlwings.server.custom_functions_meta(module),
+        dict_converter=js.Object.fromEntries,
+    )
+
+
+def custom_functions_code(module_string):
+    try:
+        module = create_module_from_string(module_string, "main")
+    except Exception as e:  # noqa: E722
+        js.console.log(f"Parsing error [custom_functions_code]: {e}")
+        return ""
+    code = ""
+    for _, obj in inspect.getmembers(module):
+        if hasattr(obj, "__xlfunc__"):
+            xlfunc = obj.__xlfunc__
+            func_name = xlfunc["name"]
+            streaming = "true" if inspect.isasyncgenfunction(obj) else "false"
+            code += dedent(
+                f"""\
+            async function {func_name}() {{
+                let args = ["{func_name}", {streaming}]
+                args.push.apply(args, arguments);
+                return await base.apply(null, args);
+            }}
+            CustomFunctions.associate("{func_name.upper()}", {func_name});
+            """
+            )
+    return code

xlwings_server/wasm/requirements.txt

@@ -0,0 +1,5 @@
+xlwings==0.33.15
+python-dotenv==1.1.1
+pyodide-http
+pandas
+matplotlib