Python

Python 是 Methodox Office 中繼 Lua 和 C# 之後的第三種指令碼語言。它在程式設計模型中扮演相同的角色：Scripts 窗格中的 .py 指令碼是一個 Command，functions.py 包含工作表 Function，智慧物件的源可以是一個 Python 表示式。Python 在 SteelPython 上執行，SteelPython 是套件的一部分，因此無需安裝其他任何內容。

第一個指令碼

在 Scripts 窗格的語言列表中選擇 Python，然後選擇 New script；或者開啟 Nu 示例 Circle of triangles.pptx，其中的 CircleOfTriangles.py 會繪製與 Lua 指令碼相同的三角形圓環：

import colorsys
import math

COUNT = 24      # how many triangles
RADIUS = 170    # points from the centre of the ring to the centre of each triangle
SIZE = 34       # each triangle's width and height, in points

page = doc.active_page
cx, cy = page.center_x, page.center_y

old = page.shapes.find("Ring")
if old is not None:
    old.delete()

triangles = []
for i in range(COUNT):
    angle = 360 * i / COUNT
    t = math.radians(angle)
    triangle = page.shapes.add_shape("triangle", 0, 0, SIZE, SIZE)
    triangle.center_on(cx + RADIUS * math.cos(t), cy + RADIUS * math.sin(t))
    triangle.rotation = angle + 90
    r, g, b = colorsys.hsv_to_rgb(i / COUNT, 0.65, 0.95)
    triangle.fill = "#{:02X}{:02X}{:02X}".format(int(r * 255), int(g * 255), int(b * 255))
    triangles.append(triangle)

ring = page.shapes.group(triangles)
ring.name = "Ring"
print(f"Drew {COUNT} triangles on page {page.index}.")

這些名稱就是物件模型中的名稱，採用 snake_case 形式：doc.active_page、sheet.used_range.address、doc.sheets.add(...)。doc、app、session、param 和 host 與 Lua 中一樣可用，位置從 1 開始計數（doc.sheets[1]）。與任何 Command 一樣，一次執行是一個事務，也是 Edit ▸ Undo 中的一個步驟，失敗時會回滾。從命令列執行：MethodoxNu --script CircleOfTriangles.py --save-as ring.pptx。

工作表函式

在名為 functions.py（或 anything.functions.py）的指令碼中，每個名稱為大寫字母的頂層 def 都是一個工作表函式，以 =PY.NAME(...) 的形式呼叫：

def TAX(amount: float, rate: float = 0.2) -> float:
    """Tax on an amount, at 20% unless a rate is given."""
    return amount * rate

def SUMSQ(values: list) -> float:
    """The sum of the squares of a range."""
    return sum(v * v for row in values for v in row if isinstance(v, (int, float)))

文件字串是 Insert Function 顯示的說明；預設值使參數成為可選參數，*values 可接受任意數量的實參，註解為 list 的參數以行列表的形式接收整個區域，float、str 和 bool 則會轉換實參。函式以 param.Name 讀取文件的參數，通過 host 取得資料的函式是資料來源 Function。關於函式如何重新計算、溢位和啟用，請參閱工作表函式。

智慧物件

在 Insert ▸ Smart Object 中選擇 Python，然後編寫一個基於其他智慧物件的表示式，例如 smart.Revenue * 0.2 或 smart["Revenue"] * 0.2，或者編寫一個返回值的函式體。它可以呼叫文件的 Python 函式指令碼中的函式。參見智慧物件。

文件的 Python 可以做什麼

文件的 Python 可以使用什麼取決於版本：

• Standard： 物件模型、宿主授予的呼叫，以及一系列計算類模組（math、cmath、statistics、decimal、fractions、random、re、json、datetime、calendar、zoneinfo、time、collections、itertools、functools、textwrap、heapq、bisect、copy、enum、colorsys、difflib、unicodedata、base64、hashlib、struct、array、numbers）。沒有 open、exec 或 eval，沒有 .NET 橋接，也沒有已安裝的包；匯入列表之外的模組會被拒絕，並顯示指出該模組名稱的訊息。
• Compute： 完整的 Python，包括文件環境中的包以及 SteelPython 與 .NET 之間的橋接。

即時模式（Tools ▸ Immediate）是你自己輸入的內容，因此在兩個版本中，其 Python 都擁有完全存取權限。

環境和包

包儲存在 Python 環境中，每個文件都通過其 Python Environment 設定說明其 Python 從哪個環境匯入。你傳送給別人的活頁簿攜帶的是其指令碼和該設定，而不是包的副本，因此對方需要在自己的電腦上建立該環境。

只有完全受信任的 Python 才會使用環境：即時模式，以及在 Compute 版中你啟用後的文件程式碼。在 Standard 版中，文件的指令碼執行的是經過審核的 Python，無論設定如何，它只能匯入上面列出的計算類模組。

Scripts 窗格工具條上的 Python environments and packages 按鈕會開啟 Python Environments 對話方塊。在對話方塊頂部，文件的 Python Environment 為以下之一：

• Your environment：你自己的環境，按使用者區分，儲存在 %LOCALAPPDATA%\DivookaOffice\Python\environments 中，由所有未選擇其他環境的文件共享。在它下方，你可以選擇你的哪個環境處於活動狀態，建立和刪除環境，以及在某個環境中安裝 pip。
• .venv beside the document：文件檔案旁邊的 .venv 資料夾，在你第一次選擇它時（連同 pip）自動為你建立。請先儲存文件，因為該資料夾位於文件檔案旁邊。
• A folder…：任何虛擬環境，即包含 pyvenv.cfg 的資料夾，無論是由 Python 的 venv、SteelPython 還是 Methodox Office 建立的。
• An interpreter…：一個 python.exe 或 spy.exe。位於虛擬環境內的直譯器代表該環境；不在任何虛擬環境中的直譯器代表其安裝的包，pip 會使用它執行。

位於文件旁邊或其資料夾下的選擇會以相對於文件的路徑儲存，因此包含活頁簿及其 .venv 的資料夾可以作為一個整體移動或共享。做出選擇會將文件標記為已更改；儲存文件即可保留該選擇。當你正在處理某個文件時，視窗會使用該文件的環境。

在選擇下方，對話方塊會列出環境中的包，並可以安裝（requests，或指定版本的 numpy==2.1）、升級和解除安裝包，執行時會顯示 pip 的輸出。在 Standard 版中，對話方塊會在選擇旁邊說明文件自身的指令碼只能匯入標準庫。

目前僅支援純 Python 包。 無論由哪個直譯器安裝，包都由 Methodox Office 自己的 Python（即應用程式內部的 SteelPython 3.12）匯入，因此指令碼可以保留物件模型。用 Python 編寫的包可以從任何環境匯入。帶有已編譯擴充模組的包（例如 numpy、pandas 或 lxml）可以安裝，但目前還無法在 Methodox Office 中匯入。用其他 Python 版本建立的環境會被標記出來，因為其中的包可能無法匯入。

對於 Methodox Office 建立的環境，pip 在其自己的程序 mos python 中執行，它也是命令列上的 Python；帶有自己直譯器的虛擬環境則使用該直譯器執行 pip：

mos python -V
mos python -c "print(2 ** 10)"
mos python script.py
mos python --env "%LOCALAPPDATA%\DivookaOffice\Python\environments\<name>" -m pip install requests

使用 --env 時，該環境即為安裝位置：-m pip install 會安裝到其中，-m ensurepip 會把 pip 放入其中，與虛擬環境自己的直譯器的行為相同。

另請參閱

• 指令碼
• 工作表函式
• 版本