<liclass="toctree-l3"><aclass="reference internal"href="#get-the-mobase-stubs">1. Get the <codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code> stubs</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="#configure-visual-studio-code-for-mobase">2. Configure Visual Studio Code for <codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code></a></li>
<liclass="toctree-l3"><aclass="reference internal"href="#configure-mypy-to-find-the-mobase-stubs">3. Configure <codeclass="docutils literal notranslate"><spanclass="pre">mypy</span></code> to find the <codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code> stubs</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="faq.html#why-is-mo2-throwing-an-exception-when-i-try-to-create-a-type-inheriting-one-of-mo2-class">1. Why is MO2 throwing an exception when I try to create a type inheriting one of MO2 class?</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="faq.html#how-can-i-be-sure-to-implement-all-the-required-methods-when-creating-a-plugin">2. How can I be sure to implement all the required methods when creating a plugin?</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="faq.html#why-are-my-isinstance-x-qobject-and-isinstance-y-qwidget-not-working">3. Why are my <codeclass="docutils literal notranslate"><spanclass="pre">isinstance(x,</span><spanclass="pre">QObject)</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">isinstance(y,</span><spanclass="pre">QWidget)</span></code> not working?</a></li>
<h1>Setting up the environment<aclass="headerlink"href="#setting-up-the-environment"title="Permalink to this headline">¶</a></h1>
<p>This page will get you started for creating a MO2 python plugin. If you have troubles getting
everything setup, feel free to come by our discord server at <aclass="reference external"href="https://discord.gg/cYwdcxj">https://discord.gg/cYwdcxj</a>.</p>
<divclass="section"id="required-tools">
<h2>Required tools<aclass="headerlink"href="#required-tools"title="Permalink to this headline">¶</a></h2>
<p>It is possible to write a MO2 python plugin using any text editor, but this guide will focus on
<aclass="reference external"href="https://code.visualstudio.com/">Visual Studio Code</a>.
This guide assumes that:</p>
<ulclass="simple">
<li><p>You have <aclass="reference external"href="https://code.visualstudio.com/">Visual Studio Code</a> installed with the
<li><p>You have Python installed: <aclass="reference external"href="https://www.python.org/downloads/">https://www.python.org/downloads/</a>.</p>
<ul>
<li><p>It is recommended but not mandatory to use the Python version that is used by MO2.
You can check the <codeclass="docutils literal notranslate"><spanclass="pre">pythonXX.dll</span></code> in the MO2 installation folder to find the Python version used by MO2 (<codeclass="docutils literal notranslate"><spanclass="pre">python38.dll</span></code> means Python 3.8).</p></li>
</ul>
</li>
<li><p>You obviously need a valid MO2 installation: <aclass="reference external"href="https://github.com/modorganizer2/modorganizer/releases">https://github.com/modorganizer2/modorganizer/releases</a></p>
<ul>
<li><p>This guide is written for MO2 ≥ 2.3.0.</p></li>
</ul>
</li>
</ul>
<p><strong>Note:</strong> In the following, I will refer to the MO2 installation directory as <codeclass="docutils literal notranslate"><spanclass="pre">$MO2DIR</span></code>. So if you
installed MO2 at <codeclass="docutils literal notranslate"><spanclass="pre">C:\MO2</span></code> and you are asked to copy a file to <codeclass="docutils literal notranslate"><spanclass="pre">$MO2DIR/plugins</span></code>, it refers to <codeclass="docutils literal notranslate"><spanclass="pre">C:\MO2\plugins</span></code>.</p>
</div>
<divclass="section"id="preparation">
<h2>Preparation<aclass="headerlink"href="#preparation"title="Permalink to this headline">¶</a></h2>
<p><strong>Note:</strong> This part is optional but highly recommended if you want a proper environment to work with.
Everything here is written to be as simple as possible but you can of course adapt it to your preferences: use a python virtual
environment, use workspace settings instead of global ones, etc.</p>
<divclass="section"id="get-the-mobase-stubs">
<h3>1. Get the <codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code> stubs<aclass="headerlink"href="#get-the-mobase-stubs"title="Permalink to this headline">¶</a></h3>
<p><codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code> is the MO2 Python module. The module is written in C++ and thus cannot be read directly by tools such
as <codeclass="docutils literal notranslate"><spanclass="pre">flake8</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">mypy</span></code>.
Instead, we provide <aclass="reference external"href="https://stackoverflow.com/questions/59051631/what-is-the-use-of-stub-files-pyi-in-python">stubs</a>
which can be used for auto-completion or type-checking.</p>
<p>The stubs for <codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code> are available at <aclass="reference external"href="https://github.com/ModOrganizer2/pystubs-generation/tree/master/stubs">https://github.com/ModOrganizer2/pystubs-generation/tree/master/stubs</a>.
You want to download the <codeclass="docutils literal notranslate"><spanclass="pre">mobase.pyi</span></code> file in the folder corresponding to your MO2 version and put it under <codeclass="docutils literal notranslate"><spanclass="pre">$MO2DIR/plugins/data</span></code>.</p>
<p><strong>Note:</strong> It is possible to put the stubs in a different location, but we are going to use <codeclass="docutils literal notranslate"><spanclass="pre">$MO2DIR/plugins/data</span></code> for PyQt5,
<h3>2. Configure Visual Studio Code for <codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code><aclass="headerlink"href="#configure-visual-studio-code-for-mobase"title="Permalink to this headline">¶</a></h3>
<p>We are going to configure Visual Studio Code to have auto-completion and linting (error and type checking)
for the MO2 Python module.
Open <codeclass="docutils literal notranslate"><spanclass="pre">settings.json</span></code> (Ctrl+Shift+P, then “Open Settings (JSON)”), and add the following entries:</p>
<h3>3. Configure <codeclass="docutils literal notranslate"><spanclass="pre">mypy</span></code> to find the <codeclass="docutils literal notranslate"><spanclass="pre">mobase</span></code> stubs<aclass="headerlink"href="#configure-mypy-to-find-the-mobase-stubs"title="Permalink to this headline">¶</a></h3>
<p>There are multiply way to configure <codeclass="docutils literal notranslate"><spanclass="pre">mypy</span></code>:</p>
<olclass="arabic simple">
<li><p>You can create a <codeclass="docutils literal notranslate"><spanclass="pre">mypy.ini</span></code> file somewhere containing:</p></li>
<p>2. You can set the <codeclass="docutils literal notranslate"><spanclass="pre">MYPYPATH</span></code> environment variable to <codeclass="docutils literal notranslate"><spanclass="pre">$MO2DIR\plugins\data</span></code> (this requires
<h3>4. [Optional] Automatically reload plugins during development<aclass="headerlink"href="#optional-automatically-reload-plugins-during-development"title="Permalink to this headline">¶</a></h3>
<p>This section is optional and requires you to already have written a “working”
plugin (a plugin that MO2 can load).</p>
<p>Since MO2 2.4 alpha 6, a new command has been added to <codeclass="docutils literal notranslate"><spanclass="pre">ModOrganizer.exe</span></code> to
reload plugins during execution.
If your plugin is named “My Plugin”, you can use the following command to reload
<p>If you are using Visual Studio Code, you can send this command to MO2 automatically
after saving files from your project.</p>
<olclass="arabic simple">
<li><p>Create a “reload plugin” task in Visual Studio Code (Ctrl+Shift+P then
<codeclass="docutils literal notranslate"><spanclass="pre">Tasks:</span><spanclass="pre">Configure</span><spanclass="pre">task</span></code> or open <codeclass="docutils literal notranslate"><spanclass="pre">.vscode/tasks.json</span></code>) using the following
snippet (replace the name and directory as needed):</p></li>
<li><p>Install the <aclass="reference external"href="https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.triggertaskonsave">Trigger Task on Save</a>
extension from Visual Studio Code marketplace.</p></li>
<li><p>Add the following to your Visual Studio Code settings (<codeclass="docutils literal notranslate"><spanclass="pre">.vscode/settings.json</span></code>)</p></li>
<h2>Testing the setup<aclass="headerlink"href="#testing-the-setup"title="Permalink to this headline">¶</a></h2>
<p>Create a new Python file in Visual Studio Code, and paste the following content (if you create
the file in <codeclass="docutils literal notranslate"><spanclass="pre">$MO2DIR\plugins</span></code>, do not forget to delete it after since it is not a valid
<li><p>If you press <codeclass="docutils literal notranslate"><spanclass="pre">Ctrl+Space</span></code> after <codeclass="docutils literal notranslate"><spanclass="pre">.down</span></code> (1), you should see the following
