Making and submitting a standardized plugin or theme¶
This is a guide on how to create and submit a standardized plugin or theme.
Table of Contents¶
NOTICE: THE PLUGIN STORE IS NO LONGER AVAILABLE. - Submiting a plugin - Updating your plugin - Deleting a plugin - Reporting a plugin - Rating a plugin - Any problems?
Making a plugin ¶
Choosing a filename ¶
First, you make your new plugin file. For this example, we’ll be using the
discordrpc
plugin. Make a new python file preferably named to something relevant to your plugin. We’ll be choosing the filenamediscordrpc.py
for this.
Importing features from core ¶
If you want to make use of some features from the
core.py
file, you can just import them. For instance, we want to import the current theme if the plugin is printing stuff and the config if the plugin is configurable, so at the top of our python file, we will put
from systemPlugins.core import config, theme
If you want to import anything else from core, you can just add it to the list of things being imported, for instance, if you wanted to import the restart()
function, it would look like
from systemPlugins.core import config, theme, restart
Running code on calculator start ¶
If you want to run some code when the calculator is started, for instance, asking the user what their name is to adjust the config, you can just put the code underneath all of your imports in the python file. Example:
from systemPlugins.core import config, theme, restart
# Get user's name
name = input("Input your name here: ")
Giving answers¶
When giving answers, it’s better to return an answer instead of printing it. This will allow for the resulting calculation to be used in other calculations.
Printing Information ¶
If you are doing anything involving printing, like taking input or just using print()
, you should make it display with the user’s theme’s color for that type of output. To see the current color palette, you can type dev.showPalette()
in the calculator. The available styles can be found below:
Normal - No styling
Error - Error Styling
Warning - Warning Styling
Important - Important Text Styling
StartupMessage - Startup Message styling
Prompt - The color of the prompt (Default prompt is
>
)Link - Hyperlink Style
Answer - The color that is used when a function returns a value
Input - The color used for taking input (
input()
)Output - General output color
To print something with a specific color, make sure you import theme from core, and then you can print like this:
#General output
print(theme["styles"]["output"] + "This is some pretty cool general output")
#Taking input
input(theme["styles"]["input"] + "How are you liking this cool theme stuff? ")
#Using a variable
importantVariable = "YOU BETTER PAY ATTENTION TO ME BECAUSE THIS IS VERY IMPORTANT"
print(theme["styles"]["important"] + importantVariable)
Handling special events ¶
The calculator will send a signal to plugins when certain events happen. This can be taken advantage of by making a function in your plugin with the same name as the signal name. Some signals take arguments, so that you can do something with the data. Available signal names can be found below:
onRestart
- Activated when the calculator restartsonPluginsLoaded
- Activated when all plugins have been loadedonLinuxStart
- Activated when the calculator is started on a Linux operating systemonHaikuStart
- Activated when the calculator is started on HaikuonWindowsStart
- Activated when the calculator is started on WindowsonMacStart
- Activated when the calculator is started on MacOSonUnknownStart
- Activated when the calculator is started on an unknown operating systemonStarted
- Activated once calculator is fully startedonReady
- Activated once calculator is ready for user inputonInput
- Activated when user inputs something, like a calculation (passes the input as an argument)onError
- Activated on error (passes the exception type as an argument)onPrintAnswer
- Activated when the answer is printedonEofExit
- Activated when a user exits the calculator by pressing Ctrl + DonFatalError
- Activated when the calculator encountered a fatal error and cannot continue (passes the exception type as an argument)onSettingsSaved
- Activated when the settings have been saved and the config file has been updated
An example of the use of these signals can be found here:
#This is in your plugin file
def onLinuxStart():
print(theme["styles"]["output"] + "Hey, you\'re pretty cool, you use linux.")
def onWindowsStart():
print(theme["styles"]["output"] + "Ew, Windows")
#Since this passes an argument, you must add an argument in the function
def onError(err):
if err == NameError:
print(theme["styles"]["error"] + "Whatever you tried to do includes an undefined variable")
Debugging your plugin¶
While debugging your plugin a simple error type may not be enough; you may need a traceback. To get the full traceback, you can change debug
in the dev
section of the config file to true
. You can do this manually, with settings.editor()
in the calculator, or with settings.configMod("dev", "debug", "true")
.
Making a theme¶
Users can make custom themes for iicalc. This is a guide on how to create them.
Manually making a theme¶
A theme file has a basic structure. You have the section that tells all of the information about the theme and the section that defines the actual colors. Themes currently support the use of colorama colors and ANSI colors. First, make a new theme file with the .iitheme
extension. We’ll call ours test.iitheme
. Now, open the theme file in an editor and paste this theme template into it, replacing NAME
and DESCRIPTION
with the values that you are using.
[theme]
name = NAME
description = DESCRIPTION
ansi = false
[styles]
normal = No
error = No
warning = No
important = No
startupmessage = No
prompt = No
link = No
answer = No
input = No
output = No
If you are using ANSI colors, change ansi
to true
, if not, leave it as false
. Now for the fun part, the colors. You can either use ANSI colors, or if you’re going for something more basic, you can use colorama. Replace every instance of No
with the corresponding color that you would like for that value. Here is a list of what every value is for. Here are 2 examples, one for colorama and one for ANSI:
Colorama:
[styles]
normal = colorama.Fore.RESET + colorama.Back.RESET + colorama.Style.NORMAL
error = colorama.Fore.RED + colorama.Back.RESET + colorama.Style.BRIGHT
warning = colorama.Fore.YELLOW + colorama.Back.RESET + colorama.Style.NORMAL
important = colorama.Fore.MAGENTA + colorama.Back.RESET + colorama.Style.BRIGHT
startupmessage = colorama.Fore.YELLOW + colorama.Back.RESET + colorama.Style.NORMAL
prompt = colorama.Fore.GREEN + colorama.Back.RESET + colorama.Style.BRIGHT
link = colorama.Fore.BLUE + colorama.Back.RESET + colorama.Style.BRIGHT
answer = colorama.Fore.GREEN + colorama.Back.RESET + colorama.Style.NORMAL
input = colorama.Fore.CYAN + colorama.Back.RESET + colorama.Style.NORMAL
output = colorama.Fore.WHITE + colorama.Back.RESET + colorama.Style.NORMAL
ANSI:
[styles]
normal = \u001b[38;5;238m\u001b[48;5;19m
error = \u001b[38;5;197m\u001b[48;5;201m
warning = \u001b[38;2;219;203;72m
important = \u001b[38;5;236m\u001b[48;5;47m
startupmessage = \u001b[38;5;21m\u001b[48;5;39m
prompt = \u001b[38;5;227m\u001b[48;5;126m
link = \u001b[38;5;26m\u001b[48;5;137m
answer = \u001b[38;5;225m\u001b[48;5;237m
input = \u001b[38;5;178m\u001b[48;5;36m
output = \u001b[38;5;143m\u001b[48;5;225m
While ANSI gives more power over the colors, colorama is simpler, so it’s up for you to decide which best fits your needs. If you’re interested in ANSI, I’ve found this article fairly useful in getting you started.
Using a tool¶
If you don’t want to manually make a theme, or you want to have more control by using ANSI, but just can’t understand that, there are some tools to help you in making themes. I’ve included a list below of some good ones.
Builtin
themes.editor()
command - good for making themes from a command line, no ANSI support.themegui
plugin. This plugin can be installed withpm.install("themegui")
or throughpm.store()
(store.store()
is now deprecated and will be removed in a future version). This plugin uses Tkinter and has adjustable RGB values with a preview. This plugin also has ANSI support.
Publishing your plugin to the store ¶
NOTICE: THE PLUGIN STORE IS NO LONGER AVAILABLE.¶
Submiting a plugin¶
Open your browser and go to https://turbowafflz.azurewebsites.net/auth. Note that this make take a minute or two depending if the server is online or not.
Click on the “Submit a new plugin” button.
Type: Click on the first dropdown menu and select if your plugin is a plugin or a theme.
Name: Go to the name input box, and type your plugin name, preferably a name that is all lowercase.
Description: Type the description of your plugin or theme in the description box, this will be displayed on the plugin page in the store.
Short Description: Underneath the description box is the short description, this will be displayed in the store as a sort of preview description.
Version: Now put in the plugin version, this would probably be
1.0
or1.0.0
if its the first release version.Dependencies: Now you can add dependencies if you are submitting a plugin and not a theme. These can be other plugins, or PyPI packages in a comma separated list. PyPI packages must my prefixed with
pypi:
. For example, if you depended on theformulas
plugin and the PyPI packagenumpy
, you would putformulas, pypi:numpy
. This can be left blank if there are no dependencies.Download link: Go to the download link box. You must use Github or Gitlab to host the files, for instance, I have a central repository for all of my plugins that you can find here. Once you’ve uploaded your plugin to Github or Gitlab, go to the file, and hit the “Raw” button on the right if on Github, or the “Open Raw” icon button on the right if on Gitlab. Now copy the current URL and paste it into the download link input. It should look something similar to
https://raw.githubusercontent.com/user/repository/branch/file.py
orhttps://gitlab.com/user/repository/-/raw/branch/file.py
File name: Now, put the filename of the plugin on Github or Gitlab into the filename box.
File hash: Now you must get the SHA256 hash of the file. Follow the instructions below depending on your operating system. If your OS is not listed, search how to get the SHA256 has of a file on your OS.
Linux: Navigate to the directory where the file is located in your terminal, and type
sha256sum file.py
, replacing file.py with your filename.MacOS: Navigate to the directory where the file is located in your terminal, and type
shasum -a 256 file.py
, replacing file.py with your filenameWindows: Open PowerShell. Navigate to the directory where the file is located, and type
Get-FileHash file.py | Format-List
, replacing file.py with your filename. Now copy the value afterHash:
Calculator Version: This is where you put the calculator version requirements that are needed for your plugin to run. For example, if your plugin only runs on version 1.5.6 and below, you would type
<=1.5.6
in the text box. You can add multiple requirements by separating them with commas. To view more about the types of version specification you can do, look at the documentation for PEP 440Maintainers: You can add maintainers by their Github usernames. You are added automatically as a maintainer. If you do not press enter after typing a name, it will not be counted as a maintainer, though you can add or remove maintainers later on.
Updating your plugin¶
Once you want to update your plugin, you can go to https://turbowafflz.gitlab.io/updateplugin.html or click the “Update an existing plugin” button on the index portal. The same process applies for uploading a plugin, but with something to ease the proccess. If you type your plugin name into the name input and click the “Autofill” button, it will autofill the applicable information. Note that this make take a minute if the server went to sleep. You should increase the version number and recalculate the file hash and make and necessary changes, and then hit the submit button.
Deleting a plugin¶
Only the creator of a plugin can delete it. There are 2 ways to do this. The first option is to go here and select it from the list. The second option is to go to here, select your plugin, and then press the delete button on the plugin page. Note that the page’s may take a minute to load if the server went to sleep.
Reporting a plugin¶
If you find a plugin that violates our guidelines, you can report it by going to https://turbowafflz.azurewebsites.net/iicalc/browse, selecting the desired plugin, and pressing the report button on the plugin’s page.
Rating a plugin¶
There are 2 ways to rate a plugin. The first way is to go to the plugin’s page (find it at https://turbowafflz.azurewebsites.net/iicalc/browse) and hit the upvote or downvote button. You must be authenticated to do this. The 2nd way is through the calculator. Start the calculator and run pm.connect()
if you haven’t done that already. Follow the steps and once you’re authenticated, you can either run pm.rate("pluginname")
, or by going to the plugin’s store page, accessed with pm.store()
(store.store()
is now deprecated and will be removed in a future version).
Any problems?¶
Did you get an error or encounter something broken? Start an issue at https://gitlab.com/TurboWafflz/ImaginaryInfinity-Calculator/-/issues