PyOCL

Description

The PyOCL (Python OpenChemLib) is a python wrapper for the Java-based 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.

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:

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:

pip install pandas==2.2.3
pip install rdkit==2024.3.6

Installation

1. Generate and activate virtual environment:

# 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:

# 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:

# 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.