Migrating from padelpy

This guide helps users of padelpy (baseline ≥ 0.1.17) move selected workflows to padelpy2 while keeping the stock Yap PaDEL-Descriptor JAR.

padelpy2 does not replace padelpy. For choosing between them, start with When to use which package.

Should you migrate?

Stay on padelpy if you need a stdlib-only stack (no RDKit, no pandas) and SMILES/SDF → dict helpers.

Migrate toward padelpy2 if you want RDKit molecules, pandas DataFrames, typed catalogs, and stock-JAR continuity (including padeldescriptor).

Stock JAR continuity

padelpy and padelpy2 both drive the classic stock JAR family. Migration here preserves that identity. Do not assume numeric agreement with other PaDEL-family distributions without your own checks.

Concept mapping

padelpy

padelpy2

Notes

from_smiles / from_sdf / from_mdl

padelpy2.compat.from_smiles (etc.)

DataFrame by default; RDKit required

Return OrderedDict / list of dicts

DataFrame, or as_dict=True

as_dict is best-effort, not identical

padeldescriptor(...)

padelpy2.padeldescriptor(...) or from padelpy2.wrapper import padeldescriptor

Same keyword-oriented CLI surface

(no Calculator)

Calculator(catalog, config=...)

Preferred for new RDKit-native code

Default descriptor run (-2d)

compat default: descriptors_2d

3D catalogs need conformers via Calculator

Side-by-side examples

padelpy (dict-oriented):

from padelpy import from_smiles

row = from_smiles("CCO")  # OrderedDict-like mapping

padelpy2 compat (DataFrame-oriented):

from padelpy2.compat import from_smiles

df = from_smiles("CCO")                 # one-row DataFrame
row = from_smiles("CCO", as_dict=True)  # best-effort dict

RDKit-native Calculator (recommended for new code):

from rdkit import Chem
from rdkit.Chem import AllChem
from padelpy2 import Calculator
from padelpy2.descriptors import Weight

mol = Chem.AddHs(Chem.MolFromSmiles("CCO"))
AllChem.Compute2DCoords(mol)
df = Calculator([Weight])([mol])

Low-level CLI (both packages):

# padelpy
from padelpy import padeldescriptor

# padelpy2 — keyword surface aligned for continuity
from padelpy2 import padeldescriptor

Behavioral differences

  • Dependencies: padelpy2 compat and Calculator require RDKit and pandas; padelpy does not.

  • Return type: DataFrames drop the engine Name column by default.

  • ``as_dict``: Convenient for migration scripts; do not assume identical key sets or OrderedDict ordering versus padelpy.

  • Fingerprints / descriptors flags: compat descriptors=True selects the default 2D catalog; fingerprints=True adds all fingerprint types.

  • Java: Both expect a system JRE on PATH. Neither auto-downloads a JRE.

Validation checkpoint

  1. Install padelpy2 with RDKit (see Installation) in an environment that can also import padelpy if you want a side-by-side check.

  2. Run a single ethanol SMILES through padelpy2.compat.from_smiles and confirm a DataFrame with the expected column count for your flags (default 2D catalog → 1444 columns; see API stability).

  3. For numeric continuity on a small subset, compare Weight (or ALOGP / Crippen / Weight) via Calculator against your historical stock-JAR CSV. Use stock-JAR (or padelpy2 oracle) values as the reference—not another PaDEL-family distribution.

  4. Keep using padelpy unchanged for any stdlib-only deployment paths.

See also