1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Using the Python Module — Eggdrop 1.10.1rc2 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="../_static/eggdrop.css?v=ab48a1b6" />
<script src="../_static/documentation_options.js?v=290de6c6"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Twitch" href="twitchinfo.html" />
<link rel="prev" title="Encryption/Hashing" href="pbkdf2info.html" />
</head><body>
<div class="header-wrapper" role="banner">
<div class="header">
<div class="headertitle"><a
href="../index.html">Eggdrop 1.10.1rc2 documentation</a></div>
<div class="rel" role="navigation" aria-label="related navigation">
<a href="pbkdf2info.html" title="Encryption/Hashing"
accesskey="P">previous</a> |
<a href="twitchinfo.html" title="Twitch"
accesskey="N">next</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="sidebar">
<h3>Table of Contents</h3>
<p class="caption" role="heading"><span class="caption-text">Installing Eggdrop</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../install/readme.html">README</a></li>
<li class="toctree-l1"><a class="reference internal" href="../install/install.html">Installing Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../install/upgrading.html">Upgrading Eggdrop</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Using Eggdrop</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="features.html">Eggdrop Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="core.html">Eggdrop Core Settings</a></li>
<li class="toctree-l1"><a class="reference internal" href="partyline.html">The Party Line</a></li>
<li class="toctree-l1"><a class="reference internal" href="autoscripts.html">Eggdrop Autoscripts</a></li>
<li class="toctree-l1"><a class="reference internal" href="users.html">Users and Flags</a></li>
<li class="toctree-l1"><a class="reference internal" href="bans.html">Bans, Invites, and Exempts</a></li>
<li class="toctree-l1"><a class="reference internal" href="botnet.html">Botnet Sharing and Linking</a></li>
<li class="toctree-l1"><a class="reference internal" href="ipv6.html">IPv6 support</a></li>
<li class="toctree-l1"><a class="reference internal" href="tls.html">TLS support</a></li>
<li class="toctree-l1"><a class="reference internal" href="ircv3.html">IRCv3 support</a></li>
<li class="toctree-l1"><a class="reference internal" href="accounts.html">Account tracking in Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="pbkdf2info.html">Encryption/Hashing</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Using the Python Module</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#system-requirements">System Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="#loading-python">Loading Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="#reloading-python-scripts">Reloading Python Scripts</a></li>
<li class="toctree-l2"><a class="reference internal" href="#multithreading-and-async">Multithreading and async</a></li>
<li class="toctree-l2"><a class="reference internal" href="#eggdrop-python-commands">Eggdrop Python Commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="#writing-an-eggdrop-python-script">Writing an Eggdrop Python script</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="twitchinfo.html">Twitch</a></li>
<li class="toctree-l1"><a class="reference internal" href="tricks.html">Advanced Tips</a></li>
<li class="toctree-l1"><a class="reference internal" href="text-sub.html">Textfile Substitutions</a></li>
<li class="toctree-l1"><a class="reference internal" href="tcl-commands.html">Eggdrop Tcl Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="twitch-tcl-commands.html">Eggdrop Twitch Tcl Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="patch.html">Patching Eggdrop</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/setup.html">Setting Up Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/firststeps.html">Common First Steps</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/tlssetup.html">Enabling TLS Security on Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/userfilesharing.html">Sharing Userfiles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/firstscript.html">Writing an Eggdrop Tcl Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/module.html">Writing a Basic Eggdrop Module</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Eggdrop Modules</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../modules/index.html">Eggdrop Module Information</a></li>
<li class="toctree-l1"><a class="reference internal" href="../modules/included.html">Modules included with Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../modules/writing.html">How to Write an Eggdrop Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="../modules/internals.html">Eggdrop Bind Internals</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">About Eggdrop</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../about/about.html">About Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../about/legal.html">Boring legal stuff</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="using-the-python-module">
<h1>Using the Python Module<a class="headerlink" href="#using-the-python-module" title="Link to this heading">¶</a></h1>
<p>In Eggdrop 1.10.0, Eggdrop was shipped with a Python module that, similar to the existing core Tcl capability, allows Eggdrop to run python scripts.</p>
<section id="system-requirements">
<h2>System Requirements<a class="headerlink" href="#system-requirements" title="Link to this heading">¶</a></h2>
<p>Similar to Tcl requirements, Eggdrop requires both python and python development libraries to be installed on the host machine. On Debian/Ubuntu machines, this requires the packages python-dev AND python-is-python3 to be installed. The python-is-python3 updates symlinks on the host system that allow Eggdrop to find it.</p>
<p>The minimum supported Python version is 3.8 and we do require the Global Interpreter Lock for thread safety, even if you use latest Python.</p>
</section>
<section id="loading-python">
<h2>Loading Python<a class="headerlink" href="#loading-python" title="Link to this heading">¶</a></h2>
<p>Put this line into your Eggdrop configuration file to load the python module:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">loadmodule</span> <span class="n">python</span>
</pre></div>
</div>
<p>To load a python script from your config file, place the .py file in the scripts/ folder and add the following line to your config:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pysource</span> <span class="n">scripts</span><span class="o">/</span><span class="n">myscript</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>If you need to install dependencies we recommend using virtual environments, see <a class="reference external" href="https://docs.python.org/3/library/venv.html">https://docs.python.org/3/library/venv.html</a> for more details.</p>
<p>To create the virtual environment in a hidden directory called .venv (only necessary once):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">eggdrop</span> <span class="o">&&</span> <span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">venv</span> <span class="o">.</span><span class="n">venv</span>
</pre></div>
</div>
<p>To install a python package in the above .venv directory (in this example, the requests package):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">eggdrop</span> <span class="o">&&</span> <span class="n">source</span> <span class="o">.</span><span class="n">venv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span> <span class="o">&&</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">requests</span>
</pre></div>
</div>
<p>Starting eggdrop with activated venv (must be run every time for proper functionality):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">eggdrop</span> <span class="o">&&</span> <span class="n">source</span> <span class="o">.</span><span class="n">venv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span> <span class="o">&&</span> <span class="o">./</span><span class="n">eggdrop</span>
</pre></div>
</div>
<p>You always need to start Eggdrop with the activated venv to set the necessary environment variables.</p>
</section>
<section id="reloading-python-scripts">
<h2>Reloading Python Scripts<a class="headerlink" href="#reloading-python-scripts" title="Link to this heading">¶</a></h2>
<p>Unfortunately, reloading python scripts with rehash like Tcl scripts is currently unsupported. Scripts can unbind their existing binds and re-bind them on being loaded again (see the bind section). For now, you should restart your bot when the Python scripts change.</p>
<p>You can (should?) also write scripts that manually unload their binds upon a reshash, example code looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a list to track the join binds</span>
<span class="k">if</span> <span class="s1">'JOIN_BINDS'</span> <span class="ow">in</span> <span class="nb">globals</span><span class="p">():</span>
<span class="k">for</span> <span class="n">joinbind</span> <span class="ow">in</span> <span class="n">JOIN_BINDS</span><span class="p">:</span>
<span class="n">joinbind</span><span class="o">.</span><span class="n">unbind</span><span class="p">()</span>
<span class="k">del</span> <span class="n">JOIN_BINDS</span>
<span class="n">JOIN_BINDS</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
<span class="o"><...></span>
<span class="c1"># Create the binds in the script like this</span>
<span class="n">JOIN_BINDS</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">bind</span><span class="p">(</span><span class="s2">"join"</span><span class="p">,</span> <span class="s2">"*"</span><span class="p">,</span> <span class="s2">"*"</span><span class="p">,</span> <span class="n">joinGreetUser</span><span class="p">))</span>
<span class="n">JOIN_BINDS</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">bind</span><span class="p">(</span><span class="s2">"join"</span><span class="p">,</span> <span class="s2">"o"</span><span class="p">,</span> <span class="s2">"*"</span><span class="p">,</span> <span class="n">joinGreetOp</span><span class="p">))</span>
</pre></div>
</div>
</section>
<section id="multithreading-and-async">
<h2>Multithreading and async<a class="headerlink" href="#multithreading-and-async" title="Link to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">pysource</span></code> loads a Python script in the main Eggdrop thread but is free to use both async Python and threads.</p>
</section>
<section id="eggdrop-python-commands">
<h2>Eggdrop Python Commands<a class="headerlink" href="#eggdrop-python-commands" title="Link to this heading">¶</a></h2>
<p>The Python module is built to use the existing core Tcl commands integrated into Eggdrop via the <code class="docutils literal notranslate"><span class="pre">eggdrop.tcl</span></code> module. To call an existing Tcl command from Python, you can either load the entire catalog by running <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">eggdrop.tcl</span></code>, or be more specific by <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">eggdrop.tcl</span> <span class="pre">import</span> <span class="pre">putserv,</span> <span class="pre">putlog,</span> <span class="pre">chanlist</span></code>, etc.</p>
<p>Arguments to the Tcl functions are automatically converted as follows:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">None</span></code> is converted to an empty Tcl object (the empty string, <code class="docutils literal notranslate"><span class="pre">""</span></code>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">List</span></code> and <code class="docutils literal notranslate"><span class="pre">Tuple</span></code> is converted to a <code class="docutils literal notranslate"><span class="pre">Tcl</span> <span class="pre">list</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Dict</span></code> is converted to a <code class="docutils literal notranslate"><span class="pre">Tcl</span> <span class="pre">dictionary</span></code></p></li>
<li><p>Everything else is converted to a string using the str() method</p></li>
</ul>
<p>Return values from Tcl functions must be manually converted:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">""</span></code> the empty string is automatically converted to None</p></li>
<li><p>everything else is returned as string</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Tcl</span> <span class="pre">list</span></code> as string can be converted to a Python <code class="docutils literal notranslate"><span class="pre">List</span></code> using <code class="docutils literal notranslate"><span class="pre">parse_tcl_list</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Tcl</span> <span class="pre">dictionary</span></code> as string can be converted to a Python <code class="docutils literal notranslate"><span class="pre">Dict</span></code> using <code class="docutils literal notranslate"><span class="pre">parse_tcl_list</span></code></p></li>
</ul>
<section id="bind-arguments">
<h3>bind <arguments><a class="headerlink" href="#bind-arguments" title="Link to this heading">¶</a></h3>
<p>An important difference to note is that Eggdrop Python has its own <code class="docutils literal notranslate"><span class="pre">bind</span></code> command implemented. You will generally want to create binds using the Python <code class="docutils literal notranslate"><span class="pre">bind</span></code> command and not import bind from eggdrop.tcl because a Python bind will call a Python function, whereas using the Tcl bind will call a Tcl function (not one from the script you are writing).</p>
<p>The python version of the bind command is used to create a bind that triggers a python function. The python bind takes the same arguments as the Tcl binds, but here each argument is passed individually. For example, a bind that would look like <code class="docutils literal notranslate"><span class="pre">bind</span> <span class="pre">pub</span> <span class="pre">*</span> <span class="pre">!foo</span> <span class="pre">myproc</span></code> in Tcl is written as <code class="docutils literal notranslate"><span class="pre">bind("pub",</span> <span class="pre">"*",</span> <span class="pre">"!foo",</span> <span class="pre">myproc)</span></code>. For more information on Eggsrop bind argument syntax please see <a class="reference internal" href="tcl-commands.html#bind-types"><span class="std std-ref">Bind Types</span></a>. The eggdrop.tcl.bind command should not be used as it will attempt to call a Tcl proc.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">bind</span></code> command returns a PythonBind object that has an <code class="docutils literal notranslate"><span class="pre">unbind</span></code> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="n">bind</span><span class="p">(</span><span class="s2">"pub"</span><span class="p">,</span> <span class="s2">"*"</span><span class="p">,</span> <span class="s2">"!foo"</span><span class="p">,</span> <span class="n">myproc</span><span class="p">)</span>
<span class="n">x</span><span class="o">.</span><span class="n">unbind</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="parse-tcl-list-string">
<h3>parse_tcl_list <string><a class="headerlink" href="#parse-tcl-list-string" title="Link to this heading">¶</a></h3>
<p>When a python script calls a Tcl command that returns a list via the eggdrop.tcl module, the return value will be a Tcl-formatted list- also simply known as a string. The <code class="docutils literal notranslate"><span class="pre">parse_tcl_list</span></code> command will convert the Tcl-formatted list into a Python list, which can then freely be used within the Python script.</p>
</section>
<section id="parse-tcl-dict-string">
<h3>parse_tcl_dict <string><a class="headerlink" href="#parse-tcl-dict-string" title="Link to this heading">¶</a></h3>
<p>When a python script calls a Tcl command that returns a dict via the eggdrop.tcl module, the return value will be a Tcl-formatted dict- also simply known as a string. The <code class="docutils literal notranslate"><span class="pre">parse_tcl_dict</span></code> command will convert the Tcl-formatted dict into a Python list, which can then freely be used within the Python script.</p>
</section>
</section>
<section id="writing-an-eggdrop-python-script">
<h2>Writing an Eggdrop Python script<a class="headerlink" href="#writing-an-eggdrop-python-script" title="Link to this heading">¶</a></h2>
<p>Some example scripts, complete with documentation, are included with the Python module that ships with Eggdrop (src/mod/python.mod/scripts). These scripts are included to help demonstrate script formatting and usage. The scripts are:</p>
<dl class="simple glossary">
<dt id="term-bestfriend.py">bestfriend.py<a class="headerlink" href="#term-bestfriend.py" title="Link to this term">¶</a></dt><dd><p>This example script demonstrates how to use the parse_tcl_list() python command to convert a list returned by a Tcl command into a list that is usable by Python.</p>
</dd>
<dt id="term-greet.py">greet.py<a class="headerlink" href="#term-greet.py" title="Link to this term">¶</a></dt><dd><p>This is a very basic script that demonstrates how a Python script with binds can be run by Eggdrop.</p>
</dd>
<dt id="term-imdb.py">imdb.py<a class="headerlink" href="#term-imdb.py" title="Link to this term">¶</a></dt><dd><p>This script shows how to use an existing third-party module to extend a Python script, in this case retrieving information from imdb.com.</p>
</dd>
<dt id="term-listtls.py">listtls.py<a class="headerlink" href="#term-listtls.py" title="Link to this term">¶</a></dt><dd><p>This script demonstrates how to use parse-tcl_list() and parse_tcl_dict() to convert a list of dicts provided by Tcl into something that is usable by Python.</p>
</dd>
<dt id="term-urltitle.py">urltitle.py<a class="headerlink" href="#term-urltitle.py" title="Link to this term">¶</a></dt><dd><p>This script shows how to use an existing third-party module to extend a Python script, in this case using an http parser to collect title information from a provided web page.</p>
</dd>
</dl>
<section id="header-section">
<h3>Header section<a class="headerlink" href="#header-section" title="Link to this heading">¶</a></h3>
<p>Python is able to call any Tcl command by importing the <code class="docutils literal notranslate"><span class="pre">eggdrop</span></code> module. For example, to use the <code class="docutils literal notranslate"><span class="pre">putlog</span></code> command in a python script, you would import it as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">eggdrop.tcl</span><span class="w"> </span><span class="kn">import</span> <span class="n">putlog</span>
</pre></div>
</div>
<p>and then call it using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">putlog</span><span class="p">(</span><span class="s2">"This is a logged message"</span><span class="p">)</span>
</pre></div>
</div>
<p>An important difference to note is that Eggdrop Python has its own <code class="docutils literal notranslate"><span class="pre">bind</span></code> command implemented. You will generally want to create binds using the Python <code class="docutils literal notranslate"><span class="pre">bind</span></code> command and not import bind from eggdrop.tcl because a Python bind will call a Python function, whereas using the Tcl bind will call a Tcl function (not one from the script you are writing).</p>
<p>Copyright (C) 2000 - 2025 Eggheads Development Team</p>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="pbkdf2info.html" title="Encryption/Hashing"
>previous</a> |
<a href="twitchinfo.html" title="Twitch"
>next</a>
</div>
<div role="note" aria-label="source link">
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright 2025, Eggheads.
Last updated on Aug 15, 2025.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
|
