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
|
<!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>Writing an Eggdrop Python Script — 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" />
</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">
</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>
<li class="toctree-l1"><a class="reference internal" href="../using/features.html">Eggdrop Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/core.html">Eggdrop Core Settings</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/partyline.html">The Party Line</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/autoscripts.html">Eggdrop Autoscripts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/users.html">Users and Flags</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/bans.html">Bans, Invites, and Exempts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/botnet.html">Botnet Sharing and Linking</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/ipv6.html">IPv6 support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/tls.html">TLS support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/ircv3.html">IRCv3 support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/accounts.html">Account tracking in Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/pbkdf2info.html">Encryption/Hashing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/python.html">Using the Python Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/twitchinfo.html">Twitch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/tricks.html">Advanced Tips</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/text-sub.html">Textfile Substitutions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/tcl-commands.html">Eggdrop Tcl Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/twitch-tcl-commands.html">Eggdrop Twitch Tcl Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using/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="setup.html">Setting Up Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="firststeps.html">Common First Steps</a></li>
<li class="toctree-l1"><a class="reference internal" href="tlssetup.html">Enabling TLS Security on Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="userfilesharing.html">Sharing Userfiles</a></li>
<li class="toctree-l1"><a class="reference internal" href="firstscript.html">Writing an Eggdrop Tcl Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="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="writing-an-eggdrop-python-script">
<h1>Writing an Eggdrop Python Script<a class="headerlink" href="#writing-an-eggdrop-python-script" title="Link to this heading">¶</a></h1>
<p>So you want to write an Eggdrop python script, but you don’t really know where
to begin. This file will give you a very basic idea about what Eggdrop python
scripting is like, using a <em>very</em> simple script that may help you get
started with your own scripts.</p>
<p>This guide assumes you know a bit about Eggdrops and, because it reimplements those commands, Tcl. You should have
already installed Eggdrop. The bot should not be on any important or busy
channels (development bots can be annoying if your script has bugs). If you
plan on doing a lot of development, enable the .python commands, and
make sure nobody else has access to your bot.</p>
<p>First, read through the script below. Very few commands are listed here intentionally,
but as you want to develop more advanced scripts, you will definitely want to
get familiar with the <a class="reference external" href="https://docs.eggheads.org/using/tcl-commands.html">Eggdrop custom Tcl commands</a>, as Python reimplements them.</p>
<p>If you have the .python command enabled, you can load a script by typing
‘.pysource script/file.tcl’ to load it. Otherwise, add it to your config
file like normal (examples to do so are at the bottom of the config file) and
‘.rehash’ or ‘.restart’ your bot.</p>
<p>Let’s look at a very basic example script that greets users as they join a channel:</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</span><span class="w"> </span><span class="kn">import</span> <span class="n">bind</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">putmsg</span>
<span class="k">def</span><span class="w"> </span><span class="nf">joinGreetUser</span><span class="p">(</span><span class="n">nick</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">handle</span><span class="p">,</span> <span class="n">channel</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">putmsg</span><span class="p">(</span><span class="n">channel</span><span class="p">,</span> <span class="sa">f</span><span class="s2">"Hello </span><span class="si">{</span><span class="n">nick</span><span class="si">}</span><span class="s2">, welcome to </span><span class="si">{</span><span class="n">channel</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">joinGreetOp</span><span class="p">(</span><span class="n">nick</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">handle</span><span class="p">,</span> <span class="n">channel</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">putmsg</span><span class="p">(</span><span class="n">channel</span><span class="p">,</span> <span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">nick</span><span class="si">}</span><span class="s2"> is an operator on this channel!"</span><span class="p">)</span>
<span class="k">if</span> <span class="s1">'GREET_BINDS'</span> <span class="ow">in</span> <span class="nb">globals</span><span class="p">():</span>
<span class="k">for</span> <span class="n">greetbind</span> <span class="ow">in</span> <span class="n">GREET_BINDS</span><span class="p">:</span>
<span class="n">greetbind</span><span class="o">.</span><span class="n">unbind</span><span class="p">()</span>
<span class="k">del</span> <span class="n">GREET_BINDS</span>
<span class="n">GREET_BINDS</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
<span class="n">GREET_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">GREET_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>
<span class="nb">print</span><span class="p">(</span><span class="s1">'Loaded greet.py'</span><span class="p">)</span>
</pre></div>
</div>
<p>Whew! There’s a lot going on here. You’ll generally see scripts broken into a few key parts- the header, the config section, and the code section. Ok, let’s go over this piece by piece. Any line prefixed by a # means it is comment, and thus ignored. You can type whatever you want, and it won’t matter. When writing scripts (especially if you want to give them to other people, it is good to use comments in the code to show what you’re doing.</p>
<p>Because developers are lazy and don’t want to manually reimplement every single Tcl command in Python code, Python includes a Tcl module that calls Tcl command via Python:</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</span><span class="w"> </span><span class="kn">import</span> <span class="n">bind</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">putmsg</span>
</pre></div>
</div>
<p>You can load the entire Tcl library by running <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">eggdrop.tcl</span></code>, or (the better solution to save memory) is to only load the commands you need via something like <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">eggdrop.tcl</span> <span class="pre">import</span> <span class="pre">putmsg</span></code>. The one exception to be aware of here is the bind command- you always want to load the custom python implementation of that so that it called a python bind, not a Tcl proc. Do this via <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">eggdrop</span> <span class="pre">import</span> <span class="pre">bind</span></code>.</p>
<p>Next, let’s create some functions that the main script will call:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">joinGreetUser</span><span class="p">(</span><span class="n">nick</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">handle</span><span class="p">,</span> <span class="n">channel</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">putmsg</span><span class="p">(</span><span class="n">channel</span><span class="p">,</span> <span class="sa">f</span><span class="s2">"Hello </span><span class="si">{</span><span class="n">nick</span><span class="si">}</span><span class="s2">, welcome to </span><span class="si">{</span><span class="n">channel</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">joinGreetOp</span><span class="p">(</span><span class="n">nick</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">handle</span><span class="p">,</span> <span class="n">channel</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">putmsg</span><span class="p">(</span><span class="n">channel</span><span class="p">,</span> <span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">nick</span><span class="si">}</span><span class="s2"> is an operator on this channel!"</span><span class="p">)</span>
</pre></div>
</div>
<p>Above, we create a function called joinGreetUser and a function called joinGreetOp. This function calls the putmsg Tcl. Note that the arguments here are slightly different than Tcl, requiring a comma instead of a space between the arguments.</p>
<p>We include the next code segment due to a limitation of Eggdrop’s Python module. Currently, if Eggdrop is rehashed, previously existing binds will be duplicated instead of being overwritten. This is example code checks for previously-existing binds after the script reloaded and deletes them:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="s1">'GREET_BINDS'</span> <span class="ow">in</span> <span class="nb">globals</span><span class="p">():</span>
<span class="k">for</span> <span class="n">greetbind</span> <span class="ow">in</span> <span class="n">GREET_BINDS</span><span class="p">:</span>
<span class="n">greetbind</span><span class="o">.</span><span class="n">unbind</span><span class="p">()</span>
<span class="k">del</span> <span class="n">GREET_BINDS</span>
</pre></div>
</div>
<p>As part of the above code, we need to track the binds. To do that, the GREET_BINDS list is created, and then we add the binds to it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">GREET_BINDS</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
<span class="n">GREET_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="c1"># Again, arguments are separated with a comma. This bind requires the 'o' flag to be triggered.</span>
<span class="n">GREET_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>
<p>Note that you must call binds at the end of a script (not the top, like we do in Tcl), because the functions must be defined before being called. And again, we create the binds using comma-separated arguments, not spaces like Tcl. <code class="docutils literal notranslate"><span class="pre">GREET_BINDS</span></code> is created as a JOIN bind that is triggered when a user with an operator flag joins. When it is triggered, it called the function joinGreetOp that we defined at the beginning of the script.</p>
<p>And lastly, our lovely <code class="docutils literal notranslate"><span class="pre">print('Loaded</span> <span class="pre">greet.py')</span></code> line. This is a normal python command, nothing special about it- it will only print to standard output (ie, if you’re running in a terminal). If you want to print to something like the partyline, you’d want to import and then use <code class="docutils literal notranslate"><span class="pre">putlog("Loaded</span> <span class="pre">greet.py</span></code>.</p>
<p>Copyright (C) 2003 - 2025 Eggheads Development Team</p>
</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">
</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>
|
