py2max
1.0.0
一個沒有相依性的純 python3 函式庫，旨在促進離線產生 Max patcher 檔案（ .maxpat 、 .maxhelp 、 .rbnopat ）。
如果您正在尋找 Max/MSP 的 python3 外部元件，請查看 py-js 專案。
使用 Python 物件以腳本方式離線產生 Max 修補程式文件，與以.maxpat JSON 文件格式儲存的 Max/MSP 物件一一對應。
具有任意巢狀等級的 (JSON) .maxpat檔案與對應的Patcher 、 Box和Patchline Python 物件之間的往返轉換。
可以處理任何 Max 物件或 maxclass。
大量單元測試，覆蓋率約 99%。
根據組成、結構（作為物件的圖形）、物件屬性和佈局（使用圖形繪製演算法）對 Max 補丁進行分析和離線腳本修改。
允許精確佈局和配置 Max 物件。
Patcher物件具有通用方法（例如add_textbox ，也可以具有專用方法（例如add_coll 。例如，此方法有一個dictionary參數，可以輕鬆預先填入coll物件（請參閱py2max/tests/test_coll.py ）。
提供maxclassdb功能，可呼叫 Max Objects 的預設配置。
腳本化修補程式檔案建立。
批量修改現有.maxpat 檔案。
使用豐富的 python 標準函式庫和生態系統來幫助創建可參數化的對象，並透過離線來源進行配置。例如，從隨機波表檔案配置的獨特的波表振盪器。
在外部開發期間產生測試用例和.maxhelp文件
消除創建具有大量參數的物件的痛苦
使用資料預先填充容器對象，例如coll 、 dict和table對象
有助於節省建立參數略有不同的多個物件的時間
在生成的補丁上使用圖形繪製/佈局演算法。
生成補丁生成(-;
ETC..
p = Patcher ( 'my-patch.maxpat' )
osc1 = p . add_textbox ( 'cycle~ 440' )
gain = p . add_textbox ( 'gain~' )
dac = p . add_textbox ( 'ezdac~' )
osc1_gain = p . add_line ( osc1 , gain ) # osc1 outlet 0 -> gain inlet 0
gain_dac0 = p . add_line ( gain , dac , outlet = 0 , inlet = 0 )
gain_dac1 = p . add_line ( gain , dac , outlet = 0 , inlet = 1 )
p . save ()預設情況下，返回物件（包括修補線），並且修補線出口和入口設定為 0。因此，上式可以更簡潔地寫為：
p = Patcher ( 'my-patch.maxpat' )
osc1 = p . add_textbox ( 'cycle~ 440' )
gain = p . add_textbox ( 'gain~' )
dac = p . add_textbox ( 'ezdac~' )
p . add_line ( osc1 , gain )
p . add_line ( gain , dac )
p . add_line ( gain , dac , inlet = 1 )
p . save ()使用內建別名（ .add表示.add_*類型方法， .link表示.add_line ），上面的範例可以用更縮寫的形式（並使用垂直佈局）編寫為：
p = Patcher ( 'out_vertical.maxpat' , layout = 'vertical' )
osc = p . add ( 'cycle~ 440' )
gain = p . add ( 'gain~' )
dac = p . add ( 'ezdac~' )
p . link ( osc , gain )
p . link ( gain , dac )
p . link ( gain , dac , 1 )
p . save ()此外，您可以解析現有的.maxpat文件，更改它們，然後儲存變更：
p = Patcher . from_file ( 'example1.maxpat' )
# ... make some change
p . save_as ( 'example1_mod.maxpat' )另一個有子補丁的例子：
p = Patcher ( 'out.maxpat' )
sbox = p . add_subpatcher ( 'p mysub' )
sp = sbox . subpatcher
in1 = sp . add ( 'inlet' )
gain = sp . add ( 'gain~' )
out1 = sp . add ( 'outlet' )
osc = p . add ( 'cycle~ 440' )
dac = p . add ( 'ezdac~' )
sp . link ( in1 , gain )
sp . link ( gain , out1 )
p . link ( osc , sbox )
p . link ( sbox , dac )
p . save ()請注意，Python 類別基本上只是 .maxpat 檔案中 JSON 結構的簡單包裝器，幾乎所有 Max/MSP 和 Jitter 物件都可以使用.add_textbox或通用.add方法新增到修補程式檔案中。還有.add_<type>形式的專門方法，用於數字、數字參數、子補丁程序和容器類型物件（有關更多詳細信息，請參閱下面的設計說明）。
最簡單的方法：
git https://github.com/shakfu/py2max.git
cd py2max
pip install . # optional請注意，py2max 不需要安裝即可使用，因此您可以跳過pip install .如果您願意，只需cd進入克隆目錄並開始使用它：
$ cd py2max
$ ipython
In [1]: from py2max import Patcher
In [2]: p = Patcher.from_file( " tests/data/simple.maxpat " )
In [3]: p._boxes
Out[3]: [Box(id= ' obj-2 ' , maxclass= ' ezdac~ ' ), Box(id= ' obj-1 ' , maxclass= ' newobj ' )]py2max有一個廣泛的測試套件，測試位於py2max/tests資料夾中。
可以如下執行所有測試：
pytest這會將所有測試的結果輸出到outputs夾中。
請注意，如果無法匯入測試所需的套件，則可能會跳過某些測試。
您可以透過以下方式檢查跳過哪個測試：
pytest -v要檢查測試覆蓋率：
./scripts/coverage.sh其本質上是執行以下操作
mkdir -p outputs
pytest --cov-report html:outputs/_covhtml --cov=py2max tests要運行單獨的測試：
python3 -m pytest tests.test_basic請注意，由於py2max主要處理json生成和操作，因此大多數測試沒有依賴項，因為json已內建到 stdlib 中。
然而，大量測試探索了正交圖佈局演算法的應用，為此，使用了一大堆包，從眾所周知的到深奧的。
如上所述，如果未安裝所需的套件，pytest 將跳過測試，因此這些完全是可選測試。
如果您堅持深入研究，並想要執行所有測試，您將需要以下套件（及其依賴項）：
pip install networkxpip install matplotlibbrew install graphviz來完成）－然後你可以pip install pygraphvizAPI 文件仍然不可用
目前的預設佈局演算法非常初級，但是有一些有前途的方向，您還可以看到不同佈局演算法在此上下文中執行情況的視覺比較。
雖然生成不會消耗 py2max 對象，但不幸的是，Max 在打開時不會從文件刷新，因此您必須不斷關閉並重新打開 Max 才能看到對象樹的更改。
對於少數擁有自己方法的對象，當前實作透過提供帶有_tilde後綴的不同方法來區分波浪線對象和非波浪線對象：
gen = p . add_gen ()
gen_tilde = p . add_gen_tilde ().maxpat JSON 格式其實非常簡單且具有層次結構。它有一個父Patcher和子Box條目以及Patchlines 。某些盒子包含其他patcher實例來表示嵌套子補丁程式和gen~補丁程式等。
上面的結構直接映射到 Python 實現，它由 3 個類別組成： Patcher 、 Box和Patchline 。這些類別可以透過它們各自的**kwds和內部__dict__結構來擴展。事實上，這就是.from_file patcher 類別方法的實作方式。
事實證明，這是處理數百個 Max、MSP 和 Jitter 物件之間所有差異的最可維護和最靈活的方法。
已經實現了越來越多的修補程式方法來專門化和促進某些需要額外配置的物件類別的創建：
.add_attr.add_beap.add_bpatcher.add_codebox.add_coll.add_comment.add_dict.add_floatbox.add_floatparam.add_gen.add_intbox.add_intparam.add_itable.add_message.add_rnbo.add_subpatcher.add_table.add_textbox.add_umenu這是一個簡短的列表，但僅add_textbox方法就可以處理幾乎所有情況。其他的其實只是為了方便和節省打字。
一般來說，建議透過這些add_<type>方法開始使用py2max ，因為它們在方法中內建了大部分必需的參數，並且您可以獲得 IDE 補全支援。一旦您對這些參數感到滿意，就可以使用通用縮寫形式： add ，這樣可以減少輸入次數，但代價是您會失去 IDE 參數完成支援。
該項目有一些可能有用的腳本：
convert.py ：將maxpat轉換為yaml以便於開發期間閱讀compare.py ：使用 deepdiff 進行比較coverage.sh ：執行 pytest 覆蓋率並產生 html 覆蓋率報告請注意，如果您想將 py2max 建置為輪子：
pip install build
cd py2max
python3 -m build .輪子應該位於dist目錄中。
該專案有一個基於 pydantic2 專案的實驗分支。
此變體具有以下優點：
In [ 1 ]: from py2max import Patcher
In [ 2 ]: p = Patcher ( path = 'outputs/demo.maxpat' )
In [ 3 ]: msg = p . add_message ( 'set' )
In [ 4 ]: p . boxes
Out [ 4 ]: [ Box ( id = 'obj-1' , text = 'set' , maxclass = 'message' , numinlets = 2 , numoutlets = 1 , outlettype = [ '' ], patching_rect = Rect ( x = 48.0 , y = 48.0 , w = 66.0 , h = 22.0 ), patcher = None )]該變體的另一個有希望的方向是為具有自己獨特的maxclass的物件建立專門的類別。所以在這種情況下，上面的內容將是：
In [ 4 ]: p . boxes
Out [ 4 ]: [ Message ( id = 'obj-1' , text = 'set' , maxclass = 'message' , numinlets = 2 , numoutlets = 1 , outlettype = [ '' ], patching_rect = Rect ( x = 48.0 , y = 48.0 , w = 66.0 , h = 22.0 ), patcher = None )]早期的努力是提供基於屬性的屬性存取和改進的 API。它已被pydantic2分支取代，並且不會進一步開發。
版權歸原作者所有：
史蒂夫·基弗、提姆·德懷爾、金·馬裡奧特和邁克爾·懷布羅。 HOLA：類人正交網路佈局。視覺化與電腦圖形學，IEEE Transactions on，第 22 卷，第 1 期，第 349 - 358 頁。
Aric A. Hagberg、Daniel A. Schult 和 Pieter J. Swart，“使用 NetworkX 探索網絡結構、動力學和功能”，第七屆 Python 科學會議論文集 (SciPy2008)，Gäel Varoquaux、Travis Vaught 和 Jarrod Millman （編輯），（美國加州帕薩迪納），第11-15 頁，2008 年8 月
繪製有向圖的技術 Emden R. Gansner、Eleftherios Koutsofios、Stephen C. North、Kiem-phong Vo • IEEE 軟體工程交易 • 1993 年出版
Gansner, ER、Koren, Y.、North, S. (2005)。透過應力主要化繪製圖形。見：Pach, J.（編）圖形繪製。 GD 2004。 https://doi.org/10.1007/978-3-540-31843-9_25
開放圖形視覺化系統及其在軟體工程中的應用 Emden R. Gansner、Stephen C. North • 軟體 - 實務與經驗 • 2000 年出版
