API stability

This page records the frozen public contract for padelpy2 on the v0.x line through v1.0 unless a major version bump says otherwise. Additive APIs are welcome when they preserve the defaults below.

See also API Documentation (autodoc) and Architecture.

Frozen top-level exports

Importable from padelpy2 (package __all__):

  • Calculator

  • PaDELConfig

  • __version__

  • descriptors, descriptors_2d, descriptors_3d

  • fingerprints

  • padeldescriptor

Catalog types Descriptor and Fingerprint, and individual catalog singletons (for example Weight, MACCSFingerprinter), are imported from submodules. padelpy2.utils is semi-internal (empty __all__).

Frozen Calculator behavior

  • Calculator(descriptors, config=None) — high-level calculator over the stock Yap JAR.

  • Calculator.__call__(mols) returns a pandas.DataFrame and drops the engine Name column by default.

  • Additive optional keyword-only arguments (defaults preserve v0.1 behavior):

    • chunk_size=None — optional batching

    • retain_names=False — drop engine Name unless True

    • on_error="raise" — fail fast; "nan" isolates invalid molecules / failed chunks as NaN rows when a column schema is available

  • Default PaDELConfig field values and padeldescriptor keyword names used by existing callers are stable.

Default catalog column counts

These shapes are guarded in CI (metadata counts and live Calculator runs):

Catalog

Columns

descriptors_2d

1444

descriptors_3d

431

descriptors

1875

Each fingerprint

Fingerprint.n_bits

Stock-JAR golden oracles under tests/fixtures/oracles_v1/ pin representative values for these catalogs.

Excluded from default lists

The following descriptors exist as importable singletons but are not in the default descriptors / descriptors_2d lists:

  • AminoAcidCount

  • IPMolecularLearning

  • KierHallSmarts

Stability checklist (do not break without a major version)

  • Signatures of Calculator.__init__ and Calculator.__call__ (required arguments)

  • Default contents of descriptors / descriptors_2d / descriptors_3d / fingerprints

  • Default dropping of the Name column

  • padeldescriptor keyword names used by existing callers

  • Default PaDELConfig field values