Metadata-Version: 2.4
Name: herethere
Version: 0.3.1
Summary: herethere
Author-email: b3b <ash.b3b@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/b3b/herethere
Project-URL: Changelog, https://github.com/b3b/herethere/blob/master/CHANGELOG.rst
Keywords: ssh,asyncssh,jupyter,ipython,ipython-magic,jupyter-magic,remote-python,remote-repl,remote-debugging,repl,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: asyncssh<3,>=2.17
Requires-Dist: click>=8
Requires-Dist: python-dotenv
Provides-Extra: magic
Requires-Dist: ipython; extra == "magic"
Requires-Dist: ipywidgets; extra == "magic"
Dynamic: license-file

herethere
=========

.. start-badges
.. image:: https://img.shields.io/pypi/v/herethere.svg
    :target: https://pypi.python.org/pypi/herethere
    :alt: Latest version on PyPI
.. image:: https://img.shields.io/pypi/pyversions/herethere.svg
    :target: https://pypi.python.org/pypi/herethere
    :alt: Supported Python versions
.. image:: https://github.com/b3b/herethere/actions/workflows/tests.yml/badge.svg?branch=master
    :target: https://github.com/b3b/herethere/actions/workflows/tests.yml?query=branch%3Amaster
    :alt: CI Status
.. image:: https://codecov.io/github/b3b/herethere/coverage.svg?branch=master
    :target: https://codecov.io/github/b3b/herethere?branch=master
    :alt: Code coverage status
.. end-badges

Run Python interactively inside live apps and devices.

``herethere`` starts a small SSH-backed server inside a Python process, then
lets you connect from the ``there`` CLI, another Python session, or a Jupyter
notebook to inspect, modify, and interact with the namespace of that running
process.

It was created for workflows where Python is running inside an app, device,
or environment that is awkward to interact with directly.
The same idea is useful for Raspberry Pi and robotics projects,
Kivy/mobile apps, containers, long-running experiments, server-side apps,
and other cases where logs or a separate remote shell are not enough.

``herethere`` is based on the `AsyncSSH <https://github.com/ronf/asyncssh>`_
library. AsyncSSH provides the SSH toolkit; ``herethere`` adds a small
Python, CLI, and Jupyter workflow layer on top.

:Code repository: https://github.com/b3b/herethere
:Documentation: https://herethere.me/library

Features
--------

* Execute Python snippets inside the namespace of a live target process.
* Connect using the ``there`` CLI, Python code, or Jupyter notebooks with
  ``%connect-there`` and ``%%there``.
* Retrieve values, view logs, run shell commands, and transfer files.
* Produce structured JSON output for scripts and coding agents.  
* Use SSH authentication and encrypted transport through AsyncSSH.
* Generate reviewable notebook cells from natural-language requests with
  ``%%there ai``.

Installation
------------

Install ``herethere`` in the Python environment that will start the server:

.. code-block:: bash

   pip install herethere

If you want to connect from Jupyter using the IPython magics, install the
``magic`` extra in the notebook/client environment:

.. code-block:: bash

   pip install "herethere[magic]"

Quickstart
----------

Target process
~~~~~~~~~~~~~~

Start ``herethere`` inside the Python process you want to interact with.

.. code-block:: python

   from herethere.here import ServerConfig, start_server

   state = {"speed": 1}

   await start_server(ServerConfig.load(prefix="here"), namespace=globals())

Terminal client
~~~~~~~~~~~~~~~

Run code or retrieve a value from the target process:

.. code-block:: console

   there run --code "state['speed'] = 3"
   there get "state"

Use structured output for scripts and coding agents:

.. code-block:: console

   there --json get "state"

Jupyter notebook / client
~~~~~~~~~~~~~~~~~~~~~~~~~

Connect from your local Jupyter notebook:

.. code-block:: python

   %load_ext herethere.magic
   %connect-there

Use the ``%%there`` cell magic to inspect variables, call functions, or update
state while the target process keeps running:

.. code-block:: python

   %%there

   print(state)
   state["speed"] = 3
   print(state)

Agent skill
-----------

``herethere`` bundles an
`agent skill <https://github.com/b3b/herethere/tree/master/herethere/.agents/skills/there-cli>`_
for using the ``there`` CLI. Install it for your project with
`Library Skills <https://github.com/tiangolo/library-skills>`_:

.. code-block:: console

   uvx library-skills

Trust model
-----------

A connected client can execute Python code inside the target process. Treat
access to ``herethere`` like access to a Python REPL running inside your app.

Use it only for development workflows where you control both sides of the
connection. Do not expose it publicly or give access to untrusted users.


Related resources
-----------------

* `PythonHere <https://herethere.me/pythonhere>`_: an application that uses the
  ``herethere`` library
* `Kivy Remote Shell <https://github.com/kivy/kivy-remote-shell>`_: a remote
  SSH + Python interactive shell application using Twisted
* `Twisted Manhole <https://twistedmatrix.com/documents/8.1.0/api/twisted.manhole.html>`_:
  interactive interpreter and direct manipulation support for Twisted
