pymud 0.20.0a2__py3-none-any.whl → 0.20.0a4__py3-none-any.whl

pymud/session.py

@@ -1,4 +1,4 @@
-import asyncio, logging, re, math, os, pickle, datetime, importlib, importlib.util, sysconfig
+import asyncio, logging, re, math, os, pickle, datetime, importlib, importlib.util, sysconfig, time
 from collections.abc import Iterable
 from collections import OrderedDict
 import logging, queue
@@ -8,7 +8,7 @@ from logging.handlers import QueueHandler, QueueListener
 from .logger import Logger
 from .extras import SessionBuffer, DotDict, Plugin
 from .protocol import MudClientProtocol
-from .objects import Trigger, Alias, Command, Timer, SimpleAlias, SimpleTrigger, SimpleTimer, GMCPTrigger, CodeBlock, CodeLine
+from .objects import BaseObject, Trigger, Alias, Command, Timer, SimpleAlias, SimpleTrigger, SimpleTimer, GMCPTrigger, CodeBlock, CodeLine
 from .settings import Settings
 
 
@@ -29,13 +29,14 @@ class Session:
 
     """
     #_esc_regx = re.compile("\x1b\\[[^mz]+[mz]")
-    _esc_regx = re.compile("\x1b\\[[\d;]+[abcdmz]", flags = re.IGNORECASE)
+    _esc_regx = re.compile(r"\x1b\[[\d;]+[abcdmz]", flags = re.IGNORECASE)
 
     _sys_commands = (
         "help",
         "exit",
         "close",
         "connect",      # 连接到服务器
+        "disconnect",   # 从服务器断开连接
 
         "info",         # 输出蓝色info
         "warning",      # 输出黄色warning
@@ -89,6 +90,7 @@ class Session:
         "var" : "variable",
         "rep" : "repeat",
         "con" : "connect",
+        "dis" : "disconnect",
         "wa"  : "wait",
         "mess": "message",
         "action": "trigger",
@@ -139,6 +141,8 @@ class Session:
         self._status_maker = None                           # 创建状态窗口的函数（属性）
         self.display_line  = ""
 
+        self._activetime = time.time()
+
         self.initialize()
 
         self._loggers = dict()
@@ -294,6 +298,15 @@ class Session:
 
         return dura
 
+    @property
+    def idletime(self) -> float:
+        "只读属性，返回当前会话空闲时间（即最后一次向服务器写入数据到现在的时间），以秒为单位。当服务器未连接时，返回-1"
+        idle = -1
+        if self._protocol and self._protocol.connected:
+            idle = time.time() - self._activetime
+
+        return idle
+
     @property
     def status_maker(self):
         """
@@ -770,6 +783,8 @@ class Session:
 
             cmd = line + self.newline
             self.write(cmd.encode(self.encoding, Settings.server["encoding_errors"]))
+
+        self._activetime = time.time()
     
     async def waitfor(self, line: str, awaitable, wait_time = 0.05) -> None:
         """
@@ -808,7 +823,7 @@ class Session:
         示例:
             .. code:: Python
 
-                session.addAlias(SimpleAlias(self.session, "^cb\s(\S+)\s(\S+)", "#3 get %1 from jinnang;#wa 250;combine gem;#wa 250;pack gem", id = "ali_combine"))
+                session.addAlias(SimpleAlias(self.session, r"^cb\s(\S+)\s(\S+)", "#3 get %1 from jinnang;#wa 250;combine gem;#wa 250;pack gem", id = "ali_combine"))
                 session.exec("cb j1a")
         """
         name = name or self.name
@@ -829,12 +844,10 @@ class Session:
         name = name or self.name
         if name in self.application.sessions.keys():
             session = self.application.sessions[name]
-            await session.exec_command_async(cmd, *args, **kwargs)
+            return await session.exec_command_async(cmd, *args, **kwargs)
         else:
             self.error(f"不存在名称为{name}的会话")
 
-    
-
     def exec_code(self, cl: CodeLine, *args, **kwargs):
         """
         执行解析为CodeLine形式的MUD命令（必定为单个命令）。一般情况下，脚本中不应调用该方法，而应使用exec/exec_command。
@@ -908,6 +921,7 @@ class Session:
         :param args: 保留兼容与扩展性所需
         :param kwargs: 保留兼容与扩展性所需
         """
+
         if cl.length == 0:
             self.writeline("")
 
@@ -935,9 +949,9 @@ class Session:
                 else:
                     try:
                         cb = CodeBlock(sess_cmd)
-                        await cb.async_execute(session, *args, **kwargs)
+                        return await cb.async_execute(session, *args, **kwargs)
                     except Exception as e:
-                        await session.exec_command_async(sess_cmd)
+                        return await session.exec_command_async(sess_cmd)
             
             else:
                 if cmd in self._commands_alias.keys():
@@ -954,7 +968,7 @@ class Session:
 
         else:
             cmdtext, code = cl.expand(self, *args, **kwargs)
-            await self.exec_text_async(cmdtext)
+            return await self.exec_text_async(cmdtext)
             
     def exec_text(self, cmdtext: str):
         """
@@ -994,14 +1008,14 @@ class Session:
 
         异步调用时，该函数要等待对应的代码执行完毕后才会返回。可以用于确保命令执行完毕。
         """
-
+        result = None
         isNotCmd = True
         for command in self._commands.values():
             if isinstance(command, Command) and command.enabled:
                 state = command.match(cmdtext)
                 if state.result == Command.SUCCESS:
                     # 命令的任务名称采用命令id，以便于后续查错
-                    await self.create_task(command.execute(cmdtext), name = "task-{0}".format(command.id))
+                    result = await self.create_task(command.execute(cmdtext), name = "task-{0}".format(command.id))
                     isNotCmd = False
                     break
 
@@ -1019,6 +1033,8 @@ class Session:
             if notAlias:
                 self.writeline(cmdtext)
 
+        return result
+
     def exec_command(self, line: str, *args, **kwargs) -> None:
         """
         在当前会话中执行MUD命令。多个命令可以用分隔符隔开。
@@ -1069,15 +1085,18 @@ class Session:
         """
 
         ## 以下为函数执行本体
+        result = None
         if (not "#" in line) and (not "@" in line) and (not "%" in line):
             cmds = line.split(self.seperator)
             for cmd in cmds:
-                await self.exec_text_async(cmd)
+                result = await self.exec_text_async(cmd)
                 if Settings.client["interval"] > 0:
                     await asyncio.sleep(Settings.client["interval"] / 1000.0)
         else:
             cb = CodeBlock(line)
-            await cb.async_execute(self)
+            result = await cb.async_execute(self)
+
+        return result
 
     def write_eof(self) -> None:
         """
@@ -1141,50 +1160,202 @@ class Session:
 
         return counts
 
-    def _addObjects(self, objs: dict, cls: type):
-        if cls == Alias:
-            self._aliases.update(objs)
-        elif cls == Command:
-            self._commands.update(objs)
-        elif cls == Trigger:
-            self._triggers.update(objs)
-        elif cls == Timer:
-            self._timers.update(objs)
-        elif cls == GMCPTrigger:
-            self._gmcp.update(objs)
-
-    def _addObject(self, obj, cls: type):
-        #if type(obj) == cls:
-        if isinstance(obj, cls):
-            if cls == Alias:
-                self._aliases[obj.id] = obj
-            elif cls == Command:
-                self._commands[obj.id] = obj
-            elif cls == Trigger:
-                self._triggers[obj.id] = obj
-            elif cls == Timer:
-                self._timers[obj.id] = obj
-            elif cls == GMCPTrigger:
-                self._gmcp[obj.id] = obj
+    # def _addObjects(self, objs: dict, cls: type):
+    #     if cls == Alias:
+    #         self._aliases.update(objs)
+    #     elif cls == Command:
+    #         self._commands.update(objs)
+    #     elif cls == Trigger:
+    #         self._triggers.update(objs)
+    #     elif cls == Timer:
+    #         self._timers.update(objs)
+    #     elif cls == GMCPTrigger:
+    #         self._gmcp.update(objs)
+
+    def _addObjects(self, objs):
+        if isinstance(objs, list) or isinstance(objs, tuple):
+            for item in objs:
+                self._addObject(item)
+
+        elif isinstance(objs, dict):
+            for key, item in objs.items():
+                if isinstance(item, BaseObject):
+                    if key != item.id:
+                        self.warning(f'对象 {item} 字典键值 {key} 与其id {item.id} 不一致，将丢弃键值，以其id添加到会话中...')
+
+                    self._addObject(item)
+
+    # def _addObject(self, obj, cls: type):
+    #     #if type(obj) == cls:
+    #     if isinstance(obj, cls):
+    #         if cls == Alias:
+    #             self._aliases[obj.id] = obj
+    #         elif cls == Command:
+    #             self._commands[obj.id] = obj
+    #         elif cls == Trigger:
+    #             self._triggers[obj.id] = obj
+    #         elif cls == Timer:
+    #             self._timers[obj.id] = obj
+    #         elif cls == GMCPTrigger:
+    #             self._gmcp[obj.id] = obj
+
+    def _addObject(self, obj):
+        if isinstance(obj, Alias):
+            self._aliases[obj.id] = obj
+        elif isinstance(obj, Command):
+            self._commands[obj.id] = obj
+        elif isinstance(obj, Trigger):
+            self._triggers[obj.id] = obj
+        elif isinstance(obj, Timer):
+            self._timers[obj.id] = obj
+        elif isinstance(obj, GMCPTrigger):
+            self._gmcp[obj.id] = obj
+
+    def addObject(self, obj: BaseObject):
+        """
+        向会话中增加单个对象，可直接添加 Alias, Trigger, GMCPTrigger, Command, Timer 或它们的子类
+
+        :param obj: 特定对象本身，可以为 Alias, Trigger, GMCPTrigger, Command, Timer 或其子类
+
+        示例:
+            .. code:: Python
+
+                class Configuration:
+                    def __init__(self, session):
+                        self.session = session
+                    
+                        self.session.addObject(SimpleAlias(session, r'^gta$', 'get all'),)
+                        self.session.addObject(SimpleTrigger(session, r'^[> ]*你嘻嘻地笑了起来.+', 'haha'))
+                        self.session.addObject(SimpleTimer(session, 'xixi', timeout = 10))
+
+        """
+        self._addObject(obj)
+
+    def addObjects(self, objs):
+        """
+        向会话中增加多个对象，可直接添加 Alias, Trigger, GMCPTrigger, Command, Timer 或它们的子类的元组、列表或者字典(保持兼容性)
+
+        :param objs: 多个特定对象组成的元组、列表或者字典，可以为 Alias, Trigger, GMCPTrigger, Command, Timer 或其子类
+
+        示例:
+            .. code:: Python
+
+                class Configuration:
+                    def __init__(self, session):
+                        self.session = session
+                    
+                        self.objs = [
+                            SimpleAlias(session, r'^gta$', 'get all;xixi'),
+                            SimpleTrigger(session, r'^[> ]*你嘻嘻地笑了起来.+', 'haha'),
+                            SimpleTimer(session, 'xixi', timeout = 10)
+                        ]
+
+                        self.session.addObjects(self.objs)
+
+        """
+        self._addObjects(objs)
 
     def _delObject(self, id, cls: type):
         if cls == Alias:
             self._aliases.pop(id, None)
         elif cls == Command:
-            self._commands.pop(id, None)
+            cmd = self._commands.pop(id, None)
+            if isinstance(cmd, Command):
+                cmd.reset()
+                cmd.unload()
+                cmd.__unload__()
+
         elif cls == Trigger:
             self._triggers.pop(id, None)
         elif cls == Timer:
-            self._timers.pop(id, None)
+            timer = self._timers.pop(id, None)
+            if isinstance(timer, Timer):
+                timer.enabled = False
         elif cls == GMCPTrigger:
             self._gmcp.pop(id, None)
 
+
     def _delObjects(self, ids: Iterable, cls: type):
         "删除多个指定元素"
         for id in ids:
             self._delObject(id, cls)
 
-    def addAliases(self, alis: dict):
+    def delObject(self, obj):
+        """
+        从会话中移除一个对象，可直接删除 Alias, Trigger, GMCPTrigger, Command, Timer 或它们的子类本身
+        
+        :param obj: 要删除的多个特定对象组成的元组、列表或者字典，可以为 Alias, Trigger, GMCPTrigger, Command, Timer 或其子类
+
+        示例:
+            .. code:: Python
+
+                class Configuration:
+                    def __init__(self, session):
+                        self.session = session
+
+                        ali = SimpleAlias(session, r'^gta$', 'get all', id = 'my_ali1')
+                        
+                        # 以下几种方式均可将该别名添加到会话
+                        session.addObject(ali)
+                        session.addAlias(ali)
+
+                        # 以下三种方式均可以删除该别名
+                        session.delObject(ali)
+                        session.delAlias(ali)
+                        session.delAlias("my_ali1")
+
+        """
+        if isinstance(obj, Alias):
+            self._aliases.pop(obj.id, None)
+        elif isinstance(obj, Command):
+            obj.reset()
+            obj.unload()
+            obj.__unload__()
+            self._commands.pop(obj.id, None)
+        elif isinstance(obj, Trigger):
+            self._triggers.pop(obj.id, None)
+        elif isinstance(obj, Timer):
+            obj.enabled = False
+            self._timers.pop(obj.id, None)
+        elif isinstance(obj, GMCPTrigger):
+            self._gmcp.pop(obj.id, None)
+
+    def delObjects(self, objs):
+        """
+        从会话中移除一组对象，可直接删除多个 Alias, Trigger, GMCPTrigger, Command, Timer
+        
+        :param objs: 要删除的一组对象的元组、列表或者字典(保持兼容性)，其中对象可以为 Alias, Trigger, GMCPTrigger, Command, Timer 或它们的子类
+
+        示例:
+
+        .. code:: Python
+
+            class Configuration:
+                def __init__(self, session):
+                    self.session = session
+                
+                    self.objs = [
+                        SimpleAlias(session, r'^gta$', 'get all;xixi'),
+                        SimpleTrigger(session, r'^[> ]*你嘻嘻地笑了起来.+', 'haha'),
+                        SimpleTimer(session, 'xixi', timeout = 10)
+                    ]
+
+                    self.session.addObjects(self.objs)
+
+                def __unload__(self):
+                    "卸载本模块时，删除所有本模块添加的对象"
+                    self.session.delObjects(self.objs)
+
+        """
+        if isinstance(objs, list) or isinstance(objs, tuple):
+            for item in objs:
+                self.delObject(item)
+
+        elif isinstance(objs, dict):
+            for key, item in objs.items():
+                self.delObject(item)
+
+    def addAliases(self, alis):
         """
         向会话中增加多个别名
 
@@ -1205,55 +1376,55 @@ class Session:
                         self._aliases['my_ali2'] = SimpleAlias(self.session, "s", "south", id = "my_ali2")
                         self.session.addAliases(self._aliases)
         """
-        self._addObjects(alis, Alias)
+        self._addObjects(alis)
 
-    def addCommands(self, cmds: dict):
+    def addCommands(self, cmds):
         """
         向会话中增加多个命令。使用方法与 addAliases 类似。
 
         :param cmds: 多个命令的字典。字典 key 应为每个命令的 id。
         """
-        self._addObjects(cmds, Command)
+        self._addObjects(cmds)
 
-    def addTriggers(self, tris: dict):
+    def addTriggers(self, tris):
         """
         向会话中增加多个触发器。使用方法与 addAliases 类似。
 
         :param tris: 多个触发器的字典。字典 key 应为每个触发器的 id。
         """
-        self._addObjects(tris, Trigger)
+        self._addObjects(tris)
 
-    def addGMCPs(self, gmcps: dict):
+    def addGMCPs(self, gmcps):
         """
         向会话中增加多个GMCPTrigger。使用方法与 addAliases 类似。
 
         :param gmcps: 多个GMCPTrigger的字典。字典 key 应为每个GMCPTrigger的 id。
         """
-        self._addObjects(gmcps, GMCPTrigger)
+        self._addObjects(gmcps)
 
-    def addTimers(self, tis: dict):
+    def addTimers(self, tis):
         """
         向会话中增加多个定时器。使用方法与 addAliases 类似。
 
         :param tis: 多个定时器的字典。字典 key 应为每个定时器的 id。
         """
-        self._addObjects(tis, Timer)
+        self._addObjects(tis)
 
-    def addAlias(self, ali: Alias):
+    def addAlias(self, ali):
         """
         向会话中增加一个别名。
 
         :param ali: 要增加的别名对象，应为 Alias 类型或其子类
         """
-        self._addObject(ali, Alias)
+        self._addObject(ali)
 
-    def addCommand(self, cmd: Command):
+    def addCommand(self, cmd):
         """
         向会话中增加一个命令。
 
         :param cmd: 要增加的命令对象，应为 Command 类型或其子类
         """
-        self._addObject(cmd, Command)
+        self._addObject(cmd)
 
     def addTrigger(self, tri: Trigger):
         """
@@ -1261,7 +1432,7 @@ class Session:
 
         :param tri: 要增加的触发器对象，应为 Trigger 类型或其子类
         """
-        self._addObject(tri, Trigger)
+        self._addObject(tri)
 
     def addTimer(self, ti: Timer):
         """
@@ -1269,7 +1440,7 @@ class Session:
 
         :param ti: 要增加的定时器对象，应为 Timer 类型或其子类
         """
-        self._addObject(ti, Timer)
+        self._addObject(ti)
 
     def addGMCP(self, gmcp: GMCPTrigger):
         """
@@ -1278,7 +1449,7 @@ class Session:
         :param gmcp: 要增加的GMCP触发器对象，应为 GMCPTrigger 类型或其子类
         """
 
-        self._addObject(gmcp, GMCPTrigger)
+        self._addObject(gmcp)
 
     def delAlias(self, ali):
         """
@@ -1397,7 +1568,7 @@ class Session:
         for ti in ti_s:
             self.delTimer(ti)
 
-    def delGMCP(self, gmcp: GMCPTrigger):
+    def delGMCP(self, gmcp):
         """
         从会话中移除一个GMCP触发器，可接受 GMCPTrigger 对象或其的id。使用方法与 delAlias 类似
         
@@ -1713,6 +1884,7 @@ class Session:
         该函数不应该在代码中直接调用。
         
         相关命令:
+            - #disconnect
             - #close
             - #exit
         '''
@@ -1734,6 +1906,18 @@ class Session:
 
             self.info("已经与服务器连接了 {}".format(time_msg))
 
+    def handle_disconnect(self, code: CodeLine = None, *args, **kwargs):
+        '''
+        嵌入命令 #disconnect / #dis 的执行函数，断开到远程服务器的连接（仅当远程服务器已连接时有效）。
+        该函数不应该在代码中直接调用。
+        
+        相关命令:
+            - #connect
+            - #close
+        '''
+
+        self.disconnect()
+
     def handle_variable(self, code: CodeLine = None, *args, **kwargs):
         '''
         嵌入命令 #variable / #var 的执行函数，操作会话变量。
@@ -1967,7 +2151,7 @@ class Session:
                             self.info("创建Timer {} 成功: {}".format(ti.id, ti.__repr__()))
 
     def handle_alias(self, code: CodeLine = None, *args, **kwargs):
-        '''
+        """
         嵌入命令 #alias / #ali 的执行函数，操作别名。该命令可以不带参数、带一个参数或者两个参数。
         该函数不应该在代码中直接调用。
 
@@ -1998,7 +2182,7 @@ class Session:
             - #trigger
             - #timer
             - #command
-        '''
+        """
 
         self._handle_objs("Alias", self._aliases, *code.code[2:])
 
@@ -2393,10 +2577,11 @@ class Session:
                 mod = self._modules[module_name]["module"]
                 config = self._modules[module_name]["config"]
                 if config: 
-                    if hasattr(config, "unload"):
-                        unload = getattr(config, "unload", None)
+                    if hasattr(config, "__unload__") or hasattr(config, "unload"):
+                        unload = getattr(config, "__unload__", None) or getattr(config, "unload", None)
                         if callable(unload):
-                            unload(config)
+                            unload()
+
                     del config
                 mod = importlib.reload(mod)
                 if hasattr(mod, 'Configuration'):
@@ -2431,15 +2616,15 @@ class Session:
             self._unload_module(mod)
 
     def _unload_module(self, module_name):
-        "卸载指定名称模块。卸载支持需要模块的Configuration实现__del__方法"
+        "卸载指定名称模块。卸载支持需要模块的Configuration实现 __unload__ 或 unload 方法"
         if module_name in self._modules.keys():
             mod = self._modules[module_name]["module"]
             config = self._modules[module_name]["config"]
             if config: 
-                if hasattr(config, "unload"):
-                    unload = getattr(config, "unload", None)
+                if hasattr(config, "__unload__") or hasattr(config, "unload"):
+                    unload = getattr(config, "__unload__", None) or getattr(config, "unload", None)
                     if callable(unload):
-                        unload(config)
+                        unload()
 
                 del config
             del mod

pymud/settings.py

@@ -11,7 +11,7 @@ class Settings:
     "APP 名称, 默认PYMUD"
     __appdesc__   = "a MUD client written in Python"
     "APP 简要描述"
-    __version__   = "0.20.0a2"
+    __version__   = "0.20.0"
     "APP 当前版本"
     __release__   = "2024-08-19"
     "APP 当前版本发布日期"