sshscript 3.1.4__py3-none-any.whl → 4.0.1__py3-none-any.whl

_sshscript_cli.py

@@ -0,0 +1,19 @@
+"""Minimal console bootstrap; must remain parseable on older Python."""
+import sys
+
+
+def main():
+    # Importing a package submodule executes __init__ first, so this check
+    # must be independent of the package's runtime guard.
+    if sys.version_info < (3, 11):
+        raise SystemExit(
+            "SSHScript requires Python 3.11 or newer.\n"
+            "Detected Python %s at %s."
+            % ('.'.join(map(str, sys.version_info[:3])), sys.executable)
+        )
+    from sshscript.sshscript import main as run
+    return run()
+
+
+if __name__ == '__main__':
+    main()

sshscript/__init__.py

@@ -26,15 +26,22 @@ Example::
     from sshscript import Session
 
     with Session() as local:
-        stdout, stderr = local("hostname")
+        stdout, stderr, exitcode = local("hostname")
         with local.connect("user@host") as remote:
-            stdout, stderr = remote("uname -s")
+            stdout, stderr, exitcode = remote("uname -s")
             print(stdout.strip())
 
 Use run_file(path) for a script file, run_script(source) for source text,
 and spy_imports() to temporarily enable Python imports of .spy modules.
 """
 
+if __package__:
+    from ._runtime import require_python as _require_python
+else:
+    from _runtime import require_python as _require_python
+
+_require_python()
+
 if __package__:
     from ._version import __version__
     from . import sshscript
@@ -49,8 +56,13 @@ else:
     from spyimporter import spy_imports
 
 run_file = sshscript.run_file
+check_file = sshscript.check_file
 run_script = sshscript.run_script
 Session = session.Session
+CommandResult = session.CommandResult
+CommandJob = session.CommandJob
+CommandTimeoutError = session.CommandTimeoutError
+JobResult = session.JobResult
 
 set_logger = errorutils.set_logger
 get_logger = errorutils.get_logger
@@ -73,8 +85,13 @@ SSHScriptException = errorutils.SSHScriptException
 
 __all__ = [
     'run_file',
+    'check_file',
     'run_script',
     'Session',
+    'CommandResult',
+    'CommandJob',
+    'CommandTimeoutError',
+    'JobResult',
     'get_logger',
     'set_logger',
     'spy_imports',

sshscript/__init__.pyi

@@ -0,0 +1,15 @@
+from typing import Any, ContextManager
+from os import PathLike
+from .session import Session as Session
+from .commandresult import CommandResult as CommandResult
+from .commandjob import CommandJob as CommandJob, JobResult as JobResult, CommandTimeoutError as CommandTimeoutError
+from .errorutils import SSHScriptException as SSHScriptException
+
+__version__: str
+
+def check_file(script_path: str | PathLike[str]) -> int: ...
+def run_file(script_path: str | PathLike[str], vars: dict[str, Any] | None = ..., showScript: bool = ...) -> int: ...
+def run_script(script: str, varGlobals: dict[str, Any] | None = ..., showScript: bool = ...) -> dict[str, Any]: ...
+def spy_imports() -> ContextManager[None]: ...
+def get_logger() -> Any: ...
+def set_logger(userlogger: Any = ..., logname: str | None = ...) -> Any: ...

sshscript/_runtime.py

@@ -0,0 +1,14 @@
+"""Reject unsupported interpreters before importing SSHScript features."""
+import sys
+
+
+def require_python(cli=False):
+    if sys.version_info < (3, 11):
+        message = (
+            "SSHScript requires Python 3.11 or newer.\n"
+            "Detected Python %s at %s."
+            % ('.'.join(map(str, sys.version_info[:3])), sys.executable)
+        )
+        if cli:
+            raise SystemExit(message)
+        raise ImportError(message)

sshscript/_version.py

@@ -1,3 +1,3 @@
 """Single source of the SSHScript package version."""
 
-__version__ = "3.1.4"
+__version__ = "4.0.1"

sshscript/channelgeneric.py

@@ -18,6 +18,7 @@
 
 import threading, os, sys, re
 import time
+import uuid
 import logging
 import paramiko
 import asyncio
@@ -67,6 +68,7 @@ class GenericChannel(object):
         
         ## an instance of Dollar
         self.owner = owner
+        self.logger = getattr(owner, "logger", logger)
 
         ## see hijack() for details
         self.hijacked = False
@@ -80,12 +82,13 @@ class GenericChannel(object):
         ## 如果沒有，則送出一個dumyEcho
         #self._exitcode_session_id = 0
         #self._command_session_id = 0
-        if os.environ.get('VERBOSE'):
+        settings = getattr(owner, 'settings', {})
+        if settings.get('verbose', bool(os.environ.get('VERBOSE'))):
             ## verbose-related
             self.dump2sys = (1,1)
             self.stdoutPrefix = os.environ.get('VERBOSE_STDOUT_PREFIX','🟩').encode('utf8')
             self.stderrPrefix = os.environ.get('VERBOSE_STDERR_PREFIX','🟨').encode('utf8')
-        elif os.environ.get('VERBOSE_STDERR'):
+        elif settings.get('verbose_stderr', bool(os.environ.get('VERBOSE_STDERR'))):
             self.dump2sys = (0,1)
             self.stdoutPrefix = b''
             self.stderrPrefix = os.environ.get('VERBOSE_STDERR_PREFIX','🟨').encode('utf8')
@@ -141,6 +144,8 @@ class GenericChannel(object):
         self._send_call_lock = threading.Lock()
         self._async_send_lock = None
         self.send_timeout = 30
+        self._console_job = None
+        self._console_job_lock = threading.Lock()
         self.command_timeout = 60         
 
     @property
@@ -286,7 +291,7 @@ class GenericChannel(object):
         basetime = self.lastIOAtTime[:]
         timeouttime = (time.time() + timeout) if timeout else 0
         ret = True
-        logger.debug(
+        self.logger.debug(
             '%s Waiting for channel output (timeout=%s, silent=%s)',
             self.prefixOfLog,
             timeout or None,
@@ -314,7 +319,7 @@ class GenericChannel(object):
                 else:
                     raise TimeoutError(f'wait_for_output exceeded {timeout}')
 
-        logger.debug(
+        self.logger.debug(
             '%s Channel output wait completed (received=%s)',
             self.prefixOfLog,
             ret,
@@ -395,7 +400,7 @@ class GenericChannel(object):
         """Return the recorded status, fetching it if needed; -1 while interactive."""
         if self.hijacked:
             #raise ValueError('exitcode is not available in current state')
-            logger.warning(
+            self.logger.warning(
                 '%s Exit status is unavailable while the channel is in interactive mode',
                 self.prefixOfLog,
             )
@@ -410,7 +415,7 @@ class GenericChannel(object):
         """Log with channel context, preserving format arguments and logging keywords."""
         if isinstance(level, int) and 0 < level < logging.DEBUG:
             level = logging.DEBUG
-        logger.log(level, f'{self.prefixOfLog} {msg}', *args, **kwargs)
+        getattr(self, 'logger', logger).log(level, f'{self.prefixOfLog} {msg}', *args, **kwargs)
 
     def expect(
         self,
@@ -1401,7 +1406,7 @@ class GenericChannel(object):
         
         :text: Text to send as input
         """
-        logger.debug(
+        self.logger.debug(
             '%s Sending channel input (length=%d, interactive=%s)',
             self.prefixOfLog,
             len(text),
@@ -1482,6 +1487,11 @@ class GenericChannel(object):
                 )
 
     def input(self, text, timeout=60):
+        """Append one newline and wait for interactive readiness, exit, or silence.
+
+        Existing newlines are retained. Use send() to write exact text instead.
+        A readiness/silence status does not establish command success.
+        """
         if not isinstance(text, str):
             raise TypeError('input text must be str')
 
@@ -1724,6 +1734,8 @@ class GenericChannel(object):
         stdout = None
         stderr = None
         completed = threading.Event()
+        stderr_completed = threading.Event()
+        stderr_marker = None
 
         try:
             self._exitcode = EXITCODE_DEFAULT
@@ -1754,9 +1766,16 @@ class GenericChannel(object):
                     '-@_@-',
                 )
 
+                # Separate pipe readers can observe stdout completion before
+                # earlier stderr has been drained. Fence both streams before
+                # returning a completed command's buffers to the public wrapper.
+                trailer = 'echo _TT$?_-@_@-'
+                if not self.owner.get_pty:
+                    stderr_marker = '-@stderr-' + uuid.uuid4().hex + '\n'
+                    stderr.set_callback(stderr_completed.set, stderr_marker)
+                    trailer += "; printf '%s\\n' " + repr(stderr_marker.rstrip('\n')) + ' >&2'
                 self.send(
-                    f'{{ {command}; }} ; '
-                    'echo _TT$?_-@_@-\n',
+                    f'{{ {command}; }} ; ' + trailer + '\n',
                     timeout=self._remaining(deadline),
                 )
 
@@ -1794,9 +1813,12 @@ class GenericChannel(object):
                 'command completion',
             )
 
+            if stderr_marker is not None:
+                self._wait_event(stderr_completed, deadline, 'stderr completion')
+
             if not self.prompt:
                 match = re.compile(
-                    r'_TT(\d+)_'
+                    r'_TT(\d+)_\r?\n?$'
                 ).search(str(stdout))
 
                 if match is None:
@@ -1826,7 +1848,7 @@ class GenericChannel(object):
 
         :return: Tuple of (stdout, stderr)
         """
-        logger.debug(
+        self.logger.debug(
             '%s Dispatching command (interactive=%s, expectations=%d) %s',
             self.prefixOfLog,
             bool(self.prompt),
@@ -1874,7 +1896,7 @@ class GenericChannel(object):
                 if m:
                     self._exitcode = int(m.group(1))
                 else:
-                    logger.warning(
+                    self.logger.warning(
                         '%s Unable to parse command exit status',
                         self.prefixOfLog,
                     )
@@ -1891,7 +1913,7 @@ class GenericChannel(object):
             ## so that when next line is getting $.exitcode, it would get the corrent exitcode
             ## not the exitcode of our modified command.
             while self.executing_lock.locked(): time.sleep(0.01)
-        logger.debug(
+        self.logger.debug(
             '%s Command completed (interactive=%s, exit_status=%s)',
             self.prefixOfLog,
             bool(self.prompt),
@@ -1921,7 +1943,7 @@ class GenericChannel(object):
             if self.closed: return
             self.touchIO(True)
             try:
-                self._stdout.append(newbytes.decode('utf8'),True)
+                self._stdout.append(self._console_job._decoders[0].decode(newbytes) if self._console_job is not None else newbytes.decode('utf8'),True)
             except UnicodeDecodeError:
                 self._stdout.append(newbytes.decode('utf8','replace'),True)
         if self.dump2sys[0]:
@@ -1938,7 +1960,7 @@ class GenericChannel(object):
             if self.closed: return
             self.touchIO(True)
             try:
-                self._stderr.append(newbytes.decode('utf8'),True)
+                self._stderr.append(self._console_job._decoders[1].decode(newbytes) if self._console_job is not None else newbytes.decode('utf8'),True)
             except UnicodeDecodeError:
                 self._stderr.append(newbytes.decode('utf8','replace'),True)
         if self.dump2sys[1]:
@@ -2000,13 +2022,23 @@ class GenericChannel(object):
                             await handler[x](newbytes)
                         self._dumpBuf.clear()
             except Exception:
-                logger.exception('%s Channel output forwarding failed', self.prefixOfLog)
+                self.logger.exception('%s Channel output forwarding failed', self.prefixOfLog)
                 raise
     async def _dump_stdout_err(self):
         handler = [self._dump_stdout,self._dump_stderr]
         for x,newbytes in self._dumpBuf:
             await handler[x](newbytes)
         self._dumpBuf.clear()
+        # One-shot completion must also forward a final unterminated line.
+        for name, stream, prefix in (
+            ('_stdoutDumpBuf', sys.stdout, self.stdoutPrefix),
+            ('_stderrDumpBuf', sys.stderr, self.stderrPrefix),
+        ):
+            pending = getattr(self, name)
+            if pending:
+                stream.buffer.write(prefix + self._native_id.encode() + b':' + pending)
+                stream.buffer.flush()
+                setattr(self, name, b'')
     
     def reset_buffer(self,reason=None):
         """Replace the current stdout/stderr pair; return (new_pair, previous_pair)."""

sshscript/channelssh.py

@@ -36,7 +36,8 @@ class ParamikoChannel(object):
     def __init__(self,sshchannel,get_pty,channel=None):
         if not isinstance(sshchannel, SSHChannel):
             raise TypeError('sshchannel must be SSHChannel')
-        self.sshchannel = sshchannel 
+        self.sshchannel = sshchannel
+        self.logger = sshchannel.logger
         self.get_pty = get_pty
         self.suspending = False
         if channel is None:
@@ -78,7 +79,7 @@ class ParamikoChannel(object):
         
         ## two-dollars has no self.command
         if self.sshchannel.owner.command:
-            logger.debug(
+            self.logger.debug(
                 '[SSHChannel] Executing remote command (host=%s, pty=%s)',
                 self.sshchannel.owner.session.host,
                 self.get_pty,
@@ -118,7 +119,7 @@ class ParamikoChannel(object):
                         except (SSHException,ValueError):
                             if self.channel.closed or self.channel.exit_status_ready():
                                 break
-                            logger.exception(
+                            self.logger.exception(
                                 '[SSHChannel] SSH channel read failed (host=%s)',
                                 self.sshchannel.owner.session.host,
                             )
@@ -126,7 +127,7 @@ class ParamikoChannel(object):
                     await asyncio.sleep(0.1)
             except OSError as e:
                 if e.errno != errno.EIO and not self.channel.closed:
-                    logger.exception(
+                    self.logger.exception(
                         '[SSHChannel] SSH channel reader failed (host=%s)',
                         self.sshchannel.owner.session.host,
                     )
@@ -166,7 +167,7 @@ class ParamikoChannel(object):
         command result is kept separately from the SSH channel exit status.
         """
         host = self.sshchannel.owner.session.host
-        logger.debug('[SSHChannel] Closing SSH channel (host=%s)', host)
+        self.logger.debug('[SSHChannel] Closing SSH channel (host=%s)', host)
         ## automatically send exit to shell
         try:
             if not self.channel.exit_status_ready():
@@ -176,7 +177,7 @@ class ParamikoChannel(object):
             deadline = time.monotonic() + timeout_seconds
             while True:
                 if time.monotonic() > deadline:
-                    logger.warning(
+                    self.logger.warning(
                         '[SSHChannel] Exit status was not received before close timeout; '
                         'forcing channel close (host=%s, timeout=%ss)',
                         host,
@@ -191,7 +192,7 @@ class ParamikoChannel(object):
                 else:
                     time.sleep(0.1)
         except (SSHException, OSError):
-            logger.exception('[SSHChannel] Failed to close SSH channel (host=%s)', host)
+            self.logger.exception('[SSHChannel] Failed to close SSH channel (host=%s)', host)
             raise
         finally:
             self.channel.close()

sshscript/channelsubprocess.py

@@ -189,7 +189,7 @@ class POpenChannel(GenericChannel):
                         for key, mask in events:
                             # key.fileobj 是原始的 pipe 物件
                             # key.data 是我們剛才註冊的自定義字串
-                            await callback[key.fileobj](os.read(key.fileobj,1024))
+                            await callback[key.fileobj](os.read(key.fileobj, 65536 if self._console_job is not None else 1024))
                         await asyncio.sleep(interval)
                 except OSError as e:
                     ## when subprocess exited, the file descriptor would be closed, and os.read() would raise OSError with errno.EIO 
@@ -200,7 +200,7 @@ class POpenChannel(GenericChannel):
                     sel.close()
         POpenChannel.count += 1
         await _reading()
-        logger.debug(
+        self.logger.debug(
             '[POpen] Subprocess reader stopped (pid=%s, returncode=%s)',
             self.cp.pid,
             self.cp.poll(),
@@ -248,7 +248,7 @@ class POpenChannel(GenericChannel):
                 pid = self.cp.pid
                 if self.cp.poll() is None:
                     timeout = 2
-                    logger.debug(
+                    self.logger.debug(
                         '[POpen] Waiting for subprocess to exit (pid=%s, timeout=%ss)',
                         pid,
                         timeout,
@@ -256,7 +256,7 @@ class POpenChannel(GenericChannel):
                     try:
                         self.cp.wait(timeout)
                     except subprocess.TimeoutExpired:
-                        logger.warning(
+                        self.logger.warning(
                             '[POpen] Subprocess did not exit before close timeout; '
                             'terminating (pid=%s, timeout=%ss)',
                             pid,
@@ -266,7 +266,7 @@ class POpenChannel(GenericChannel):
                         try:
                             self.cp.wait(timeout)
                         except subprocess.TimeoutExpired:
-                            logger.warning(
+                            self.logger.warning(
                                 '[POpen] Subprocess did not terminate before timeout; '
                                 'killing (pid=%s, timeout=%ss)',
                                 pid,
@@ -284,7 +284,7 @@ class POpenChannel(GenericChannel):
                     else:
                         fd.close()
 
-                logger.debug(
+                self.logger.debug(
                     '[POpen] Subprocess channel closed (pid=%s, returncode=%s)',
                     pid,
                     self.cp.poll(),