Metadata-Version: 2.4
Name: pyocl-idor
Version: 0.8.3
Summary: OpenChemLib via python
Author-email: Julien Hazemann <julien.hazemann@idorsia.com>, Manuel Sellner <manuel.sellner@idorsia.com>, Thomas Liphardt <thomas.liphardt@idorsia.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jpype1>=1.5.1
Requires-Dist: numba>=0.61.0
Dynamic: license-file

# PyOCL

## Description

The PyOCL (Python OpenChemLib) is a python wrapper for the Java-based [OpenChemLib](https://github.com/Actelion/openchemlib).


## Prerequisites

Environment variable ```JAVA_HOME``` must point to a Java 21 or newer runtime.
The bundled PyOCL helper classes require Java 21. E.g.
```bash
export JAVA_HOME=/path/to/jdk-21
```

PyOCL enables native access when it starts the JVM so that JPype can load its
native bridge without restricted-method warnings on Java 24 and newer. If your
application starts the JVM before importing PyOCL, pass the option yourself:

```python
import jpype

jpype.startJVM("--enable-native-access=ALL-UNNAMED")

import pyocl
```

This option permits native access for Java classes loaded from the classpath.
Set it when starting the JVM; restart the Python process or notebook kernel if
the JVM is already running without it.

## Dependencies

Some functionalities of PyOCL require RDKit or pandas to be installed (conversion between OCL StereoMolecules and RDKit molecules, conversion between DataWarrior dwar files and pandas dataframes).  
If you need these functionalities, you have to install RDKit and/or pandas separately:

```bash
pip install pandas==2.2.3
pip install rdkit==2024.3.6
```

## Installation

1. Generate and activate virtual environment:
```bash
# Conda
conda create -n pyocl python=3.10
conda activate pyocl

# Python venv
python -m venv venv
. venv/bin/activate  # Command for Linux
.\venv\Scripts\activate  # Command for Windows
```

2. Install PyOCL:
```bash
# From PyPI
python -m pip install pyocl-idor

# From cloned repository
git clone https://github.com/actelion/pyocl.git
python -m pip install pyocl/

# Directly from GitHub with pip
python -m pip install git+https://github.com/actelion/pyocl.git
```

The PyPI distribution is named `pyocl-idor`; Python imports use `pyocl`, for
example `from pyocl.chem import StereoMolecule`.

## Documentation

You can build a local version of the full PyOCL documentation:

```bash
# Create environment and install dependencies
conda create -n pyocl python=3.10
conda activate pyocl
git clone https://github.com/actelion/pyocl.git
python -m pip install pyocl/ sphinx==8.1.3 sphinx-rtd-theme==3.0.2 pandas==2.2.3 rdkit==2024.3.6

# Build documentation
cd pyocl/docs/
sphinx-apidoc -o . ../pyocl
make html  # Command for Linux
.\make.bat html  # Command for Windows
```

This creates the directory `docs/_build/html` in which you can find a file called `index.html`. You can open this file in your browser to access the documentation.

This package also contains tutorials about specific functionalities of PyOCL. While they are covered in the html version of the documentation, there is also a **Python script** and a **Jupyter notebook** for each of the tutorials. These files can be found in `docs/tutorials`.

## CI and PyPI releases

The GitHub Actions workflow in `.github/workflows/release.yml` builds a wheel and
source distribution on branch pushes and pull requests. It checks package
metadata and bundled Java files, then tests the installed wheel on Linux,
Windows, and macOS with Python 3.10 and 3.12 and Java 21. The Java setup action
sets `JAVA_HOME` and adds Java to `PATH` in every test job.

Pushing a version tag such as `v0.8.2` also publishes the tested distributions to
PyPI under the distribution name `pyocl-idor`. Branch pushes, pull requests, and
manual workflow runs run the checks
without publishing. Versions are derived from Git tags by `setuptools_scm`;
the release build must match the pushed tag.
