Metadata-Version: 2.3
Name: pymol_remote
Version: 0.0.5
Author-email: Simon Mathis <simon.mathis@gmail.com>
License: // Last Update: 2024-07-23
        // Author: Simon Mathis (simon.mathis@cl.cam.ac.uk)
        // Description: The license of the PyMOL RPC plugin
        
        NOTE: This code is inspired by the pymol rpc code originally written by
        Greg Landrum (https://github.com/schrodinger/pymol-open-source/blob/master/modules/pymol/rpc.py)
        and is licensed under the same terms as PyMOL.
        
        
        Open-Source PyMOL Copyright Notice
         ==================================
        
         The Open-Source PyMOL source code is copyrighted, but you can freely
         use and copy it as long as you don't change or remove any of the
         Copyright notices. The Open-Source PyMOL product is made available
         under the following open-source license terms:
        
         ----------------------------------------------------------------------
         Open-Source PyMOL is Copyright (C) Schrodinger, LLC.
        
         All Rights Reserved
        
         Permission to use, copy, modify, distribute, and distribute modified
         versions of this software and its built-in documentation for any
         purpose and without fee is hereby granted, provided that the above
         copyright notice appears in all copies and that both the copyright
         notice and this permission notice appear in supporting documentation,
         and that the name of Schrodinger, LLC not be used in advertising or
         publicity pertaining to distribution of the software without specific,
         written prior permission.
        
         SCHRODINGER, LLC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
         INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
         NO EVENT SHALL SCHRODINGER, LLC BE LIABLE FOR ANY SPECIAL, INDIRECT OR
         CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
         OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
         OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
         USE OR PERFORMANCE OF THIS SOFTWARE.
         ----------------------------------------------------------------------
        
         PyMOL Trademark Notice
         ======================
        
         PyMOL(TM) is a trademark of Schrodinger, LLC. Derivative
         software which contains PyMOL source code must be plainly
         distinguished from any and all PyMOL products distributed by Schrodinger,
         LLC in all publicity, advertising, and documentation.
        
         The slogans, "Includes PyMOL(TM).", "Based on PyMOL(TM) technology.",
         "Contains PyMOL(TM) source code.", and "Built using PyMOL(TM).", may
         be used in advertising, publicity, and documentation of derivative
         software provided that the notice, "PyMOL is a trademark of Schrodinger,
         LLC.", is included in a footnote or at the end of the
         document.
        
         All other endorsements employing the PyMOL trademark require specific,
         written prior permission.
License-File: LICENSE
Requires-Python: >=3.8
Description-Content-Type: text/markdown

[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PyPI](https://img.shields.io/pypi/v/pymol-remote?color=blue)](https://pypi.org/project/pymol-remote/)
# PyMOL Remote
> A simple RPC client for sending commands and data between Python and PyMOL.
(RPC = Remote Procedure Call)

![Screenshot of pymol with pymol-remote](./assets/screenshot.png)

## 1. Installation
`pymol-remote` has no dependencies beyond the base Python standard library, so installation is straightforward:
```bash
pip install pymol-remote
```

On the server side, you need to have a working `pymol` installation. Whichever python interpreter you are using to run `pymol` should also have `pymol-remote` installed (or needs to have `pymol-remote` in its pythonpath). The easiest way to do this is to [install `pymol` via `conda`](https://pymol.org/conda/) into an existing or new environment and then install `pymol-remote` in the same environment with `pip install pymol-remote`.

On the client side, you need to have a working Python environment with `pymol-remote` installed.

## 2. Usage
### 2.1 Server side (where PyMOL is running)
```bash
# Navigate into your pymol environment
#  that environment should have both, pymol and pymol_remote installed
# e.g.:
# conda activate pymol

# If pymol_remote is installed, the following command will start the server
pymol_remote
```
This command will start pymol, and in the pymol console you should see a likely guess of your IP address (and the correct port number, 9123 by default).
If this IP address does not work, you might need to use commands like `ifconfig` or `ipconfig` on your computer to find the correct IP address of the server in your local network.

### 3.2 Client side (where you want to run your Python code)
Make sure you have the `pymol_remote` package installed in the Python environment where you want to run your code.
Make sure you ran `pymol_remote` on the server side before running the Python code below.

```python
from pymol_remote.client import PymolSession

# NOTE: When you run `pymol_remote` on the server side, it will print a likely guess of your 
#  IP address (and the correct port number, 9123 by default). Try that IP address first,
#  if it doesn't work you might need to use commands like `ifconfig` or `ipconfig` on
#  your computer to find the correct IP address of the server in your local network.
pymol = PymolSession(hostname="ip_address_of_server", port=9123)
 
# You can now send commands to PyMOL
pymol.fetch("6lyz")
pymol.do("remove solvent")
pymol.do("set valence, on")
pymol.get_state(format="cif")

# To see all available methods use
pymol.help()

# To get more help on a specific method, use
pymol.help("fetch")

# To get more general documentation information, use
pymol.print_help()
```

## 3. Credit
This implementation is inspired by and based on the original [RDKit RPC](https://github.com/rdkit/rdkit/blob/master/rdkit/python/rdkit/Chem/PyMol.py) implementation and [PyMOL RPC](https://github.com/schrodinger/pymol-open-source/blob/9d3061ca58d8b69d7dad74a68fc13fe81af0ff8e/modules/pymol/rpc.py) by Greg Landrum. Thank you Greg! And thank you Schrodinger for making PyMOL open source!

## 4. License
This code is licensed under the same terms as PyMOL. See [LICENSE](./LICENSE) for more details.
