### Install and Register xlOil

Source: https://context7.com/cunnane/xloil/llms.txt

Commands to install the xlOil package and register the add-in with Excel.

```bash
# Install the package
pip install xlOil

# Register the add-in with Excel
xloil install
```

--------------------------------

### Configure xlOil settings

Source: https://github.com/cunnane/xloil/blob/master/docs/source/Core.rst

Example of defining the base path and loading plugins in the xlOil.ini configuration file.

```toml
...
XLOIL_PATH='''C:\lib\xloil```
...
Plugins=["xloil_Python.dll", "xlOil_SQL.dll"]
```

--------------------------------

### Install xlOil Addin

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/GettingStarted.rst

Run this command in your terminal to register the xlOil addin with Excel.

```bash
xloil install
```

--------------------------------

### Test Python wheels

Source: https://github.com/cunnane/xloil/blob/master/docs/source/Developer.rst

Install and uninstall the generated wheel to verify the package structure.

```bash
cd <xloil_root>\build\staging\pypackage
pip install dist/xlOil-0.3-cp37-cp37m-win_amd64.whl
pip uninstall dist/xlOil-0.3-cp37-cp37m-win_amd64.whl
```

--------------------------------

### Install xlOil Addin

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/GettingStarted.rst

Run this command in your terminal to install the xlOil addin for creating Python-based Excel functions.

```bash
pip install xlOil
```

--------------------------------

### Create RTD Server with Custom Publisher

Source: https://context7.com/cunnane/xloil/llms.txt

Implement a custom RTD publisher in Python for fine-grained control over real-time data. This example fetches URL content periodically.

```python
import xloil as xlo
import asyncio

_rtdServer = xlo.RtdServer()

class UrlGetter(xlo.RtdPublisher):
    def __init__(self, url):
        super().__init__()
        self._url = url
        self._task = None

    def connect(self, num_subscribers):
        if self.done():
            async def run():
                try:
                    while True:
                        data = await fetch_url(self._url)
                        _rtdServer.publish(self._url, data)
                        await asyncio.sleep(4)
                except Exception as e:
                    _rtdServer.publish(self._url, e)
            self._task = xlo.get_event_loop().create_task(run())

    def disconnect(self, num_subscribers):
        if num_subscribers == 0:
            self.stop()
            return True

    def stop(self):
        if self._task is not None:
            self._task.cancel()

    def done(self):
        return self._task is None or self._task.done()

    def topic(self):
        return self._url

@xlo.func
def pyGetUrlLive(url):
    if _rtdServer.peek(url) is None:
        _rtdServer.start(UrlGetter(url))
    return _rtdServer.subscribe(url)
```

--------------------------------

### Implement fine-grained RTD control

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/Rtd.rst

Uses peek, start, and subscribe to manage publishers manually. Useful for complex scenarios like URL polling.

```python
_rtdServer = xlo.RtdServer()

@xlo.func
def pyGetUrlLive(url):
    if _rtdServer.peek(url) is None:
        publisher = UrlGetter(url)
        _rtdServer.start(publisher)
    return _rtdServer.subscribe(url)
```

--------------------------------

### Quit xloil Application

Source: https://github.com/cunnane/xloil/blob/master/tests/ManualSheets/python/TestJupyterConnection.ipynb

Commented-out example for quitting the xloil application.

```python
#xl.quit()
```

--------------------------------

### Define plugin environment variables

Source: https://github.com/cunnane/xloil/blob/master/docs/source/Core.rst

Example of setting environment variables for the Python plugin using TOML syntax, including registry lookups and variable references.

```toml
[[xlOil_Python.Environment]]
xlOilPythonVersion="3.7"

[[xlOil_Python.Environment]]
PYTHONPATH='''<HKLM\SOFTWARE\Python\PythonCore\%xlOilPythonVersion%\PythonPath\>'''
PYTHON_LIB='''<HKLM\SOFTWARE\Python\PythonCore\%xlOilPythonVersion%\InstallPath\>'''

[[xlOil_Python.Environment]]
PATH='''%PATH%;%PYTHON_LIB%;%PYTHON_LIB%\Library\bin'''
```

--------------------------------

### Get Source File Information with xloil

Source: https://github.com/cunnane/xloil/blob/master/tests/AutoSheets/TestUtils.ipynb

Retrieves source file information using xloil.importer._source_file.get().

```python
xloil.importer._source_file.get(3)
```

--------------------------------

### Call COM methods with keyword arguments

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExcelApplication.rst

Demonstrates calling Excel COM methods using keyword arguments, noting that COM arguments must start with a capital letter.

```python
xloil.app().Selection.PasteSpecial(Paste=xloil.constants.xlPasteFormulas)
```

--------------------------------

### Automate Excel with a test runner

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExcelApplication.rst

Example of driving Excel externally by creating an application instance, loading an XLL, and iterating through named ranges to validate test results.

```python
import xloil as xlo

# Create a new Excel instance and make it visible
app = xlo.Application()
app.visible = True

# Load addin
if not app.RegisterXLL("xloil.xll"):
    raise Exception("xloil load failed")

test_results = {}
for filename in ['TestUtils.xlsx, PythonTest.xlsm']:

    # Open the workbook in readonly mode: don't change the test source!
    wb = app.open(filename, read_only=True)

    app.calculate(full=True)

    # Loop through all named ranges in the workbook, looking for ones 
    # prefixed with 'Test_'.  We expect those ranges to contain True
    # for a successful test outcome.
    names = wb.to_com().Names
    for named_range in names:
        if named_range.Name.lower().startswith("Test_"):
            # skip one char as RefersTo always starts with '='
            address = named_range.RefersTo[1:]
            test_results[(filename, named_range.Name)] = wb[address].value
    
    wb.close(save=False)

app.quit()

if not all(test_results.values()):
    print("-->FAILED<--")
```

--------------------------------

### Read data from Excel ranges

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExcelApplication.rst

Examples of reading range values using xlOil syntax versus direct COM access, noting differences in return types.

```python
import xloil as xlo

# if xlOil is embedded: no need to specify Application.
# Returns a numpy array
xlo.Range("A1:C1").value

# Above is equivalent to
xlo.app().range("A1:C1").value

# Using COM (win32com) to access a range with empty index
# Returns a tuple rather than a numpy array
xlo.app().Range("A1", "C1").Value
```

--------------------------------

### Package Python Distribution with xlOil

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/DistributingAddins.rst

Use the 'xloil package' command to bundle a Python distribution, including xlOil and your custom modules, into an installer. Specify the configuration INI file and use '--hidden-import' for modules PyInstaller might miss.

```bash
xloil package myaddin.ini --hidden-import excel_funcs
```

--------------------------------

### Register a Callable Class Instance

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/Dynamic.rst

Register an instance of a class that implements the __call__ method, allowing it to be used as a function in Excel. This example accumulates a total.

```python
class Closure:
    self._total = 0
    def __call__(self, x):
        self._total += x
        return x

xlo.register_functions(Closure())
```

--------------------------------

### Create a Workbook-Specific xlOil Function

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/GettingStarted.rst

Create a Python file named after your Excel workbook (e.g., MyBook.py) in the same directory. Functions defined here will be loaded when the workbook is opened. This example shows a simple addition function that can also handle arrays.

```python
import xloil as xlo

@xlo.func
def Adder(x, y):
    return x + y
```

--------------------------------

### Create and Control Excel Application Instance

Source: https://context7.com/cunnane/xloil/llms.txt

Shows how to create a new Excel instance, control its visibility, load add-ins, open workbooks, and perform calculations.

```python
import xloil as xlo

# Create new Excel instance
app = xlo.Application()
app.visible = True
```

```python
# Load an add-in
app.RegisterXLL("xloil.xll")
```

```python
# Open workbook
wb = app.open("test.xlsx", read_only=True)
```

```python
# Calculate
app.calculate(full=True)
```

--------------------------------

### Stage the xlOil build

Source: https://github.com/cunnane/xloil/blob/master/docs/source/Developer.rst

Run the staging script from the tools directory to prepare the build.

```bash
cd <xloil_root>\tools
python stage.py
```

--------------------------------

### Create a Ribbon in an xlOil plugin

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/CustomGUI.rst

Uses XLO_PLUGIN_INIT to initialize the plugin and register the ribbon interface.

```cpp
#incude <xloil/xloil.h>

void ribbonHandler(const RibbonControl& ctrl) {}
std::shared_ptr<IComAddin> theComAddin;

XLO_PLUGIN_INIT(xloil::AddinContext* ctx, const xloil::PluginContext& plugin)
{
    xloil::linkLogger(ctx, plugin);

    auto mapper = [=](const wchar_t* name) mutable { return ribbonHandler; };
    theComAddin = makeAddinWithRibbon(
        L"TestXlOil",
        LR"(
            <customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
            ...
            </customUI>
        )", 
        mapper);

    return 0;
}
```

--------------------------------

### Build Stateful Database

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_SQL/index.rst

Create and populate an in-memory database using chained function calls.

```excel
.              A                               B       C       D   
1 =xloSqlDB()                                  MyTab   Foo     Bar
2                                                      7       2
3 =xloSqlTable(A1, C1:D4, B1)                          4       1
4                                                      8       4
5
```

--------------------------------

### Subscribe to RTD data in C++

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/CppRtd.rst

Demonstrates creating an RTD server and subscribing to live data updates using xlOil.

```c++
#include <xloil/xlOil.h>
using namespace xloil;

IRtdServer& myRtdServer()
{
  static shared_ptr<IRtdServer> ptr = newRtdServer();
  static auto backgroundTask = std::async([]()
    {
      // Somehow fetch live prices here
      ptr->publish("SP500", ExcelObj(123));
      ptr->publish("FTSE100", ExcelObj(456));
    });
  return *ptr;
}

XLO_FUNC_START(
  getStock(const ExcelObj& ticker)
)
{
  auto value = myRtdServer().subscribe(tag.toString().c_str());
  return returnValue(value
    ? *value
    : Const::Error(CellError::NA));
}
XLO_FUNC_END(getStock);
```

--------------------------------

### Get Linked Workbook Name with xloil

Source: https://github.com/cunnane/xloil/blob/master/tests/AutoSheets/TestUtils.ipynb

Retrieves the name of the currently linked workbook using xloil.linked_workbook().

```python
xloil.linked_workbook()
```

--------------------------------

### Control Excel via COM from Jupyter

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/Jupyter.rst

Use the xloil.app object to control the connected Excel instance if the xloil package is installed in the kernel.

```python
app = xloil.app()
app.workbooks.add()
```

--------------------------------

### Define an xlOil function with complex type annotations

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/TypeConversion.rst

Example of using multiple argument types and a return type annotation in an xlOil function.

```python
@xlo.func
def pySumNums(x: float, y: float, a: int = 2, b: int = 3) -> float:
    return x * a + y * b
```

--------------------------------

### Python Function for Dynamic Import

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/Dynamic.rst

This is an example Python function that can be dynamically imported into Excel using xloil.import_functions. Typing annotations and doc-strings are respected.

```python
def greet(x:str):
    return f"Hello {x}!"
```

--------------------------------

### Initialize xloil Application

Source: https://github.com/cunnane/xloil/blob/master/tests/ManualSheets/python/TestJupyterConnection.ipynb

Instantiate the xloil application object.

```python
xl = xloil.app()
```

--------------------------------

### Create Excel Ribbon Components with ExcelGUI

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/CustomGUI.rst

Instantiate ExcelGUI to manage dynamic creation of Excel Fluent Ribbon components. The funcmap links ribbon XML callbacks to Python functions.

```python
gui = xlo.ExcelGUI(r'''<customUI xmlns=...>....</<customUI>''', 
    funcmap={
        'onClick1': run_click,
        'onClick2': run_click,
        'onUpdate': update_text,
    })
```

--------------------------------

### Handle Dictionary and Keyword Arguments

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/TypeConversion.rst

Shows how to accept a dictionary and keyword arguments as a two-column array from Excel.

```python
@xlo.func
def pyTestKwargs(lookup: dict, **kwargs) -> dict:
    lookup.update(kwargs)
    return lookup
```

--------------------------------

### Register a Workbook Event Handler

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/Concepts.rst

Example of registering a Python function to handle the 'WorkbookNewSheet' event. The handler receives workbook and worksheet names and writes to a cell.

```python
def greet(workbook, worksheet):
    xlo.Range(f"[{workbook}]{worksheet}!A1") = "Hello!"

xlo.event.WorkbookNewSheet += greet
```

--------------------------------

### Create a Ribbon in a static XLL

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/CustomGUI.rst

Uses XLO_DECLARE_ADDIN to register an addin and xllOpenComCall to defer ribbon creation until the COM interface is ready.

```cpp
void ribbonHandler(const RibbonControl& ctrl) {}

struct MyAddin
{
    std::shared_ptr<IComAddin> theComAddin;
    MyAddin()
    {
        // We need this call so that xlOil defers execution of the ribbon creation
        // until Excel's COM interface is ready
        xllOpenComCall([this]()
        {
            auto mapper = [=](const wchar_t* name) mutable { return ribbonHandler; };
            theComAddin = makeAddinWithRibbon(
                L"TestXlOil",
                LR"(
                    <customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
                    ...
                    </customUI>
                )", 
                mapper);
        });
    }
};
XLO_DECLARE_ADDIN(MyAddin);
```

--------------------------------

### Basic Variable Assignment in Python

Source: https://github.com/cunnane/xloil/blob/master/tests/AutoSheets/TestUtils.ipynb

Demonstrates a simple variable assignment in Python.

```python
x=1
```

--------------------------------

### Reference xloil Application Constructor

Source: https://github.com/cunnane/xloil/blob/master/tests/ManualSheets/python/TestJupyterConnection.ipynb

Reference the `xloil.app` constructor, used for initializing the xloil application.

```python
xloil.app
```

--------------------------------

### Create xloil Address for Formulas

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExcelApplication.rst

Use xloil.Address to create a reference for use in Excel formula strings. The address is defined by start and end row/column, and optionally a sheet name.

```python
sum_start_row=0
sum_end_row=9
address = xlo.Address((sum_start_row, 1, sum_end_row, 1), sheet="Sheet1")
xlo.app().Range("A1").formula = f'=SUM({address})'  # Will be '=SUM(Sheet1!B1:B10)'
```

--------------------------------

### Create a Custom Task Pane

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/CustomGUI.rst

Adds a task pane to an existing COM addin instance.

```cpp
std::shared_ptr<ICustomTaskPane> taskPane(theComAddin->createTaskPane(L"xloil"));
taskPane->setVisible(true);
```

--------------------------------

### Define an xlOil Plugin

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/GettingStarted.rst

Use XLO_PLUGIN_INIT to register the DLL as a plugin and XLO_FUNC_START/END macros to define Excel-callable functions.

```c++
#include <xloil/xloil.h>

XLO_PLUGIN_INIT(xloil::AddinContext* ctx, const xloil::PluginContext& plugin)
{
  xloil::linkLogger(ctx, plugin);
  return 0;
}

using namespace xloil;

XLO_FUNC_START( 
    MyFunc(const ExcelObj* arg1, const ExcelObj* arg2)
)
{
    auto result = arg1->toString() + ": " + arg2->toString(L"default value");
    return ExcelObj::returnValue(result);
}
XLO_FUNC_END(MyFunc).threadsafe()
    .help(L"Joins two strings")
    .arg(L"Val1", L"First String")
    .arg(L"Val2", L"Second String");
```

--------------------------------

### Custom Return Type Converter Function

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/TypeConversion.rst

A function decorated with @xlo.returner() can be used to convert Python objects to types Excel understands. This example registers a converter for `MyType` which returns the type's name.

```python
@xlo.returner(typeof=MyType, register=True)
def mytypename(val):
  return val.__name__
  
@xlo.func
def MakeMyType():
  return MyType()
```

--------------------------------

### Asynchronous GUI Initialization and Pane Attachment in xlOil

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/CustomGUI.rst

This asynchronous function demonstrates how to initialize ExcelGUI without immediate connection and then asynchronously connect and attach a task pane. Ensure you maintain a reference to the ExcelGUI object to keep the UI connected.

```python
async def make_gui():

    # With connect=False the ctor does nothing
    excelui = xlo.ExcelGUI(xml=..., funcmap=..., connect=False)

    # The action happens when we call connect, which returns a awaitable future
    await excelui.connect()

    # We can also create the pane async by passing an awaitable but we have 
    # to then pass the name explictly
    await excelui.attach_pane_async(
        name='TkPane',
        pane=Tk_thread().submit_async(TkTaskPane))

    # We need to keep a reference to 'excelui' as deleting it disconnects the UI
    return excelui, pane
```

--------------------------------

### Register and Handle Excel Events

Source: https://context7.com/cunnane/xloil/llms.txt

Demonstrates how to hook into Excel events like calculation completion, before print, and sheet changes, and register corresponding Python callback functions.

```python
import xloil as xlo
import datetime as dt

def on_calc_finished():
    """Called after each calculation"""
    wb = xlo.active_workbook()
    rng = wb["Sheet1"]["A1"]
    rng.value = f"Calc finished at: {dt.datetime.now()}"
```

```python
def on_before_print(wbName, cancel):
    """Called before printing - can cancel the print"""
    xlo.Range("B1").value = "Print cancelled for: " + wbName
    cancel.value = True  # Cancel the print operation
```

```python
def on_sheet_change(worksheet, changed):
    """Called when cells change"""
    ws = xlo.worksheets[worksheet]
    ws["Z1"] = f"Changed: {changed.address()}"
```

```python
# Register event handlers
xlo.event.AfterCalculate += on_calc_finished
xlo.event.WorkbookBeforePrint += on_before_print
xlo.event.SheetChange += on_sheet_change
```

```python
# Unregister when done
# xlo.event.AfterCalculate -= on_calc_finished
```

--------------------------------

### Dynamic Function Registration with Closure

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/Functions.rst

Demonstrates dynamic function registration using a closure. A class 'Closure' is defined to maintain state across calls. Functions are appended to a list and then registered using xlo.register_functions.

```python
class Closure:
    self._total = 0
    def __call__(self, x):
        self._total += x
        return x

funcs.append(
    xlo.func(fn=Closure(), name=f"dynamic1", register=False)
    )

xlo.register_functions(funcs, sys.modules[__name__])
```

--------------------------------

### Upload packages to PyPI

Source: https://github.com/cunnane/xloil/blob/master/docs/source/Developer.rst

Use twine to upload the built packages to the test or production PyPI repositories.

```bash
cd <xloil_root>\build\staging\pypackage

# (Optional test)
twine upload --repository-url https://test.pypi.org/legacy/ dist/*

# The real thing
twine upload dist/*
```

--------------------------------

### Configure xlOil SQL Plugin

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_SQL/index.rst

Add the SQL plugin to the xlOil configuration file.

```ini
Plugins=["xlOil_SQL.dll"]
```

--------------------------------

### Execute SQL Join Query

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_SQL/index.rst

Join multiple data arrays using SQL syntax.

```excel
=xloSql("SELECT table1.A, B, C FROM table1 ",  { A    B  } , { A     C } )
        "INNER JOIN table2                 "   { Foo  1  }   { Bar   2 } )
        "ON table1.A == table2.A           "   { Baz  7  }   { Foo   3 } )
```

--------------------------------

### Initialize NumPy Array

Source: https://github.com/cunnane/xloil/blob/master/tests/ManualSheets/python/TestJupyterConnection.ipynb

Create a NumPy array for use in calculations.

```python
import numpy as np
watch_var = np.array([6, 2, 3, 5])
```

--------------------------------

### Configure xloil Environment Variables and Path

Source: https://github.com/cunnane/xloil/blob/master/tests/ManualSheets/python/TestJupyterConnection.ipynb

Set environment variables and append to sys.path to configure the xloil environment, specifying build and library directories.

```python
import sys
import os
soln_dir = os.path.join(os.getcwd(), r"..\..\.." "\")
os.environ['XLOIL_BIN_DIR'] = os.path.join(soln_dir, r"build\x64\Debug")
sys.path.append(os.path.join(soln_dir, r"libs\xlOil_Python\Package"))
```

--------------------------------

### Create an xlOil XLL Addin

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/DistributingAddins.rst

Use the 'xloil create' command to generate an XLL addin file and its associated INI file. This addin will attempt to load a Python script with the same base name.

```bash
xloil create myaddin.xll
```

--------------------------------

### Create a Qt Task Pane

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/CustomGUI.rst

Inherit from QWidget to create a custom task pane. Use the attach_pane method to register the widget with Excel.

```python
import xloil.gui.qtpy
from qtpy.QtWidgets import QWidget     

class QtTaskPane(QWidget):
    def __init__(self):
        super().__init__() # Don't forget this!
        ... # some code to draw the widget
    def send_signal(self, int):
        ... # some code to emit a Qt signal

excelui = xlo.create_gui(...)
pane = excelui.attach_pane('MyPane', pane=QtTaskPane)

# The widget is in the pane's `widget` attribute
pane.widget.send_signal(3)
```

--------------------------------

### Use Excel Application as Context Manager

Source: https://context7.com/cunnane/xloil/llms.txt

Shows how to manage the Excel application lifecycle using a context manager, ensuring automatic quitting.

```python
# Using as context manager
with xlo.Application() as app:
    app.visible = True
    wb = app.open("data.xlsx")
    # Work with workbook...
# App automatically quit on exit
```

--------------------------------

### Returning PIL Image from Function

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/TypeConversion.rst

This function `ShowPic` demonstrates returning a PIL Image object. Importing `xloil.pillow` registers a custom return converter for `PIL.Image`. Macro permissions are required for this function.

```python
import xloil.pillow
from PIL import Image

@xlo.func(macro=True) # macro permissions required
def ShowPic(filename):
    return Image.open(filename)
```

--------------------------------

### Create Custom Type Converters

Source: https://context7.com/cunnane/xloil/llms.txt

Shows how to define custom type converters for arguments and return values using the `@xlo.converter` decorator, enabling specialized data handling.

```python
import xloil as xlo

@xlo.converter()
def arg_doubler(x):
    """Doubles the input value"""
    if isinstance(x, xlo.ExcelArray):
        x = x.to_numpy()
    return 2 * x
```

```python
@xlo.func
def pyTestCustomConv(x: arg_doubler):
    """Input is automatically doubled"""
    return x
```

```python
# Call in Excel: =pyTestCustomConv(5)
# Result: 10
```

```python
@xlo.converter(typeof=bytes, register=True)
class StrToBytes:
    """Converts strings to/from bytes"""
    def __init__(self, encoding='utf-8'):
        self._encoding = encoding
    def read(self, val):
        return val.encode(self._encoding)
    def write(self, val):
        return val.decode(self._encoding)
```

```python
@xlo.func
def Pad(text: bytes, size: int) -> StrToBytes('utf-8'):
    return text.center(size)
```

--------------------------------

### Set Button Images using loadImage Callback

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/CustomGUI.rst

Configure ribbon buttons to display images by specifying an 'image' attribute in the customUI XML and a corresponding 'loadImage' callback function that returns a PIL Image.

```xml
<customUI loadImage="MyImageLoader" xmlns=...>
    ...
    <button id="AButton" image="icon.jpg" />
```

--------------------------------

### Create a wxPython Task Pane

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/CustomGUI.rst

Inherit from wx.Frame and use the wx_thread decorator to ensure UI updates are thread-safe.

```python
from xloil.gui.wx import wx_thread
import wx

class OurWxPane(wx.Frame):
    def __init__(self):
        super().__init__(None, title='Hello')
        ...

    @wx_thread
    def set_progress(self, x: int):
        ...

excelui = xlo.create_gui(...)
pane = excelui.attach_pane('MyPane', pane=OurWxPane)

# The frame is in the pane's `frame` attribute
pane.frame.set_progress(3)
```

--------------------------------

### Execute SQL Query with xloSqlQuery

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_SQL/index.rst

Use xloSqlQuery to fetch data from a specified table. Ensure the database connection is established before execution.

```Excel Formula
6 =xloSqlQuery(A3, "SELECT Bar FROM MyTab")
```

--------------------------------

### Declare a Statically Linked XLL

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/GettingStarted.rst

Use XLO_DECLARE_ADDIN to initialize the add-in structure when statically linking the xlOil library.

```c++
#include <xloil/xlOil.h>
#include <xloil/XllEntryPoint.h>
using namespace xloil;

struct MyAddin
{};
XLO_DECLARE_ADDIN(MyAddin);

XLO_FUNC_START( 
    MyFunc(const ExcelObj* arg1, const ExcelObj* arg2)
)
{
    auto result = arg1->toString() + ": " + arg2->toString(L"default value");
    return ExcelObj::returnValue(result);
}
XLO_FUNC_END(MyFunc).threadsafe()
    .help(L"Joins two strings")
    .arg(L"Val1", L"First String")
    .arg(L"Val2", L"Second String");
```

--------------------------------

### Execute background tasks with RTD

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/CppRtd.rst

Shows how to run slow background tasks like counters using RtdAsyncTask, ensuring the UI remains responsive.

```c++
#include <xloil/xlOil.h>
using namespace xloil;

struct Counter : public RtdAsyncTask
{
  Counter(int iStep) : _iStep(iStep) {}

  int _iStep;

  // This function arranges for the work to be done in the background, but must
  // exit when the `RtdNotifier` requests it
  std::future<void> operator()(RtdNotifier notify) override
  {
    return std::async([=, step = _iStep]()
    {
      int _count = 0;
      while (!notify.cancelled())
      {
        notify.publish(ExcelObj(_count));
        std::this_thread::sleep_for(std::chrono::seconds(2));
        _count += step;
      }
    });
  }

  // When the cell which generated the task is recalculated, xlOil cannot tell
  // whether Excel is calling it with new inputs or RTD triggered the call to get
  // a result. It uses this equality operator to determine if it already has a 
  // running task for the given set of inputs
  bool operator==(const IRtdAsyncTask& that_) const override
  {
    const auto* that = dynamic_cast<const Counter*>(&that_);
    if (!that)
      return false;
    return _iStep == that->_iStep;
  }
};

XLO_FUNC_START(
  rtdCounter(const ExcelObj& step)
)
{
  auto value = rtdAsync(
    std::make_shared<Counter>(step.toInt(1)));
  return returnValue(value ? *value : CellError::NA);
}
XLO_FUNC_END(rtdCounter);
```

--------------------------------

### Enable PIL Image Return Converter

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExternalPackages.rst

Import xloil.pillow to enable returning PIL images from worksheet functions. Images are resized by default and require macro=True in the xloil.func declaration.

```python
import xloil.pillow
from PIL import Image

@xlo.func(macro=True)
def pyTestPic():
    im = Image.open("MyPic.jpg")
    return im
```

--------------------------------

### Define and Call Custom Python Functions in Excel

Source: https://context7.com/cunnane/xloil/llms.txt

Explains how to define Python functions that can be called from Excel using the `@xlo.func` decorator and how to call Excel's built-in functions from Python.

```python
import xloil as xlo

@xlo.func
def pyCallSum(arg1, arg2, arg3):
    """Calls Excel's SUM function"""
    return xlo.call("SUM", arg1, arg2, arg3)
```

```python
@xlo.func
async def pyCallSumAsync(x, y, z):
    """Calls Excel's SUM function asynchronously"""
    return await xlo.call_async("SUM", x, y, z)
```

```python
# Application.Run equivalent for UDFs
xlo.run("MyUserDefinedFunction", arg1, arg2)
```

```python
# Via COM interface
xlo.app().WorksheetFunction.Sum(range1, range2)
```

--------------------------------

### Write data to Excel ranges

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExcelApplication.rst

Demonstrates writing data to ranges using COM, xlOil syntax with numpy arrays, and range modification operators.

```python
# Using the COM object
xlo.app().Range("A1", "B2").Value = ((1, 2), (3, 4))

rng = xlo.Range("A1:B2")
# Using xlOil syntax (can use numpy array)
rng.value = np.array([[1, 2], [3, 4]])

# Set the entire range to a single value
rng.set("hello")

# Add something
rng += " world!"
```

--------------------------------

### Accessing Excel COM interface with xlOil

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Cpp/COM.rst

Demonstrates importing the Excel type library and using the excelApp() function to modify a range. Including ExcelTypeLib.h before xlOil.h enables COM error handling for worksheet functions.

```cpp
#include <xlOil\ExcelTypeLib.h>
#include <xlOil\xlOil.h>
using namespace xloil;

XLO_FUNC_START(testToday())
{
    excelApp().Range[L"A1"]->NumberFormat = L"dd-mm-yyyy";
}
XLO_FUNC_END(testToday).macro();
```

--------------------------------

### Accessing a Variable in Python

Source: https://github.com/cunnane/xloil/blob/master/tests/AutoSheets/TestUtils.ipynb

Shows how to access a previously assigned variable in Python.

```python
x
```

--------------------------------

### xloLog Function

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Core_Functions.rst

Flushes the log file and returns its location, with an option to show the log window.

```APIDOC
## xloLog

### Description
Flushes the xlOil log file and returns its location. The log is only flushed occasionally or when an error/warning occurs. Executing this function forces a flush. Optionally, the log window can be shown, displaying recent log messages.

### Method
FUNCTION

### Endpoint
xloLog(ShowWindow=FALSE)

### Parameters
#### Path Parameters
- **ShowWindow** (boolean) - Optional - If TRUE, xlOil's log window will appear. Defaults to FALSE.

### Response
#### Success Response (200)
- **logFilePath** (string) - The location of the flushed log file.
```

--------------------------------

### Manage Application lifecycle with context manager

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExcelApplication.rst

Use the Application object as a context manager to ensure the Excel instance is closed automatically.

```python
with xloil.Application() as app:
    # do stuff
    ...

# app has been quit without saving any open Workbooks
```

--------------------------------

### Access Named Ranges via COM

Source: https://context7.com/cunnane/xloil/llms.txt

Illustrates how to access Excel's named ranges through the COM interface and retrieve their addresses and values.

```python
# Access named ranges via COM
names = wb.to_com().Names
for named_range in names:
    if named_range.Name.startswith("Test_"):
        address = named_range.RefersTo[1:]
        value = wb[address].value
```

--------------------------------

### Create a Basic xlOil Function

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/GettingStarted.rst

Define a simple Python function decorated with @xlo.func to make it available as an Excel worksheet function. Ensure the directory containing this file is in xlOil's search paths and the module is loaded.

```python
import xloil as xlo

@xlo.func
def Greeting(who):
    return "Hello  " + who
```

--------------------------------

### External Library Integrations

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ModuleReference.rst

Documentation for integrations with external libraries like pandas, Pillow, and Matplotlib.

```APIDOC
## insert_cell_image Function

### Description
Inserts an image into an Excel cell.

### Parameters
(No specific parameters detailed in the provided text.)

### Request Example
(No request example provided.)

### Response
(No specific response details provided.)
```

```APIDOC
## pandas Integration

### Description
Integration with the pandas library for data manipulation.

### PDFrame Class
- **members**: All public members of the xloil.pandas.PDFrame class.
```

```APIDOC
## pillow Integration

### Description
Integration with the Pillow library for image handling.

### ReturnImage Class
- **members**: All public members of the xloil.pillow.ReturnImage class.
```

```APIDOC
## matplotlib Integration

### Description
Integration with the Matplotlib library for plotting.

### ReturnFigure Class
- **members**: All public members of the xloil.matplotlib.ReturnFigure class.
```

--------------------------------

### Configure xlOil to load Jupyter module

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/Jupyter.rst

Add the xloil.jupyter module to the xlOil.ini file to enable Jupyter integration.

```ini
[xlOil_Python]
LoadModules=["xloil.jupyter"]
```

--------------------------------

### Close and Quit Excel Application

Source: https://context7.com/cunnane/xloil/llms.txt

Demonstrates how to close a workbook and quit the Excel application.

```python
# Close and quit
wb.close(save=False)
app.quit()
```

--------------------------------

### Miscellaneous Utilities

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ModuleReference.rst

A collection of utility functions and classes for various tasks, including asynchronous operations, date handling, and add-in management.

```APIDOC
## xloil Miscellaneous Utilities

### Description
Provides a range of utility functions and classes for common tasks, including asynchronous execution, date conversion, add-in management, and state checking.

### Functions
- **in_wizard**: Checks if running in a wizard.
- **get_async_loop**: Gets the asynchronous event loop.
- **get_event_loop**: Gets the main event loop.
- **from_excel_date**: Converts an Excel date to a Python datetime object.
- **linked_workbook**: Gets the linked workbook.
- **excel_state**: Gets the current Excel state.
- **check_abort**: Checks if an operation should be aborted.
- **run**: Runs a synchronous function in Excel.
- **run_async**: Runs an asynchronous function in Excel.
- **call**: Calls a function in the Excel main thread.
- **call_async**: Calls an asynchronous function in the Excel main thread.
- **excel_callback**: Registers a callback for Excel events.
- **source_addin**: Returns the source add-in.
- **xloil_addins**: Returns the list of xloil add-ins.
- **core_addin**: Returns the core add-in.

### Classes
- **Address**: Represents an Excel cell address.
- **Addin**: Base class for add-ins.
- **ObjectCache**: Manages cached objects.

### Data
- **cache**: An instance of ObjectCache for caching.
- **date_formats**: List of supported date formats.
- **xloil._core._AddinsDict**: Internal dictionary for add-ins.
- **xloil._core._DateFormatList**: Internal list for date formats.
- **xloil._core._LogWriter**: Internal class for logging.
- **xloil.logging.log**: Logging function.
- **xloil.debug.use_debugger**: Function to enable the debugger.
```

--------------------------------

### Define an xlOil function with type annotations

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/TypeConversion.rst

Basic syntax for declaring an xlOil function with argument type hints.

```python
@xlo.func
def DoSomething(x, y:float):
  return x
```

--------------------------------

### xloHelp Function

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Core_Functions.rst

Returns help information on an xlOil registered function.

```APIDOC
## xloHelp

### Description
Returns a two-column array containing the help information for an xlOil registered function. The first row contains the function name and the main help string. Subsequent rows contain argument names and their associated help. Help strings in the function wizard are limited to 256 characters, but xloHelp does not have this limitation.

### Method
FUNCTION

### Endpoint
xloHelp(functionName)

### Parameters
#### Path Parameters
- **functionName** (string) - Required - The name of the xlOil function to get help for.

### Response
#### Success Response (200)
- **helpInfo** (array[2 columns]) - A two-column array with function name, main help string, and argument help information.
```

--------------------------------

### Execute Code on the Qt Thread

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/CustomGUI.rst

Use the Qt_thread object or decorator to ensure functions execute on the dedicated Qt event loop thread.

```python
from xloil.gui.qtpy import Qt_thread
future = Qt_thread().submit(func, *args)        # returns a concurrent.futures.Future
future2 = Qt_thread().submit_async(func, *args) # returns an asyncio.Future
future.result()                                 # Blocks if result is required now
```

```python
@Qt_thread
def some_func():
    ...
```

--------------------------------

### Inspect Call Stack with inspect.stack()

Source: https://github.com/cunnane/xloil/blob/master/tests/AutoSheets/TestUtils.ipynb

Uses the inspect module to retrieve and display the current call stack information.

```python
import inspect
inspect.stack()
```

--------------------------------

### Call COM methods directly on xlOil application objects

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ExcelApplication.rst

Demonstrates equivalent ways to call COM methods on xlOil application objects. COM calls must be invoked on the main thread.

```python
xlo.Application().RegisterXLL(...)
```

```python
xlo.Application().to_com().RegisterXLL(...)
```

--------------------------------

### xloBlock: Creates an array from blocks

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Utils.rst

Creates a block matrix given a layout specification and input arguments. It handles auto-sizing, padding, and filling holes with #N/A.

```APIDOC
## xloBlock /api/xloil/utils/xloBlock

### Description
Creates a block matrix given a layout specification. The layout defines how input arguments are arranged into rows and columns. Supports auto-sizing for padded spaces and fills missing elements with #N/A.

### Method
APICALL

### Endpoint
/api/xloil/utils/xloBlock

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **layout** (string) - Required - A string specifying the block layout (e.g., "1, 2; 3, 4").
- **arg1, arg2, ...** (array or single value) - Required - The data blocks to be arranged according to the layout.

### Request Example
```json
{
  "layout": "1, 2; 3, 4",
  "arguments": [
    [["A", "A"], ["B", "B"]],
    [["C"]], 
    [["D"]]
  ]
}
```

### Response
#### Success Response (200)
- **result** (array) - The created block matrix.

#### Response Example
```json
{
  "result": [
    ["A", "A", "B", "B"],
    ["A", "A", "B", "B"],
    ["C", null, null, null],
    ["D", null, null, null]
  ]
}
```
```

--------------------------------

### Stateful Database Functions

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_SQL/index.rst

Functions for building and querying an in-memory database, useful for performance-critical scenarios.

```APIDOC
## xloSqlDB Function

### Description
Returns a reference to a new database object.

### Method
Excel Function

### Endpoint
xloSqlDB()

### Response
#### Success Response
- **Database Reference** (object) - A reference to a new database object.

```

```APIDOC
## xloSqlTable Function

### Description
Creates a table in a database. It is recommended to chain calls to force execution order.

### Method
Excel Function

### Endpoint
xloSqlTable(Database, Data, Name, [Headings], [Query])

### Parameters
#### Arguments
- **Database** (object) - Required - A reference to a database created with `xloSqlDB`.
- **Data** (array) - Required - An array of data with columns as fields and records as rows. Unless column headings are specified, the first row is interpreted as column names.
- **Name** (string) - Required - The name of the table in the database. This must be unique.
- **Headings** (array of string) - Optional - Column headings for the data. If specified, data is read from the first input row.
- **Query** (string) - Optional - An optional query to process the data as it is copied into the database. If omitted, "SELECT * FROM name" is used.

### Response
#### Success Response
- **Database Reference** (object) - A reference to the database, allowing for chained calls.

```

```APIDOC
## xloSqlQuery Function

### Description
Executes a SQL query on a database previously populated using `xloSqlTable`.

### Method
Excel Function

### Endpoint
xloSqlQuery(Database, Query)

### Parameters
#### Arguments
- **Database** (object) - Required - A reference to a database originally created with `xloSqlDB` but which has passed through calls to `xloSqlTable`.
- **Query** (string) - Required - A SQL query to execute. Tables referenced in the query must have been added to the database by `xloSqlTable` before this function is called.

### Response
#### Success Response
- **Result** (array) - The result of the SQL query.

### Request Example
```excel
=xloSqlQuery(A1, "SELECT * FROM MyTab WHERE Foo > 2")
```
```

--------------------------------

### Import xloil Library

Source: https://github.com/cunnane/xloil/blob/master/tests/AutoSheets/TestUtils.ipynb

Imports the xloil library for use in subsequent operations.

```python
import xloil
```

--------------------------------

### xloVersion Function

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Core_Functions.rst

Returns information on the xlOil version.

```APIDOC
## xloVersion

### Description
Returns a two-column array containing information about the xlOil version.

### Method
FUNCTION

### Endpoint
xloVersion()

### Parameters
None

### Response
#### Success Response (200)
- **versionInfo** (array[2 columns]) - A two-column array with version information.
```

--------------------------------

### NewWorkbook Event

Source: https://github.com/cunnane/xloil/blob/master/docs/source/Events.rst

Occurs when a new workbook is created. Takes a single parameter containing the workbook name.

```APIDOC
## NewWorkbook Event

Occurs when a new workbook is created. Takes a single parameter containing the workbook name.
```

--------------------------------

### Logging and Debugging

Source: https://github.com/cunnane/xloil/blob/master/docs/source/xlOil_Python/ModuleReference.rst

API documentation for the logging and debugging modules.

```APIDOC
## Logging Module

### Description
Provides logging functionalities for the xloil library.

### Members
- **members**: All public members of the xloil.logging module.
```

```APIDOC
## Debug Module

### Description
Provides debugging utilities for the xloil library.

### Members
- **members**: All public members of the xloil.debug module.
```