ptymini 0.0.1__tar.gz

ptymini-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2022, fastai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ptymini-0.0.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include pyproject.toml
+include LICENSE
+include CONTRIBUTING.md
+include README.md
+recursive-exclude * __pycache__

ptymini-0.0.1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: ptymini
+Version: 0.0.1
+Summary: Asyncio pty sessions: spawn, write, multi-client attach with replay, and a named registry
+Author-email: Jeremy Howard <github@jhoward.fastmail.fm>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/AnswerDotAI/ptymini
+Project-URL: Documentation, https://AnswerDotAI.github.io/ptymini/
+Keywords: nbdev
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastcore>=2.1.18
+Requires-Dist: ptyprocess>=0.7
+Dynamic: license-file
+
+# ptymini
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`ptymini` fills the gap between `ptyprocess` (a raw pty fd), `pexpect` (sync expect loops), and `terminado` (a pty server welded to tornado): asyncio-native pty *sessions*. A [`PtySession`](https://AnswerDotAI.github.io/ptymini/core.html#ptysession) is one spawned pty that any number of clients can attach to as independent byte streams, each primed from a byte-bounded replay buffer — so a reconnecting client resumes with recent scrollback instead of a blank screen. A [`PtyRegistry`](https://AnswerDotAI.github.io/ptymini/core.html#ptyregistry) adds named get-or-create sessions, injected shell setup (`rc`), and inactivity culling. It carries no server, no framework, and no session persistence beyond the process: web exposure belongs to the embedding app (e.g. [jupygate](https://github.com/AnswerDotAI/jupygate)), and durable session management belongs to tmux.
+
+## Usage
+
+### Installation
+
+Install latest from the GitHub [repository](https://github.com/AnswerDotAI/ptymini):
+
+``` sh
+$ pip install git+https://github.com/AnswerDotAI/ptymini.git
+```
+
+or from [conda](https://anaconda.org/AnswerDotAI/ptymini)
+
+``` sh
+$ conda install -c AnswerDotAI ptymini
+```
+
+or from [pypi](https://pypi.org/project/ptymini/)
+
+``` sh
+$ pip install ptymini
+```
+
+### Documentation
+
+Documentation can be found hosted on this GitHub [repository](https://github.com/AnswerDotAI/ptymini)’s [pages](https://AnswerDotAI.github.io/ptymini/). Additionally you can find package manager specific guidelines on [conda](https://anaconda.org/AnswerDotAI/ptymini) and [pypi](https://pypi.org/project/ptymini/) respectively.

ptymini-0.0.1/README.md

@@ -0,0 +1,32 @@
+# ptymini
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`ptymini` fills the gap between `ptyprocess` (a raw pty fd), `pexpect` (sync expect loops), and `terminado` (a pty server welded to tornado): asyncio-native pty *sessions*. A [`PtySession`](https://AnswerDotAI.github.io/ptymini/core.html#ptysession) is one spawned pty that any number of clients can attach to as independent byte streams, each primed from a byte-bounded replay buffer — so a reconnecting client resumes with recent scrollback instead of a blank screen. A [`PtyRegistry`](https://AnswerDotAI.github.io/ptymini/core.html#ptyregistry) adds named get-or-create sessions, injected shell setup (`rc`), and inactivity culling. It carries no server, no framework, and no session persistence beyond the process: web exposure belongs to the embedding app (e.g. [jupygate](https://github.com/AnswerDotAI/jupygate)), and durable session management belongs to tmux.
+
+## Usage
+
+### Installation
+
+Install latest from the GitHub [repository](https://github.com/AnswerDotAI/ptymini):
+
+``` sh
+$ pip install git+https://github.com/AnswerDotAI/ptymini.git
+```
+
+or from [conda](https://anaconda.org/AnswerDotAI/ptymini)
+
+``` sh
+$ conda install -c AnswerDotAI ptymini
+```
+
+or from [pypi](https://pypi.org/project/ptymini/)
+
+``` sh
+$ pip install ptymini
+```
+
+### Documentation
+
+Documentation can be found hosted on this GitHub [repository](https://github.com/AnswerDotAI/ptymini)’s [pages](https://AnswerDotAI.github.io/ptymini/). Additionally you can find package manager specific guidelines on [conda](https://anaconda.org/AnswerDotAI/ptymini) and [pypi](https://pypi.org/project/ptymini/) respectively.

ptymini-0.0.1/ptymini/__init__.py

@@ -0,0 +1,8 @@
+"""Asyncio pty sessions: spawn, write, multi-client attach with replay, and a named registry
+
+Modules:
+
+- `ptymini.bg`: The bgterm API: sync, cursor-paged background terminal sessions
+- `ptymini.core`: `PtySession` and `PtyRegistry`: asyncio pty sessions over one offset-tracked output ring"""
+
+__version__ = "0.0.1"

ptymini-0.0.1/ptymini/_modidx.py

@@ -0,0 +1,88 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/ptymini',
+                'doc_host': 'https://AnswerDotAI.github.io',
+                'git_url': 'https://github.com/AnswerDotAI/ptymini',
+                'lib_path': 'ptymini'},
+  'syms': { 'ptymini.bg': { 'ptymini.bg.BgtermError': ('bg.html#bgtermerror', 'ptymini/bg.py'),
+                            'ptymini.bg.PollResult': ('bg.html#pollresult', 'ptymini/bg.py'),
+                            'ptymini.bg.PollResult.truncated': ('bg.html#pollresult.truncated', 'ptymini/bg.py'),
+                            'ptymini.bg.Session': ('bg.html#session', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.__enter__': ('bg.html#session.__enter__', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.__exit__': ('bg.html#session.__exit__', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.__init__': ('bg.html#session.__init__', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.close': ('bg.html#session.close', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.exit_code': ('bg.html#session.exit_code', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.kill': ('bg.html#session.kill', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.open': ('bg.html#session.open', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.poll': ('bg.html#session.poll', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.read': ('bg.html#session.read', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.running': ('bg.html#session.running', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.send': ('bg.html#session.send', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.start': ('bg.html#session.start', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.terminate': ('bg.html#session.terminate', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.wait': ('bg.html#session.wait', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.write': ('bg.html#session.write', 'ptymini/bg.py'),
+                            'ptymini.bg.Session.write_stdin': ('bg.html#session.write_stdin', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession': ('bg.html#_bgsession', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.__init__': ('bg.html#_bgsession.__init__', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession._read': ('bg.html#_bgsession._read', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.close': ('bg.html#_bgsession.close', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.exit_code': ('bg.html#_bgsession.exit_code', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.kill': ('bg.html#_bgsession.kill', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.poll': ('bg.html#_bgsession.poll', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.read': ('bg.html#_bgsession.read', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.running': ('bg.html#_bgsession.running', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.start': ('bg.html#_bgsession.start', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.terminate': ('bg.html#_bgsession.terminate', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.wait': ('bg.html#_bgsession.wait', 'ptymini/bg.py'),
+                            'ptymini.bg._BgSession.write_stdin': ('bg.html#_bgsession.write_stdin', 'ptymini/bg.py'),
+                            'ptymini.bg._call': ('bg.html#_call', 'ptymini/bg.py'),
+                            'ptymini.bg._ensure_loop': ('bg.html#_ensure_loop', 'ptymini/bg.py'),
+                            'ptymini.bg._lookup': ('bg.html#_lookup', 'ptymini/bg.py'),
+                            'ptymini.bg.close_bgterm': ('bg.html#close_bgterm', 'ptymini/bg.py'),
+                            'ptymini.bg.kill': ('bg.html#kill', 'ptymini/bg.py'),
+                            'ptymini.bg.list_sessions': ('bg.html#list_sessions', 'ptymini/bg.py'),
+                            'ptymini.bg.poll': ('bg.html#poll', 'ptymini/bg.py'),
+                            'ptymini.bg.read': ('bg.html#read', 'ptymini/bg.py'),
+                            'ptymini.bg.start_bgterm': ('bg.html#start_bgterm', 'ptymini/bg.py'),
+                            'ptymini.bg.terminate': ('bg.html#terminate', 'ptymini/bg.py'),
+                            'ptymini.bg.wait': ('bg.html#wait', 'ptymini/bg.py'),
+                            'ptymini.bg.write_stdin': ('bg.html#write_stdin', 'ptymini/bg.py')},
+            'ptymini.core': { 'ptymini.core.Gap': ('core.html#gap', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry': ('core.html#ptyregistry', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.__aenter__': ('core.html#ptyregistry.__aenter__', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.__aexit__': ('core.html#ptyregistry.__aexit__', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.__init__': ('core.html#ptyregistry.__init__', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.__len__': ('core.html#ptyregistry.__len__', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry._next_name': ('core.html#ptyregistry._next_name', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.create': ('core.html#ptyregistry.create', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.cull': ('core.html#ptyregistry.cull', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.cull_ready': ('core.html#ptyregistry.cull_ready', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.delete': ('core.html#ptyregistry.delete', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.get': ('core.html#ptyregistry.get', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.shutdown': ('core.html#ptyregistry.shutdown', 'ptymini/core.py'),
+                              'ptymini.core.PtyRegistry.values': ('core.html#ptyregistry.values', 'ptymini/core.py'),
+                              'ptymini.core.PtySession': ('core.html#ptysession', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.__aenter__': ('core.html#ptysession.__aenter__', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.__aexit__': ('core.html#ptysession.__aexit__', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.__init__': ('core.html#ptysession.__init__', 'ptymini/core.py'),
+                              'ptymini.core.PtySession._eof': ('core.html#ptysession._eof', 'ptymini/core.py'),
+                              'ptymini.core.PtySession._notify': ('core.html#ptysession._notify', 'ptymini/core.py'),
+                              'ptymini.core.PtySession._on_read': ('core.html#ptysession._on_read', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.attach': ('core.html#ptysession.attach', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.kill': ('core.html#ptysession.kill', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.model': ('core.html#ptysession.model', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.read_from': ('core.html#ptysession.read_from', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.resize': ('core.html#ptysession.resize', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.terminate': ('core.html#ptysession.terminate', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.wait': ('core.html#ptysession.wait', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.wait_change': ('core.html#ptysession.wait_change', 'ptymini/core.py'),
+                              'ptymini.core.PtySession.write': ('core.html#ptysession.write', 'ptymini/core.py'),
+                              'ptymini.core.Ring': ('core.html#ring', 'ptymini/core.py'),
+                              'ptymini.core.Ring.__init__': ('core.html#ring.__init__', 'ptymini/core.py'),
+                              'ptymini.core.Ring.__len__': ('core.html#ring.__len__', 'ptymini/core.py'),
+                              'ptymini.core.Ring.append': ('core.html#ring.append', 'ptymini/core.py'),
+                              'ptymini.core.Ring.read_from': ('core.html#ring.read_from', 'ptymini/core.py'),
+                              'ptymini.core.cull_loop': ('core.html#cull_loop', 'ptymini/core.py')}}}

ptymini-0.0.1/ptymini/bg.py

@@ -0,0 +1,272 @@
+"""The bgterm API: sync, cursor-paged background terminal sessions
+
+The [bgterm](https://github.com/AnswerDotAI/bgterm) package, folded in: a *sync*, sid-based API for background terminal sessions — start once, send input later, wait a bounded time, read what arrived since your last look. It is the cursor view of a `PtySession`, for callers that live outside an event loop (kernel tools, plain scripts, an LLM deciding between actions): every session shares one private asyncio loop on a daemon thread, and each call marshals onto it and blocks, so `write_stdin(sid, "2+2\n", 500)` means what it always meant. The buffering, paging, and drop accounting are the `Ring`'s, which was extracted from bgterm in the first place; `PollResult` and every function signature are unchanged from the original package.
+
+Docs: https://AnswerDotAI.github.io/ptymini/bg.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/01_bg.ipynb.
+
+# %% auto #0
+__all__ = ['DEFAULT_MAX_BUFFER_BYTES', 'DEFAULT_MAX_OUTPUT_BYTES', 'Cmd', 'BgtermError', 'PollResult', 'list_sessions',
+           'start_bgterm', 'write_stdin', 'poll', 'read', 'wait', 'terminate', 'kill', 'close_bgterm', 'Session']
+
+# %% ../nbs/01_bg.ipynb #214abe5a
+import asyncio, itertools, os, signal, threading
+from dataclasses import dataclass
+from .core import PtySession
+
+DEFAULT_MAX_BUFFER_BYTES = 1_000_000
+DEFAULT_MAX_OUTPUT_BYTES = 65_536
+Cmd = str | list[str]
+
+class BgtermError(RuntimeError):
+    "Raised when a bgterm session cannot be started, found, or controlled."
+
+# %% ../nbs/01_bg.ipynb #f9dfa8f5
+_loop, _loop_lock = None, threading.Lock()
+
+def _ensure_loop():
+    global _loop
+    with _loop_lock:
+        if _loop is None or _loop.is_closed():
+            _loop = asyncio.new_event_loop()
+            threading.Thread(target=_loop.run_forever, daemon=True, name='ptymini-bg').start()
+    return _loop
+
+def _call(coro):
+    "Run `coro` on the bg loop thread and block for its result."
+    return asyncio.run_coroutine_threadsafe(coro, _ensure_loop()).result()
+
+# %% ../nbs/01_bg.ipynb #c8b59e13
+@dataclass(slots=True)
+class PollResult:
+    "Unread output returned by a `write_stdin()` or `poll()` call."
+
+    text: str
+    data: bytes
+    start_offset: int
+    end_offset: int
+    buffer_start_offset: int
+    buffer_end_offset: int
+    bytes_returned: int
+    remaining_bytes: int
+    dropped_bytes: int
+    running: bool
+    exit_code: int | None
+
+    @property
+    def truncated(self):
+        "Return whether output was paged or older unread bytes were dropped."
+        return self.remaining_bytes > 0 or self.dropped_bytes > 0
+
+# %% ../nbs/01_bg.ipynb #ee8593c4
+class _BgSession:
+    "Sync cursor facade over one `PtySession` living on the bg loop."
+    def __init__(self, s:PtySession, encoding:str, errors:str):
+        self.s, self.encoding, self.errors, self.cursor, self._closed = s, encoding, errors, 0, False
+
+    @classmethod
+    def start(cls, cmd:Cmd=None, cwd=None, env=None, shell=None, encoding='utf-8', errors='replace',
+        max_buffer_bytes=DEFAULT_MAX_BUFFER_BYTES):
+        if cmd is None: cmd = os.environ.get('SHELL', '/bin/sh')
+        if shell is None: shell = isinstance(cmd, str)
+        if shell and isinstance(cmd, str): cmd = ['/bin/sh', '-c', cmd]
+        elif isinstance(cmd, str): cmd = [cmd]
+        env = dict(os.environ if env is None else env, TERM='dumb')
+        async def _spawn(): return PtySession(list(cmd), cwd=cwd, env=env, buffer_bytes=max_buffer_bytes)
+        return cls(_call(_spawn()), encoding, errors)
+
+    @property
+    def running(self): return self.s.alive
+    @property
+    def exit_code(self): return self.s.exit_code
+
+    def _read(self, max_output_bytes):
+        if max_output_bytes is not None and max_output_bytes < 0: raise ValueError('max_output_bytes must be >= 0')
+        r = self.s.ring
+        payload, end_offset, dropped = r.read_from(self.cursor, max_output_bytes)
+        start_offset = end_offset - len(payload)
+        self.cursor = end_offset
+        return PollResult(payload.decode(self.encoding, errors=self.errors), payload, start_offset, end_offset,
+            r.start, r.end, len(payload), max(0, r.end - end_offset), dropped, self.s.alive, self.s.exit_code)
+
+    def read(self, max_output_bytes=DEFAULT_MAX_OUTPUT_BYTES):
+        async def _r(): return self._read(max_output_bytes)
+        return _call(_r())
+
+    def write_stdin(self, chars='', yield_time_ms=0, max_output_bytes=DEFAULT_MAX_OUTPUT_BYTES):
+        async def _w():
+            if chars:
+                data = chars if isinstance(chars, bytes) else chars.encode(self.encoding)
+                try: self.s.write(data)
+                except OSError as e: raise BgtermError('session PTY is no longer writable') from e
+            if yield_time_ms > 0 and self.cursor >= self.s.ring.end and self.s.alive: await self.s.wait_change(timeout=yield_time_ms / 1000)
+            return self._read(max_output_bytes)
+        return _call(_w())
+
+    def poll(self, yield_time_ms=0, max_output_bytes=DEFAULT_MAX_OUTPUT_BYTES): return self.write_stdin('', yield_time_ms, max_output_bytes)
+
+    def wait(self, timeout_ms=None):
+        async def _w():
+            t = None if timeout_ms is None else max(timeout_ms, 0) / 1000
+            try: return await asyncio.wait_for(self.s.wait(), t)
+            except asyncio.TimeoutError: return None
+        return _call(_w())
+
+    def terminate(self):
+        if self.running:
+            try: self.s.kill(signal.SIGTERM)
+            except ProcessLookupError: pass
+
+    def kill(self):
+        if self.running:
+            try: self.s.kill(signal.SIGKILL)
+            except ProcessLookupError: pass
+
+    def close(self, terminate=True, kill_after_ms=1000):
+        if self._closed: return
+        self._closed = True
+        if terminate and self.running:
+            self.terminate()
+            if self.wait(kill_after_ms) is None and self.running:
+                self.kill()
+                self.wait(kill_after_ms)
+
+# %% ../nbs/01_bg.ipynb #0924cc6e
+_REGISTRY_LOCK = threading.Lock()
+_SESSIONS = {}
+_NEXT_SID = itertools.count(1)
+
+
+def _lookup(sid: int):
+    try: return _SESSIONS[int(sid)]
+    except KeyError as e: raise BgtermError(f"unknown bgterm session id {sid!r}") from e
+
+
+def list_sessions():
+    "List active in-process bgterm session ids."
+    with _REGISTRY_LOCK: return tuple(sorted(_SESSIONS))
+
+
+def start_bgterm(cmd: Cmd | None = None, cwd: str | None = None, env: dict[str, str] | None = None, shell: bool | None = None, encoding: str="utf-8",
+    errors: str="replace", max_buffer_bytes: int=DEFAULT_MAX_BUFFER_BYTES):
+    "Start a PTY-backed session and return its integer session id."
+    session = _BgSession.start(cmd, cwd, env, shell, encoding, errors, max_buffer_bytes)
+    with _REGISTRY_LOCK:
+        sid = next(_NEXT_SID)
+        _SESSIONS[sid] = session
+    return sid
+
+
+def write_stdin(sid: int, chars: str = "", yield_time_ms: int = 0, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+    "Write to a session PTY, wait briefly, and return unread output."
+    return _lookup(sid).write_stdin(chars, yield_time_ms, max_output_bytes)
+
+
+def poll(sid: int, yield_time_ms: int = 0, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+    "Wait for unread session output, then return it without writing input."
+    return _lookup(sid).poll(yield_time_ms, max_output_bytes)
+
+
+def read(sid: int, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+    "Return unread session output immediately."
+    return _lookup(sid).read(max_output_bytes)
+
+
+def wait(sid: int, timeout_ms: int | None = None):
+    "Wait for a session to exit and return its exit code."
+    return _lookup(sid).wait(timeout_ms)
+
+
+def terminate(sid: int):
+    "Terminate the session child process."
+    _lookup(sid).terminate()
+
+
+def kill(sid: int):
+    "Kill the session child process."
+    _lookup(sid).kill()
+
+
+def close_bgterm(sid: int, terminate: bool = True, kill_after_ms: int = 1000):
+    "Close a session and remove it from the in-process registry."
+    with _REGISTRY_LOCK: session = _SESSIONS.pop(int(sid), None)
+    if session is None: return
+    session.close(terminate, kill_after_ms)
+
+# %% ../nbs/01_bg.ipynb #8f426dc2
+class Session:
+    "Thin OO wrapper around the sid-based bgterm API."
+
+    def __init__(self, sid: int, close_on_exit=True):
+        self.sid = int(sid)
+        self.close_on_exit = close_on_exit
+        self._closed = False
+
+    @classmethod
+    def start(cls, cmd: Cmd | None = None, cwd: str | None = None, env: dict[str, str] | None = None, shell: bool | None = None, encoding: str="utf-8",
+        errors: str="replace", max_buffer_bytes: int=DEFAULT_MAX_BUFFER_BYTES, close_on_exit:bool=True):
+        "Start a PTY-backed session and wrap it in `Session`."
+        return cls(start_bgterm(cmd, cwd, env, shell, encoding, errors, max_buffer_bytes), close_on_exit)
+
+    @classmethod
+    def open(cls, sid: int, close_on_exit=False):
+        "Wrap an existing session id."
+        _lookup(sid)
+        return cls(sid, close_on_exit)
+
+    def __enter__(self): return self
+
+    def __exit__(self, exc_type, exc, tb):
+        if self.close_on_exit: self.close()
+        return False
+
+    @property
+    def running(self):
+        "Return whether the wrapped session is still running."
+        if self._closed: return False
+        return _lookup(self.sid).running
+
+    @property
+    def exit_code(self):
+        "Return the wrapped session's exit code, if available."
+        if self._closed: return None
+        return _lookup(self.sid).exit_code
+
+    def write_stdin(self, chars: str | bytes = "", yield_time_ms: int = 0, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+        "Write to this session PTY, wait briefly, and return unread output."
+        return write_stdin(self.sid, chars, yield_time_ms, max_output_bytes)
+
+    def send(self, chars: str | bytes = "", yield_time_ms: int = 0, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+        "Alias for `write_stdin()`."
+        return self.write_stdin(chars, yield_time_ms, max_output_bytes)
+
+    def write(self, chars: str | bytes = "", yield_time_ms: int = 0, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+        "Alias for `write_stdin()`."
+        return self.write_stdin(chars, yield_time_ms, max_output_bytes)
+
+    def poll(self, yield_time_ms: int = 0, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+        "Wait for unread output from this session, then return it."
+        return poll(self.sid, yield_time_ms, max_output_bytes)
+
+    def read(self, max_output_bytes: int | None = DEFAULT_MAX_OUTPUT_BYTES):
+        "Return unread output from this session immediately."
+        return read(self.sid, max_output_bytes)
+
+    def wait(self, timeout_ms: int | None = None):
+        "Wait for this session to exit and return its exit code."
+        return wait(self.sid, timeout_ms)
+
+    def terminate(self):
+        "Terminate this session child process."
+        terminate(self.sid)
+
+    def kill(self):
+        "Kill this session child process."
+        kill(self.sid)
+
+    def close(self, terminate: bool = True, kill_after_ms: int = 1000):
+        "Close this session and make repeated closes a no-op."
+        if self._closed: return
+        close_bgterm(self.sid, terminate, kill_after_ms)
+        self._closed = True

ptymini-0.0.1/ptymini/core.py

@@ -0,0 +1,236 @@
+"""`PtySession` and `PtyRegistry`: asyncio pty sessions over one offset-tracked output ring
+
+Every design here serves two consumer shapes over one pty. *Streams* (a websocket handler, a renderer) want every byte in order, pushed as it arrives, with recent scrollback replayed on attach. *Cursors* (an LLM tool that reads "what's new since I last looked") want bounded-memory buffering with paging and honest drop accounting. Both are views over a single structure: the `Ring`, a byte buffer with absolute offsets. Each pty read appends to the ring; a session-wide change event wakes waiters; `read_from(offset)` serves both a stream's next chunk and a cursor's next page, and reports how many bytes fell off the back. There is no server here, no framework, and no persistence beyond the process: web exposure belongs to the embedding app (e.g. jupygate), durable sessions belong to tmux.
+
+Docs: https://AnswerDotAI.github.io/ptymini/core.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_core.ipynb.
+
+# %% auto #0
+__all__ = ['log', 'DEFAULT_ARGV', 'Ring', 'PtySession', 'Gap', 'PtyRegistry', 'cull_loop']
+
+# %% ../nbs/00_core.ipynb #0fc74163
+import asyncio, itertools, logging, os, signal, time
+from collections import deque
+from pathlib import Path
+from tempfile import mkdtemp
+from fastcore.basics import patch
+from ptyprocess import PtyProcess
+
+log = logging.getLogger('ptymini')
+
+# %% ../nbs/00_core.ipynb #97624ef1
+class Ring:
+    "Bounded byte buffer with absolute offsets: `start`..`end` of the retained window, `end` = total bytes ever appended."
+    def __init__(self, max_bytes:int=1_000_000):
+        if max_bytes <= 0: raise ValueError('max_bytes must be > 0')
+        self.max_bytes, self.chunks, self.start, self.end = max_bytes, deque(), 0, 0
+
+    def __len__(self): return self.end - self.start
+
+    def append(self, data:bytes):
+        self.chunks.append((self.end, data))
+        self.end += len(data)
+        while len(self) > self.max_bytes:
+            off, d = self.chunks[0]
+            overflow = len(self) - self.max_bytes
+            if overflow >= len(d):
+                self.chunks.popleft()
+                self.start = off + len(d)
+            else:
+                self.chunks[0] = (off + overflow, d[overflow:])
+                self.start = off + overflow
+
+    def read_from(self,
+        offset:int,                  # Absolute position to read from; behind `start` counts as dropped
+        max_bytes_out:int=None,      # Cap on returned bytes (None: everything retained)
+    ):                               # (data, new_offset, dropped)
+        dropped = max(0, self.start - offset)
+        cur = max(offset, self.start)
+        out = bytearray()
+        for off, d in self.chunks:
+            if off + len(d) <= cur: continue
+            piece = d[max(0, cur - off):]
+            if max_bytes_out is not None: piece = piece[:max_bytes_out - len(out)]
+            if not piece: break
+            out.extend(piece)
+            if max_bytes_out is not None and len(out) >= max_bytes_out: break
+        return bytes(out), cur + len(out), dropped
+
+# %% ../nbs/00_core.ipynb #0bb16e1a
+class PtySession:
+    "One pty process: reads land in a `Ring`, a change event wakes waiters, EOF reaps the exit status."
+    def __init__(self,
+        argv:list[str],          # Command to spawn on the pty
+        cwd:str=None,            # Working directory for the child
+        env:dict=None,           # Child environment; None inherits this process's
+        rows:int=24, cols:int=80,
+        buffer_bytes:int=1_000_000,  # Ring bound: how much recent output is retained
+        name:str=None,           # Optional handle, set by `PtyRegistry`
+    ):
+        self.name, self.alive, self.exit_code = name, True, None
+        self.ring = Ring(buffer_bytes)
+        self.last_activity = time.time()
+        self._evt, self._eof_evt = asyncio.Event(), asyncio.Event()
+        self.proc = PtyProcess.spawn(list(argv), cwd=cwd, env=env, dimensions=(rows, cols))
+        asyncio.get_running_loop().add_reader(self.proc.fd, self._on_read)
+
+    def _notify(self):
+        evt, self._evt = self._evt, asyncio.Event()
+        evt.set()
+
+    def _on_read(self):
+        try: data = self.proc.read(65536)
+        except (EOFError, OSError): data = b''
+        if not data: return self._eof()
+        self.last_activity = time.time()
+        self.ring.append(data)
+        self._notify()
+
+    def _eof(self):
+        self.alive = False
+        asyncio.get_running_loop().remove_reader(self.proc.fd)
+        self.proc.isalive()   # reaps; fills exitstatus/signalstatus
+        self.exit_code = -self.proc.signalstatus if self.proc.signalstatus else self.proc.exitstatus
+        try: self.proc.close()
+        except OSError: pass
+        self._eof_evt.set()
+        self._notify()
+
+    async def wait_change(self,
+        seen_end:int=None,   # Wake when `ring.end` passes this (None: the value at call time)
+        timeout:float=None,  # Max seconds to wait; None waits indefinitely
+    )->bool:                 # True when new output or EOF arrived, False on timeout
+        if seen_end is None: seen_end = self.ring.end
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while self.alive and self.ring.end == seen_end:
+            t = None if deadline is None else max(0, deadline - time.monotonic())
+            try: await asyncio.wait_for(self._evt.wait(), t)
+            except asyncio.TimeoutError: return False
+        return True
+
+    def read_from(self, offset:int, max_bytes_out:int=None): return self.ring.read_from(offset, max_bytes_out)
+
+    def write(self, data:bytes):
+        self.last_activity = time.time()
+        self.proc.write(data)
+
+    def resize(self, rows:int, cols:int): self.proc.setwinsize(rows, cols)
+    def kill(self, sig:int=signal.SIGTERM): self.proc.kill(sig)
+
+    async def wait(self)->int:
+        "The exit code, once the pty dies (negative: terminating signal number)."
+        await self._eof_evt.wait()
+        return self.exit_code
+
+    def model(self)->dict: return dict(name=self.name, alive=self.alive, last_activity=self.last_activity)
+
+    async def __aenter__(self): return self
+    async def __aexit__(self, *exc): await self.terminate(force=True)
+
+# %% ../nbs/00_core.ipynb #35b6ab39
+@patch
+async def terminate(self:PtySession, force:bool=False)->bool:
+    "SIGHUP/SIGCONT/SIGINT/SIGTERM in turn, then SIGKILL if `force`; True if the child ended."
+    for sig in (signal.SIGHUP, signal.SIGCONT, signal.SIGINT, signal.SIGTERM):
+        if not self.proc.isalive(): return True
+        try: self.kill(sig)
+        except ProcessLookupError: return True
+        await asyncio.sleep(self.proc.delayafterterminate)
+    if not self.proc.isalive(): return True
+    if force:
+        self.proc.kill(signal.SIGKILL)
+        await asyncio.sleep(self.proc.delayafterterminate)
+    return not self.proc.isalive()
+
+# %% ../nbs/00_core.ipynb #08b260eb
+class Gap(int):
+    "Bytes lost to ring trimming between two yields of an `attach` stream."
+
+@patch
+async def attach(self:PtySession,
+    gaps:bool=False,       # Also yield `Gap(n)` markers when the stream fell behind the ring?
+    from_start:bool=True,  # Begin at the oldest retained byte (replay); False starts at the live edge
+):
+    "Async byte stream over the session's output: replay, then live; ends at EOF."
+    off = self.ring.start if from_start else self.ring.end
+    while True:
+        data, off, dropped = self.read_from(off)
+        if dropped and gaps: yield Gap(dropped)
+        if data: yield data
+        elif not self.alive: return
+        else: await self.wait_change(seen_end=off)
+
+# %% ../nbs/00_core.ipynb #a2eefe3b
+DEFAULT_ARGV = [os.environ.get('SHELL') or 'bash', '-i']
+
+class PtyRegistry:
+    "Named-session registry: get-or-create, list, terminate. An embedding app or a test drives this."
+
+    def __init__(self,
+        argv:list[str]=None,      # Default spawn command; creation requests may override it
+        cull_timeout:float=0,     # Seconds of inactivity before a terminal is reaped (0 disables)
+    ):
+        self.argv = argv or DEFAULT_ARGV
+        self.cull_timeout, self.terms = cull_timeout, {}
+
+    def _next_name(self): return next(str(i) for i in itertools.count(1) if str(i) not in self.terms)
+
+    async def create(self,
+        name:str=None,           # Existing name reattaches; None auto-numbers
+        argv:list[str]=None,     # Spawn command; the registry default if None
+        cwd:str=None,            # Working directory for the child
+        env:dict=None,           # Replaces the inherited environment
+        appendenv:dict=None,     # Overlays the base environment
+        rc:str=None,             # Shell setup text, written to a private dir; `{rcfile}`/`{rcdir}` substitute into argv and env values
+        rows:int=24, cols:int=80,
+    )->PtySession:
+        "Get session `name` if it exists, else spawn one (auto-named when `name` is None)."
+        if name and name in self.terms: return self.terms[name]
+        name = name or self._next_name()
+        argv = list(argv or self.argv)
+        if rc is not None:
+            rcdir = mkdtemp(prefix='ptymini-rc-')
+            rcfile = str(Path(rcdir)/'.zshrc')  # one name serves bash (--rcfile {rcfile}) and zsh (ZDOTDIR={rcdir})
+            Path(rcfile).write_text(rc)
+            subst = lambda s: s.replace('{rcfile}', rcfile).replace('{rcdir}', rcdir)
+            argv = [subst(a) for a in argv]
+            if env: env = {k: subst(v) for k, v in env.items()}
+            if appendenv: appendenv = {k: subst(v) for k, v in appendenv.items()}
+        full_env = dict(os.environ if env is None else env) | (appendenv or {})  # `env` replaces the inherited environment; `appendenv` overlays the base
+        t = PtySession(argv, cwd=cwd, env=full_env, rows=rows, cols=cols, name=name)
+        self.terms[name] = t
+        return t
+
+    async def delete(self, name:str):
+        t = self.terms.pop(name)
+        await t.terminate(force=True)
+
+    def cull_ready(self)->list[str]:
+        "Names of terminals past the inactivity timeout (empty when culling is disabled)."
+        if not self.cull_timeout: return []
+        now = time.time()
+        return [n for n, t in self.terms.items() if now - t.last_activity > self.cull_timeout]
+
+    async def cull(self):
+        for n in self.cull_ready():
+            log.info('culling inactive session %s', n)
+            await self.delete(n)
+
+    async def shutdown(self):
+        "Reap every terminal; nothing survives the registry."
+        await asyncio.gather(*[self.delete(n) for n in list(self.terms)], return_exceptions=True)
+
+    def get(self, name:str)->PtySession|None: return self.terms.get(name)
+    def values(self): return self.terms.values()
+    def __len__(self): return len(self.terms)
+
+    async def __aenter__(self): return self
+    async def __aexit__(self, *exc): await self.shutdown()
+
+# %% ../nbs/00_core.ipynb #eeed4f3d
+async def cull_loop(reg:PtyRegistry, interval:float=300):
+    "Periodic cull sweep; an embedding app runs this as a task while it serves."
+    while True:
+        await asyncio.sleep(interval)
+        await reg.cull()

ptymini-0.0.1/ptymini.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: ptymini
+Version: 0.0.1
+Summary: Asyncio pty sessions: spawn, write, multi-client attach with replay, and a named registry
+Author-email: Jeremy Howard <github@jhoward.fastmail.fm>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/AnswerDotAI/ptymini
+Project-URL: Documentation, https://AnswerDotAI.github.io/ptymini/
+Keywords: nbdev
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastcore>=2.1.18
+Requires-Dist: ptyprocess>=0.7
+Dynamic: license-file
+
+# ptymini
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`ptymini` fills the gap between `ptyprocess` (a raw pty fd), `pexpect` (sync expect loops), and `terminado` (a pty server welded to tornado): asyncio-native pty *sessions*. A [`PtySession`](https://AnswerDotAI.github.io/ptymini/core.html#ptysession) is one spawned pty that any number of clients can attach to as independent byte streams, each primed from a byte-bounded replay buffer — so a reconnecting client resumes with recent scrollback instead of a blank screen. A [`PtyRegistry`](https://AnswerDotAI.github.io/ptymini/core.html#ptyregistry) adds named get-or-create sessions, injected shell setup (`rc`), and inactivity culling. It carries no server, no framework, and no session persistence beyond the process: web exposure belongs to the embedding app (e.g. [jupygate](https://github.com/AnswerDotAI/jupygate)), and durable session management belongs to tmux.
+
+## Usage
+
+### Installation
+
+Install latest from the GitHub [repository](https://github.com/AnswerDotAI/ptymini):
+
+``` sh
+$ pip install git+https://github.com/AnswerDotAI/ptymini.git
+```
+
+or from [conda](https://anaconda.org/AnswerDotAI/ptymini)
+
+``` sh
+$ conda install -c AnswerDotAI ptymini
+```
+
+or from [pypi](https://pypi.org/project/ptymini/)
+
+``` sh
+$ pip install ptymini
+```
+
+### Documentation
+
+Documentation can be found hosted on this GitHub [repository](https://github.com/AnswerDotAI/ptymini)’s [pages](https://AnswerDotAI.github.io/ptymini/). Additionally you can find package manager specific guidelines on [conda](https://anaconda.org/AnswerDotAI/ptymini) and [pypi](https://pypi.org/project/ptymini/) respectively.

ptymini-0.0.1/ptymini.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+ptymini/__init__.py
+ptymini/_modidx.py
+ptymini/bg.py
+ptymini/core.py
+ptymini.egg-info/PKG-INFO
+ptymini.egg-info/SOURCES.txt
+ptymini.egg-info/dependency_links.txt
+ptymini.egg-info/entry_points.txt
+ptymini.egg-info/requires.txt
+ptymini.egg-info/top_level.txt
+tests/test_bg.py

ptymini-0.0.1/ptymini.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ptymini-0.0.1/ptymini.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[nbdev]
+ptymini = ptymini._modidx:d

ptymini-0.0.1/ptymini.egg-info/requires.txt

@@ -0,0 +1,2 @@
+fastcore>=2.1.18
+ptyprocess>=0.7

ptymini-0.0.1/ptymini.egg-info/top_level.txt

@@ -0,0 +1 @@
+ptymini

ptymini-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ptymini"
+dynamic = ["version"]
+description = "Asyncio pty sessions: spawn, write, multi-client attach with replay, and a named registry"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [{name = "Jeremy Howard", email = "github@jhoward.fastmail.fm"}]
+keywords = ['nbdev']
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = ['fastcore>=2.1.18', 'ptyprocess>=0.7']
+
+[project.urls]
+Repository = "https://github.com/AnswerDotAI/ptymini"
+Documentation = "https://AnswerDotAI.github.io/ptymini/"
+
+[project.entry-points.nbdev]
+ptymini = "ptymini._modidx:d"
+
+[tool.setuptools.dynamic]
+version = {attr = "ptymini.__version__"}
+
+[tool.setuptools.packages.find]
+include = ["ptymini"]
+
+[tool.nbdev]

ptymini-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ptymini-0.0.1/tests/test_bg.py

@@ -0,0 +1,73 @@
+
+import sys, time
+
+from ptymini.bg import Session, close_bgterm, list_sessions, poll, read, start_bgterm, write_stdin
+
+
+def test_functional_write_stdin_collects_output_between_calls():
+    cmd = [sys.executable, "-u", "-c", "import time; print('ready', flush=True); time.sleep(0.5); print('later', flush=True)"]
+    sid = start_bgterm(cmd)
+    try:
+        assert sid in list_sessions()
+        first = poll(sid, 100)
+        assert "ready" in first.text
+
+        second = poll(sid, 700)
+        assert "later" in second.text
+        assert second.dropped_bytes == 0
+    finally: close_bgterm(sid)
+
+
+def test_empty_write_stdin_returns_buffered_backlog_in_pages():
+    cmd = [sys.executable, "-u", "-c", "import sys; sys.stdout.write('x' * 4096); sys.stdout.flush()"]
+    sid = start_bgterm(cmd)
+    try:
+        time.sleep(0.1)
+        first = write_stdin(sid, max_output_bytes=1024)
+        second = read(sid, 1024)
+        assert first.bytes_returned == 1024
+        assert second.bytes_returned == 1024
+        assert first.remaining_bytes > 0
+    finally: close_bgterm(sid)
+
+
+def test_small_buffer_reports_dropped_bytes():
+    cmd = [sys.executable, "-u", "-c", "import sys; sys.stdout.write('a' * 4096); sys.stdout.flush()"]
+    sid = start_bgterm(cmd, max_buffer_bytes=512)
+    try:
+        time.sleep(0.1)
+        result = poll(sid, max_output_bytes=None)
+        assert result.bytes_returned == 512
+        assert result.dropped_bytes == 4096 - 512
+    finally: close_bgterm(sid)
+
+
+def test_functional_session_accepts_input_and_returns_echoed_output():
+    cmd = [
+        sys.executable,
+        "-u",
+        "-c",
+        "print('ready', flush=True)\n"
+        "import sys\n"
+        "for line in sys.stdin:\n"
+        "    sys.stdout.write(f'ACK:{line}')\n"
+        "    sys.stdout.flush()\n"]
+    sid = start_bgterm(cmd)
+    try:
+        ready = poll(sid, 500)
+        assert "ready" in ready.text
+
+        reply = write_stdin(sid, "hello\n", 100)
+        if "ACK:hello" not in reply.text: reply = poll(sid, 500)
+        assert "ACK:hello" in reply.text
+    finally: close_bgterm(sid)
+
+
+def test_object_wrapper_delegates_to_sid_api():
+    cmd = [sys.executable, "-u", "-c", "print('ready', flush=True); raise SystemExit(3)"]
+    with Session.start(cmd) as sess:
+        ready = sess.poll(500)
+        assert "ready" in ready.text
+        assert sess.sid in list_sessions()
+        assert sess.running
+        assert sess.wait(3000) == 3