Version 1.0.3

.github/workflows/github-actions.yml

@@ -20,9 +20,9 @@ jobs:
         run:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
-      - name: unit test
+      - name: unit tests
         run: |
-          cd tests
-          python -m unittest
+          python -m unittest tests/test_client.py
+          python -m unittest tests/test_handler.py
       # - name: build project
       #   run: python -m build --sdist

README.md

@@ -569,8 +569,9 @@ $endif
 - More custom functions
 - Documentation
 - Сontributing
+- Plugins (mods)
 ## In the Future🚀
 - More usefull $eval/$pyeval
-- Support of mods
+- Compiled version or support for other langs
 
 #### Repository and first lines of code by [MZshnik](https://github.com/MZshnik)

docs/CONTRIBUTING.md

@@ -74,6 +74,10 @@ def setup(handler):
 3. Register new folder in [`__init__.py`](/src/MZscript/Functions/__init__.py) like other modules or in `__init__.py` file of folder if you dont create new folder, only file  
 Next steps writed in this [header](https://github.com/MZshnik/MZscript/blob/main/docs/CONTRIBUTING.md#creating-new-function)
 ### What about events
-This topic will be created later
+Now, events taked from basic disnake lib. Its just `on_ready`, `on_message` and other. MZClient only wrap it with beautiful MZscript code
+
+This topic is not ended, but you can help end up it!
 ### Modify library
-This topic will be created later
+In this context we talking about library how low-level functionality and code: interpreter, parser, database and etc.  
+If you dont know how library works, please, dont change anything: best way is say anyone your idea or create pull request with changes - its a very frail layer.  
+However, this code has amout of doc stings, comments and instruments what interdement developer (maybe) know so you actually can understand this massive work and help us imvprove some things or add new!

docs/DOCS.md

@@ -25,10 +25,10 @@ $else uses for say to code what if $if return False, we go to block of $else. Yo
 Needs for end $if block. If you write $if - you need to write after him $endif. Its necessary.
 
 ## Good job! We go next - creating I/O commands.
-Main thing what you need to think - plane text not sends. You need to write $sendMessage for sending message.
+Main thing what you need to think - plane text not sends. You need to write $sendMessage for sending messages.
 ### And not less important - creating commands:
 > dont miss to install last version by
-> `pip install --update git+https://github.com/MZshnik/MZscript`  
+> `pip install --upgrade git+https://github.com/MZshnik/MZscript`  
 
 First all, you need to import library
 ```py
@@ -62,16 +62,16 @@ bot.run("your bot token")
 ```
 
 Now you can `python main.py` or run your code or file how you want or can.  
-You can test your first command by typing `!help` in the channel where bot can send and view messages.  
+Test your first command by typing `!help` in the channel where bot can send and view messages.  
 By default, MZClient uses all the intents that discord bots have, but you can configure it like this:
 ```py
 bot = MZClient(intents="all") # best way is not set intents
 ```
 Or just set intents how you want or need:)
 ```py
-from disnake import Intents
+from disnake import Intents # disnake module is installed with mzscript
 intents = Intents.all()
-intents.members = False # not recomened
+intents.members = False # not recommened
 bot = MZClient(intents=intents)
 ```
 ## Lets talk about commands
@@ -101,14 +101,41 @@ Events is more important thing in bot developering. You can add event in your co
 ```py
 bot.add_event(name="message", code="""
 $console[Some guy send message in $channelInfo[name]]
-"""
+""")
+```
+> It is worth saying that some events used by library by default. You can edit events in lib code with plugins if you want to control events by self
+### Plugins
+Have you ever thought that you need to add some kind of extra single function that obviously no one wants to do? Plugins is your solution!  
+Plugins, in order, its python code what interacted with MZClient class what you instantiate in MZscript. They can modify lib code in runtime or add new things.
+You can load multi plugins, but they are works in 1 thread and can stop execution of other plugins, so keep that in mind and sort adding plugins.  
+To import plugin, use `from <module> import <plugin>` where `<module>` is name/path of plugin file and `<plugin>` is name of plugin. After this add plugin to bot by `bot.add_plugin(<plugin>())`.
+Developer of plugin must give you instructions or docs of using his plugin. Dont use unsafe or undescovered plugins!  
+Now you can view how to create your own plugin, follow me:
+1. Create new `.py` file
+2. Add line `from MZscript import BasePlugin, MZClient`  
+We use MZClient to get code highlighting
+3. Create new class and inherit `BasePlugin` to your class, like `class MyPlugin(BasePlugin)`  
+Use `def __init__` to configure your plugin  
+`BasePlugin` class required to implement method `setup` where your plugin getting `MZClient` class. Save it to class `self.` var 
+
+Example of adding new function in the plugin class
+```py
+    async def func_myfunction(self, ctx, args):
+        print("Hello!")
+
+    # self.client declaration
+    def setup(self, client):
+        self.client: MZClient = client
+        self.client.funcs.add_function("$myfunction", self.func_myfunction)
 ```
-> It is worth saying that some events used by library by default. You can edit events in lib code if you want to control events by self
+Rules and guides how to write your own function explained in the [contribution page](/docs/CONTRIBUTING.md)
 ### Load commands (or "Cogs" / export module)
 If you dont want write all commands in one file, use `bot.load_command(path)` or `bot.load_commands(dir)`, this is example of loaded file:
 ```py
 from MZscript import MZClient
 # import and set client argument to MZClient is not nessecary
+
+# but gives you code highlighting
 def setup(client: MZClient):
     client.add_command(
     name="!command",

docs/website_plugin.py

@@ -0,0 +1,37 @@
+
+# this is example of plugin creating, maded by vanezus <3
+
+# Use quart - this async flask
+from quart import Quart, jsonify
+# need for types
+from src.MZscript import MZClient, BasePlugin
+
+
+class WebsitePlugin(BasePlugin): # name of plugin
+    def __init__(self):
+        self.app = Quart(__name__)
+
+        #route /
+        @self.app.route("/")
+        async def route_page():
+            return jsonify({"bot": self.bot_name}) # -> return bot display name
+
+    # simple add function
+    async def func_myfunction(self, ctx, args):
+        print("Hello!")
+
+    # self.client declaration
+    def setup(self, client):
+        self.client: MZClient = client
+        self.client.funcs.add_function("$myfunction", self.func_myfunction)
+
+    # there is async starting of server
+    # on bot ready
+    async def on_ready(self):
+        self.bot_name: str = self.client.bot.user.display_name
+        await self.app.run_task(host='127.0.0.1', port=5000, debug=False)
+
+# # example of add:
+# from .website import WebsitePlugin
+#
+# bot.add_plugin(WebsitePlugin())

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "MZscript"
-version = "1.0.2"
+version = "1.0.3"
 dependencies = [
   "disnake>=2.9.2"
 ]

requirements.txt

@@ -1,3 +1,2 @@
 disnake>=2.9.2
-MZscript @ git+https://github.com/MZshnik/MZscript@main
 twine>=5.1.0

src/MZscript/__init__.py

@@ -8,3 +8,4 @@
 
 from .database import Database
 from .main import MZClient
+from .base_plugin import BasePlugin

src/MZscript/base_plugin.py

@@ -0,0 +1,34 @@
+import disnake
+
+
+class BasePlugin:
+    """
+    ## Base class for creating MZscript plugins
+    ### This class discribes events what MZClient can call
+    ### Only 1 method is required - `setup`. If it ignored, raises NotImplementedError
+    """
+
+    def setup(self, client):
+        """
+        ## Setup plugin
+        ### Required to implement. If it ignored, raises NotImplementedError
+
+        ### Args:
+            client (`MZClient`): Instance of MZClient class. Contains all user and bot settings/information
+        """
+        raise NotImplementedError("Method \"setup\" of BasePlugin not implemented")
+
+    async def on_ready(self):
+        pass
+
+    async def on_message(self, message: disnake.Message):
+        pass
+
+    async def on_button_click(self, inter: disnake.MessageInteraction):
+        pass
+
+    async def on_interaction(self, inter: disnake.MessageInteraction):
+        pass
+
+    async def on_slash(self, inter: disnake.MessageInteraction):
+        pass

src/MZscript/functions_collector.py

@@ -18,6 +18,7 @@ def __init__(self, client, db_warns: bool, debug_log: bool, debug_console: bool)
         self.debug_log = debug_log
         self.debug_console = debug_console
         self.client = client
+        self.loaded_mods = []
         self.python_vars = {"uptime": datetime.now().timestamp()}
         self.database = Database()
         self.funcs = {}
@@ -28,7 +29,7 @@ def load_functions(self):
         ## Load functions from "Functions" directory
         """
         functions = []
-        tempmods = []
+        self.loaded_mods = []
         self.all_funcs = [i.lower() for i in self.all_funcs]
         # get all files of directory .Functions
         for i in os.walk(os.path.dirname(__file__)+"/Functions"):
@@ -40,7 +41,7 @@ def load_functions(self):
                     # and we get this class from setup function
                     exec(f"""
 tempmod = {j[:-3]}.setup(self)
-tempmods.append(tempmod)
+self.loaded_mods.append(tempmod)
 for k in inspect.getmembers(tempmod, inspect.ismethod):
     functions.append(k)""")
 
@@ -56,5 +57,20 @@ def load_functions(self):
             except NameError:
                 logging.warning(f"WARNING: For function \"{line}\" not exists command found.")
         self.sync_functions(self.funcs)
-        for i in tempmods:
+        for i in self.loaded_mods:
             i.sync_functions(self.funcs)
+
+    def add_function(self, func_name: str, func_method):
+        # TODO: Make chosing type of function (logic/no arg/can be no arg)
+        """
+        ## Adds new $function to handlering
+        
+        ### Args:
+            func_name (`str`): Name of function with $ in lowercase
+            func_method (`function`): Function method to execute
+        """
+        self.funcs[func_name] = func_method
+        self.all_funcs.append(func_name)
+        self.sync_functions(self.funcs)
+        for i in self.loaded_mods:
+            i.sync_functions(self.funcs)