Package: smalld-click
SmallD-ClickSmallD-Click is an extension forSmallDthat enables the use ofClickCLI applications as discord bots.InstallingInstall using pip:$pipinstallsmalld-clickExampleimportclickfromsmalldimportSmallDfromsmalld_clickimportSmallDCliRunner@click.command()@click.option("--count",default=1,help="Number of greetings.")@click.option("--name",prompt="Your name",help="The person to greet.")defhello(count,name):"""Simple program that greets NAME for a total of COUNT times."""forxinrange(count):click.echo("Hello%s!"%name)smalld=SmallD()withSmallDCliRunner(smalld,hello,prefix="++"):smalld.run()For this CLI example, if a user sends the message "++hello --count=2", then the bot will ask the user -
by sending a message in the same channel - for their name, "Your name:".If the user answers with "lymni", for example, the bot will send the message, "Hello lymni", twice.Notice that the bot responds in a single message, instead of two, even though we callclick.echomultiple times.
This is because calls to echo are buffered. However, calls to prompt will cause this buffer to be flushed and its
content is sent immediately.There is also a timeout for how long the bot will wait for the user's message, if the timeout is exceeded the bot will
simply drop the execution of the command.For an example with multiple commands that run under different names (i.e, with no common base command name)
see themulticommands bot.GuideSmallDCliRunner(smalld,cli,prefix="",name=None,timeout=60,create_message=None,executor=None)TheSmallDCliRunneris the core class for running CLI applications.smalldtheSmallDinstance for your bot.cliaclick.Commandinstance to use for running the commands.prefixeach command invocation must start with this string.namethe name of the CLI application, defaults tocli.name. Can be used to change the command's name,
or completely remove it by passing the empty string. Used with the prefix to determine what messages
to consider as invocations of the CLI application.timeouthow long will the bot wait for the user to respond to a prompt in seconds.create_messagea callback for creating the message payload for discord's create message route.
By default, text is sent as is in the content field of the payload.executoran instance ofconcurrent.futures.Executorused to execute commands. By default,
this is aconcurrent.futures.ThreadPoolExecutor.Instances of this class should be used as a context manager, to patch click functions and to properly close
the executor when the bot stops.Conversation(runner,message)Represents the the state of the command invocation. Holds the runner instance, and the message payload.
Also manages the interactions between the user and the CLI application.After each prompt, the message is updated to the latest message sent by the user.get_conversation()Returns the current conversation. Must only be invoked inside of a command handler.Patched functionalityYou can useclick.echo, andclick.promptdirectly to send/wait for messages.prompts that are hidden, usinghide_input=True, are sent to the user DM, and cause the conversation to continue there.Note that, echo and prompt will send a message in the same channel as the message that triggered the command invocation.Calls to echo are buffered. When the buffer is flushed, its content is sent in 2K chunks (limit set by discord.)
The buffer can be flushed automatically when there is a prompt, or the command finishes execution, or the content
in the buffer exceeds the 2K limit.It's also possible to flush the buffer by passingflush=Truetoclick.echocall.AcknowledgementsOriginal idea byPrincess Lana.ContributingToxis used for running tests.Runtox -eto run tests with your installed python versionRuntox -e fmtto format the codeConventional Commitsis used for commit messages and pull requestsDevelopingTox is used to setup and manage virtual environments when working on SmallD-ClickTo run tests:$toxTo run the examples greet bot:$tox-erun--examples/greet.py