<h1 align="center">
<sub>
<img src=".github/assets/jishaku_logo.svg" height="36">
</sub>
jishaku
</h1>
<p align="center">
<sup>
a debugging and utility extension for discord.py bots
</sup>
<br>
<sup>
<a href="https://jishaku.readthedocs.io/">Read the documentation online.</a>
</sup>
</p>
jishaku is an extension for bot developers that enables rapid prototyping, experimentation, and debugging of features for bots.
One of jishaku's core philosophies is to be dynamic and easy-to-use. Here's the two step install:
- Download jishaku on the command line using pip:
pip install -U jishaku
- Load the extension in your bot code before it runs:
bot.load_extension('jishaku')
# or
await bot.load_extension('jishaku')
That's it!
You can also import the module to use the command development utilities.
Index
Command reference
<table>
<tr>
<td width="60px">
<img align="left" width="50" src=".github/assets/python_logo.svg">
</td>
<td>
<h4>> <code>jishaku [py|python] <argument></code></h4>
<h4>> <code>jishaku [pyi|python_inspect] <argument></code></h4>
The Python commands execute or evaluate Python code passed into them.
It supports simple expressions:
<br><br> <!-- Horrifying that I have to do this -->
<blockquote>
<p>> <i>jsk py 3+4</i></p>
<img align="left" width="50" height="50" src=".github/assets/beep_bot.svg">
<p><b>Beep Bot</b></p>
7
</blockquote>
<br>
It also supports async expressions:
<br><br>
<blockquote>
<p>> <i>jsk py await _ctx.pins()</i></p>
<img align="left" width="50" height="50" src=".github/assets/beep_bot.svg">
<p><b>Beep Bot</b></p>
[<Message id=123456789012345678 ...>, ...]
</blockquote>
<br>
You can pass in codeblocks for longer blocks of code to execute, and you can use <code>yield</code> to return intermediate results within your processing.
<br><br>
The <i>inspect</i> variant of the command will return a codeblock with detailed inspection information on all objects returned.
<br><br>
The variables available by default in all execution contexts are:
<br><br>
<table>
<tr>
<td><code>_ctx</code></td>
<td>
The <a href="https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context">Context</a> that invoked the command.
</td>
</tr>
<tr>
<td><code>_bot</code></td>
<td>
The running <a href="https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot">Bot</a> instance.
</td>
</tr>
<tr>
<td><code>_author</code><br><code>_channel</code><br><code>_guild</code><br><code>_me</code><br><code>_message</code><br><code>_msg</code></td>
<td>
Shortcuts for attributes on <a href="https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context"><code>_ctx</code></a>.
</td>
</tr>
<tr>
<td><code>_find</code><br><code>_get</code></td>
<td>
Shortcuts for <a href="https://discordpy.readthedocs.io/en/latest/api.html#utility-functions"><code>discord.utils</code></a> functions.
</td>
</tr>
</table>
<br>
The underscore prefix on the provided variables is intended to help prevent shadowing when writing large blocks of code within the command.
<br>
If you decide that you don't want the prefix, you can disable it by setting the <code>JISHAKU_NO_UNDERSCORE</code> environment variable to <code>true</code>.
<br><br>
Each Python command is individually scoped. That means variables you create won't be retained in later invocations.
<br>
You can use <code>jishaku retain on</code> to change this behavior and retain variables, and <code>jishaku retain off</code> if you change your mind later.
<br><br>
<h4>> <code>jishaku [dis|disassemble] <argument></code></h4>
This command compiles Python code in an asynchronous context, and then disassembles the resulting function into Python bytecode in the style of <code>dis.dis</code>.
<br><br>
This allows you to quickly and easily determine the bytecode that results from a given expression or piece of code. The code itself is not actually executed.
<br><br>
<h4>> <code>jishaku ast <argument></code></h4>
This command compiles Python code into its Abstract Syntax Tree, and then displays it as a formatted tree of AST blocks.
<br><br>
</td>
</tr>
</table>
<table>
<tr>
<td width="60px">
<img align="left" width="50" src=".github/assets/terminal.svg">
</td>
<td>
<h4>> <code>jishaku [sh|shell] <argument></code></h4>
The shell command executes commands within your system shell.
<br><br>
If you're on Linux and are using a custom shell, jishaku will obey the <code>SHELL</code> environment variable, otherwise, it will use <code>/bin/bash</code>.
<br>
On Windows, jishaku will use PowerShell if it's detected, otherwise, it will use Command Prompt.
<br><br>
The results from the commands you pass in are returned through a paginator interface live as the command runs. If you need to stop a command, you can press the stop button reaction, or use <code>jsk cancel</code>.
<br><br>
The execution will terminate automatically if no output is produced for 120 seconds.
<br><br>
<h4>> <code>jishaku git <argument></code></h4>
<h4>> <code>jishaku pip <argument></code></h4>
These commands act as shortcuts to the shell command, so you can save typing a word if you use these frequently.
<br><br>
</td>
</tr>
</table>
<table>
<tr>
<td width="60px">
<img align="left" width="50" src=".github/assets/extension.svg">
</td>
<td>
<h4>> <code>jishaku [load|reload] [extensions...]</code></h4>
<h4>> <code>jishaku unload [extensions...]</code></h4>
These commands load, reload, or unload extensions on your bot.
<br><br>
You can reload jishaku itself with <code>jsk reload jishaku</code>.
<br>
<code>jsk reload ~</code> will reload all extensions on your bot.
<br><br>
You can load, reload, or unload multiple extensions at once: <code>jsk reload cogs.one cogs.two</code>
<br><br>
<h4>> <code>jishaku shutdown</code></h4>
This command gracefully shuts down your bot.
<br><br>
<h4>> <code>jishaku rtt</code></h4>
This command calculates <a href="https://en.wikipedia.org/wiki/Round-trip_delay">Round-Trip Time</a> for your bot to the API. It does this by calculating response time samples, so you can tell if your bot is being slow or not.
<br><br>
<h4>> <code>jishaku sync [guild_ids...]</code></h4>
This command syncs the app_command tree for a list of guilds, or globally if none are given, and then reports the results.
<br><br>
</td>
</tr>
</table>
<table>
<tr>
<td width="60px">
<img align="left" width="50" src=".github/assets/description.svg">
</td>
<td>
<h4>> <code>jishaku cat <file></code></h4>
This command reads a file from your file system, automatically detecting encoding and (if applicable) highlighting.
<br><br>
You can use this to read things like bot logs or source files in your project.
<h4>> <code>jishaku curl <url></code></h4>
This command reads text from a URL and attempts to detect encoding and language, similar to <code>jsk cat</code>.
<br><br>
You can use this to display contents of files online, for instance, the <code>message.txt</code> files created when a message is too long, or raw files from paste sites.
<br><br>
</td>
</tr>
</table>
<table>
<tr>
<td width="60px">
<img align="left" width="50" src=".github/assets/chat.svg">
</td>
<td>
<h4>> <code>jishaku exec [member and/or channel...] <command string
