pydompekeygen 1.0.0__tar.gz

pydompekeygen-1.0.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

pydompekeygen-1.0.0/.gitignore

@@ -0,0 +1,138 @@
+# Pickles
+*.pkl
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PyCharm stuff:
+.idea/
+
+# VSCode stuff:
+.vscode/
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

pydompekeygen-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OlivierBeq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydompekeygen-1.0.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pydompekeygen
+Version: 1.0.0
+Summary: A Python implementation of DompéKeys
+Author-email: "Olivier J. M. Béquignon" <olivier.bequignon.maintainer@gmail.com>
+Maintainer-email: "Olivier J. M. Béquignon" <olivier.bequignon.maintainer@gmail.com>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/OlivierBeq/PyDompeKeyGen
+Project-URL: repository, https://github.com/OlivierBeq/PyDompeKeyGen
+Keywords: qsar,cheminformatics,fingerprint,dompé
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rdkit
+Dynamic: license-file
+
+# PyDompeKeyGen
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
+[![Status](https://img.shields.io/badge/status-beta-orange.svg)](pyproject.toml)
+[![Paper](https://img.shields.io/badge/DOI-10.1186%2Fs13321--024--00813--4-blue.svg)](https://doi.org/10.1186/s13321-024-00813-4)
+
+A lightweight Python / [RDKit](https://www.rdkit.org/) implementation of **DompéKeys** — a set of 1,064 SMARTS-based structural keys for mapping chemical space, built for use as an interpretable molecular fingerprint.
+
+DompéKeys were originally developed by scientists at [Dompé farmaceutici](https://www.dompe.com/) as part of the [EXSCALATE](https://exscalate.eu/) drug-discovery platform and published in the *Journal of Cheminformatics* ([Manelfi, Tazzari, et al., 2024](https://doi.org/10.1186/s13321-024-00813-4)). This package provides a small, dependency-light way to generate the corresponding fingerprint for any RDKit molecule.
+
+## ✨ Features
+
+- 🧬 **1,064 curated SMARTS keys** spanning amino acids, acids, metal binders, toxicophores, ring systems, and generic pharmacophoric features (H-bond donors/acceptors, etc.), organized across 5 complexity levels.
+- 🎯 **Single-class API** — one object, one method, one RDKit `ExplicitBitVect` out.
+- ⚡ **Fast startup** — the SMARTS catalog is compiled once and cached to disk (`smarts.pkl`), and automatically rebuilt if your installed RDKit version changes.
+- 🔍 **Interpretable** — every set bit maps back to a named, human-readable substructure.
+
+## 📦 Installation
+
+PyDompeKeyGen is not yet published to PyPI. Install it directly from GitHub:
+
+```bash
+pip install git+https://github.com/OlivierBeq/PyDompeKeyGen.git
+```
+
+Or clone and install locally for development:
+
+```bash
+git clone https://github.com/OlivierBeq/PyDompeKeyGen.git
+cd PyDompeKeyGen
+pip install -e .
+```
+
+Requires Python ≥ 3.10 and [RDKit](https://pypi.org/project/rdkit/) (installed automatically as a dependency).
+
+## 🚀 Quick start
+
+```python
+from rdkit import Chem
+from pydompekeygen import PyDompeKeys
+
+# Load the DompéKeys catalog (built once, then cached on disk)
+dompekeys = PyDompeKeys()
+
+# Generate a fingerprint for a molecule
+mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")  # aspirin
+fingerprint = dompekeys.GetFingerprint(mol)
+
+print(f"{fingerprint.GetNumOnBits()} / {dompekeys.num_bits} keys matched")
+```
+
+See the [usage guide](docs/usage.md) for similarity calculations, converting fingerprints to NumPy arrays, batch processing, and inspecting which named keys matched.
+
+## 📚 Documentation
+
+| Document | Description |
+|---|---|
+| [docs/usage.md](docs/usage.md) | Practical guide: similarity search, NumPy conversion, batch processing, introspecting matched keys |
+| [docs/api.md](docs/api.md) | API reference for the `PyDompeKeys` class |
+| [docs/background.md](docs/background.md) | What DompéKeys are, the 5 complexity levels, and how to cite the original paper |
+
+## 📖 Citation
+
+If you use PyDompeKeyGen in published work, please cite the original DompéKeys paper:
+
+> Manelfi, C., Tazzari, V., Lunghini, F. *et al.* "DompeKeys": a set of novel substructure-based descriptors for efficient chemical space mapping, development and structural interpretation of machine learning models, and indexing of large databases. *J Cheminform* **16**, 21 (2024). https://doi.org/10.1186/s13321-024-00813-4
+
+See [docs/background.md](docs/background.md) for a BibTeX entry.
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome at [github.com/OlivierBeq/PyDompeKeyGen](https://github.com/OlivierBeq/PyDompeKeyGen).
+
+## ⚖️ License
+
+Released under the [MIT License](LICENSE).

pydompekeygen-1.0.0/README.md

@@ -0,0 +1,77 @@
+# PyDompeKeyGen
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
+[![Status](https://img.shields.io/badge/status-beta-orange.svg)](pyproject.toml)
+[![Paper](https://img.shields.io/badge/DOI-10.1186%2Fs13321--024--00813--4-blue.svg)](https://doi.org/10.1186/s13321-024-00813-4)
+
+A lightweight Python / [RDKit](https://www.rdkit.org/) implementation of **DompéKeys** — a set of 1,064 SMARTS-based structural keys for mapping chemical space, built for use as an interpretable molecular fingerprint.
+
+DompéKeys were originally developed by scientists at [Dompé farmaceutici](https://www.dompe.com/) as part of the [EXSCALATE](https://exscalate.eu/) drug-discovery platform and published in the *Journal of Cheminformatics* ([Manelfi, Tazzari, et al., 2024](https://doi.org/10.1186/s13321-024-00813-4)). This package provides a small, dependency-light way to generate the corresponding fingerprint for any RDKit molecule.
+
+## ✨ Features
+
+- 🧬 **1,064 curated SMARTS keys** spanning amino acids, acids, metal binders, toxicophores, ring systems, and generic pharmacophoric features (H-bond donors/acceptors, etc.), organized across 5 complexity levels.
+- 🎯 **Single-class API** — one object, one method, one RDKit `ExplicitBitVect` out.
+- ⚡ **Fast startup** — the SMARTS catalog is compiled once and cached to disk (`smarts.pkl`), and automatically rebuilt if your installed RDKit version changes.
+- 🔍 **Interpretable** — every set bit maps back to a named, human-readable substructure.
+
+## 📦 Installation
+
+PyDompeKeyGen is not yet published to PyPI. Install it directly from GitHub:
+
+```bash
+pip install git+https://github.com/OlivierBeq/PyDompeKeyGen.git
+```
+
+Or clone and install locally for development:
+
+```bash
+git clone https://github.com/OlivierBeq/PyDompeKeyGen.git
+cd PyDompeKeyGen
+pip install -e .
+```
+
+Requires Python ≥ 3.10 and [RDKit](https://pypi.org/project/rdkit/) (installed automatically as a dependency).
+
+## 🚀 Quick start
+
+```python
+from rdkit import Chem
+from pydompekeygen import PyDompeKeys
+
+# Load the DompéKeys catalog (built once, then cached on disk)
+dompekeys = PyDompeKeys()
+
+# Generate a fingerprint for a molecule
+mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")  # aspirin
+fingerprint = dompekeys.GetFingerprint(mol)
+
+print(f"{fingerprint.GetNumOnBits()} / {dompekeys.num_bits} keys matched")
+```
+
+See the [usage guide](docs/usage.md) for similarity calculations, converting fingerprints to NumPy arrays, batch processing, and inspecting which named keys matched.
+
+## 📚 Documentation
+
+| Document | Description |
+|---|---|
+| [docs/usage.md](docs/usage.md) | Practical guide: similarity search, NumPy conversion, batch processing, introspecting matched keys |
+| [docs/api.md](docs/api.md) | API reference for the `PyDompeKeys` class |
+| [docs/background.md](docs/background.md) | What DompéKeys are, the 5 complexity levels, and how to cite the original paper |
+
+## 📖 Citation
+
+If you use PyDompeKeyGen in published work, please cite the original DompéKeys paper:
+
+> Manelfi, C., Tazzari, V., Lunghini, F. *et al.* "DompeKeys": a set of novel substructure-based descriptors for efficient chemical space mapping, development and structural interpretation of machine learning models, and indexing of large databases. *J Cheminform* **16**, 21 (2024). https://doi.org/10.1186/s13321-024-00813-4
+
+See [docs/background.md](docs/background.md) for a BibTeX entry.
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome at [github.com/OlivierBeq/PyDompeKeyGen](https://github.com/OlivierBeq/PyDompeKeyGen).
+
+## ⚖️ License
+
+Released under the [MIT License](LICENSE).

pydompekeygen-1.0.0/docs/api.md

@@ -0,0 +1,67 @@
+# API reference
+
+## `pydompekeygen.PyDompeKeys`
+
+```python
+class PyDompeKeys:
+    def __init__(self): ...
+    def GetFingerprint(self, mol: rdkit.Chem.Mol) -> rdkit.DataStructs.ExplicitBitVect: ...
+```
+
+The single entry point of the package. Instantiate once and reuse across molecules.
+
+### `PyDompeKeys()`
+
+Loads the DompéKeys SMARTS catalog into an [`rdkit.Chem.rdfiltercatalog.FilterCatalog`](https://www.rdkit.org/docs/source/rdkit.Chem.rdfiltercatalog.html).
+
+- On first run (or if no cache exists), the catalog is compiled from the bundled `smarts.txt` and pickled to `smarts.pkl` next to the installed package, together with the RDKit version used to build it.
+- On subsequent runs, the cache is loaded directly. If the installed RDKit version differs from the one recorded in the cache, the catalog is silently recompiled and re-cached — this keeps SMARTS matching behavior consistent with the RDKit version actually in use.
+
+Takes no arguments.
+
+#### Attributes
+
+| Attribute | Type | Description |
+|---|---|---|
+| `library` | `rdkit.Chem.rdfiltercatalog.FilterCatalog` | The compiled catalog of DompéKey SMARTS filters. Each entry's description is a `"{index}\|{key_id}\|{name}\|{smarts}\|level{level}"` string, where `index` is the fingerprint bit position and `key_id` is the `DK#` identifier from `smarts.txt`. Query it directly (e.g. via `.GetMatches(mol)`) to introspect which named keys matched — see [docs/usage.md](usage.md#inspecting-which-keys-matched). |
+| `num_bits` | `int` | Total number of DompéKeys / fingerprint length (1,064 with the bundled `smarts.txt`). |
+
+### `GetFingerprint(mol)`
+
+```python
+GetFingerprint(mol: rdkit.Chem.Mol) -> rdkit.DataStructs.ExplicitBitVect
+```
+
+Generates the DompéKey fingerprint for a molecule.
+
+**Parameters**
+
+- `mol` — an `rdkit.Chem.Mol` instance (e.g. from `Chem.MolFromSmiles`, `Chem.MolFromMolFile`, etc.). Must not be `None`.
+
+**Returns**
+
+An `rdkit.DataStructs.ExplicitBitVect` of length `num_bits`. Bit `i` is set if the molecule matches the SMARTS pattern of the DompéKey at index `i` in `library`. Compatible with all RDKit similarity metrics (`DataStructs.TanimotoSimilarity`, `DataStructs.BulkTanimotoSimilarity`, etc.) and `DataStructs.ConvertToNumpyArray`.
+
+**Example**
+
+```python
+from rdkit import Chem
+from pydompekeygen import PyDompeKeys
+
+dompekeys = PyDompeKeys()
+mol = Chem.MolFromSmiles("c1ccccc1O")  # phenol
+fp = dompekeys.GetFingerprint(mol)
+```
+
+## Module data
+
+The `smarts.txt` file bundled with the package is a tab-separated table with one DompéKey per row:
+
+| Column | Description |
+|---|---|
+| `Index` | Human-readable key identifier (e.g. `DK1`) |
+| `Chemical_Name` | Descriptive name of the substructure |
+| `DompeKeys` | The SMARTS pattern |
+| `Level` | Complexity level, `0`–`4` (see [docs/background.md](background.md)) |
+
+This file is the single source of truth for the fingerprint definition — regenerating `smarts.pkl` (by deleting it, or on an RDKit version bump) always reflects the current contents of `smarts.txt`.

pydompekeygen-1.0.0/docs/background.md

@@ -0,0 +1,57 @@
+# Background
+
+## What are DompéKeys?
+
+**DompéKeys** are a set of substructure-based descriptors developed by researchers at [Dompé farmaceutici](https://www.dompe.com/) as part of their [EXSCALATE](https://exscalate.eu/) drug-discovery platform, and published in the *Journal of Cheminformatics*:
+
+> Manelfi, C., Tazzari, V., Lunghini, F., Cerchia, C., Fava, A., Pedretti, A., Stouten, P. F. W., Vistoli, G., & Beccari, A. R. (2024). "DompeKeys": a set of novel substructure-based descriptors for efficient chemical space mapping, development and structural interpretation of machine learning models, and indexing of large databases. *Journal of Cheminformatics*, 16, 21. https://doi.org/10.1186/s13321-024-00813-4
+
+The original protocol and reference implementation are also available at [dompekeys.exscalate.eu](https://dompekeys.exscalate.eu).
+
+DompéKeys encode 1,064 curated SMARTS patterns covering chemical features relevant to pharmaceutical compounds — from precisely defined structural moieties (natural amino acids, metal-chelating groups, known toxicophores/structural alerts) to more generic pharmacophoric features (hydrogen-bond donors/acceptors, ring systems, charged groups). Unlike fingerprints generated by exhaustive substructure enumeration (e.g. Morgan/ECFP), every bit in a DompéKeys fingerprint corresponds to a *named, medicinal-chemistry-relevant* fragment, which makes the fingerprint directly interpretable: a set bit can be read and explained by a chemist, not just used as an opaque ML feature.
+
+This makes DompéKeys well suited to:
+
+- **Chemical space mapping** and diversity analysis of large compound collections
+- **Interpretable machine learning** — explaining *why* a model made a prediction in terms of concrete substructures
+- **Indexing very large databases** for fast substructure-aware similarity search
+
+## The five complexity levels
+
+Each DompéKey is tagged with a `Level` from 0 to 4, reflecting how specific vs. generic the encoded pattern is — from well-defined structural moieties toward broad pharmacophoric features. The bundled catalog (`smarts.txt`) breaks down as follows:
+
+| Level | # Keys |
+|---|---|
+| 0 | 265 |
+| 1 | 66 |
+| 2 | 617 |
+| 3 | 72 |
+| 4 | 44 |
+| **Total** | **1,064** |
+
+The level for each key is included in its `FilterCatalogEntry` description (see [docs/api.md](api.md)), so fingerprints can be filtered or interpreted level-by-level if your application needs it.
+
+## PyDompeKeyGen vs. the original protocol
+
+PyDompeKeyGen is an independent, minimal Python/RDKit implementation that reproduces the DompéKeys fingerprint from the published SMARTS definitions. It does not implement the full EXSCALATE pipeline (e.g. Molecular Anatomy integration) — only fingerprint generation via `PyDompeKeys.GetFingerprint`. For the canonical reference implementation and any downstream tooling built around DompéKeys, see [dompekeys.exscalate.eu](https://dompekeys.exscalate.eu).
+
+## Citing this work
+
+If PyDompeKeyGen is useful in your research, please cite the original DompéKeys paper (not this package):
+
+```bibtex
+@article{Manelfi2024DompeKeys,
+  author  = {Manelfi, Candida and Tazzari, Valerio and Lunghini, Filippo and Cerchia, Carmen
+             and Fava, Anna and Pedretti, Alessandro and Stouten, Pieter F. W.
+             and Vistoli, Giulio and Beccari, Andrea Rosario},
+  title   = {"{DompeKeys}": a set of novel substructure-based descriptors for efficient
+             chemical space mapping, development and structural interpretation of machine
+             learning models, and indexing of large databases},
+  journal = {Journal of Cheminformatics},
+  year    = {2024},
+  volume  = {16},
+  number  = {1},
+  pages   = {21},
+  doi     = {10.1186/s13321-024-00813-4}
+}
+```

pydompekeygen-1.0.0/docs/usage.md

@@ -0,0 +1,93 @@
+# Usage guide
+
+This guide covers the practical patterns you'll need day to day: generating fingerprints, comparing molecules, converting to NumPy, batch processing, and inspecting *which* keys matched.
+
+## Generating a fingerprint
+
+```python
+from rdkit import Chem
+from pydompekeygen import PyDompeKeys
+
+dompekeys = PyDompeKeys()
+
+mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")  # aspirin
+fp = dompekeys.GetFingerprint(mol)
+```
+
+`GetFingerprint` returns an RDKit [`ExplicitBitVect`](https://www.rdkit.org/docs/source/rdkit.DataStructs.cDataStructs.html) of length `dompekeys.num_bits` (1,064 by default), with one bit per DompéKey. This is the same object type returned by RDKit's own fingerprinting functions, so it works with every RDKit similarity metric and bit-vector utility out of the box.
+
+Only create the `PyDompeKeys()` instance once and reuse it — building/loading the SMARTS catalog has a fixed one-time cost, but `GetFingerprint` itself is cheap per molecule.
+
+## Comparing molecules
+
+```python
+from rdkit import DataStructs
+
+mol_a = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")   # aspirin
+mol_b = Chem.MolFromSmiles("CC(=O)Nc1ccc(O)cc1")       # paracetamol
+
+fp_a = dompekeys.GetFingerprint(mol_a)
+fp_b = dompekeys.GetFingerprint(mol_b)
+
+similarity = DataStructs.TanimotoSimilarity(fp_a, fp_b)
+print(f"Tanimoto similarity: {similarity:.3f}")
+```
+
+Any RDKit bit-vector metric works the same way, e.g. `DataStructs.DiceSimilarity`, `DataStructs.CosineSimilarity`, or bulk variants like `DataStructs.BulkTanimotoSimilarity` for comparing one fingerprint against many.
+
+## Converting to NumPy
+
+```python
+import numpy as np
+from rdkit import DataStructs
+
+arr = np.zeros((dompekeys.num_bits,), dtype=int)
+DataStructs.ConvertToNumpyArray(fp, arr)
+```
+
+`arr` is now a plain 0/1 NumPy vector, ready to feed into scikit-learn, PyTorch, or any other ML stack.
+
+## Batch processing
+
+```python
+import pandas as pd
+from rdkit import Chem
+from pydompekeygen import PyDompeKeys
+
+dompekeys = PyDompeKeys()
+
+df = pd.DataFrame({"smiles": ["CCO", "c1ccccc1", "CC(=O)Oc1ccccc1C(=O)O"]})
+df["mol"] = df["smiles"].apply(Chem.MolFromSmiles)
+df["fingerprint"] = df["mol"].apply(dompekeys.GetFingerprint)
+```
+
+For large datasets, drop unparsable SMILES (`Chem.MolFromSmiles` returns `None` on failure) before calling `GetFingerprint`, since it expects a valid `rdkit.Chem.Mol`.
+
+## Inspecting which keys matched
+
+Each bit corresponds to a named substructure. To see which DompéKeys fired for a given molecule (instead of just the bit vector), query the underlying RDKit `FilterCatalog` directly:
+
+```python
+matches = dompekeys.library.GetMatches(mol)
+
+for entry in matches:
+    index, key_id, name, smarts, level = entry.GetDescription().split("|")
+    print(f"[bit {index}, {level}] {key_id} — {name}")
+```
+
+Example output for aspirin:
+
+```
+[bit 410, level2] DK415 — carboxylic acids (aromatic)
+[bit 429, level2] DK443 — esters (aliphatic) / (aromatic)
+[bit 958, level3] DK978 — carboxylic acids derivatives
+[bit 1061, level4] DK1081 — donor atoms for H-bonds (N and O)
+[bit 1062, level4] DK1082 — acceptor atoms for H-bonds (N,O,F)
+...
+```
+
+This is useful for explaining a model's prediction, debugging why two molecules are (dis)similar, or filtering the fingerprint down to a subset of complexity levels — see [docs/background.md](background.md) for what each level means.
+
+## Rebuilding the SMARTS catalog
+
+On first use, PyDompeKeyGen compiles `smarts.txt` into an RDKit `FilterCatalog` and caches it alongside the installed RDKit version in `smarts.pkl`. On every subsequent import it loads straight from that cache — unless your installed RDKit version has changed since the cache was built, in which case it transparently rebuilds it. You never need to manage this yourself.

pydompekeygen-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77.0.0", "setuptools_scm[toml]>=7.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pydompekeygen"
+dynamic = ["version"]
+description = "A Python implementation of DompéKeys"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["qsar", "cheminformatics", "fingerprint", "dompé"]
+authors = [{ name = "Olivier J. M. Béquignon", email = "olivier.bequignon.maintainer@gmail.com" }]
+maintainers = [{ name = "Olivier J. M. Béquignon", email = "olivier.bequignon.maintainer@gmail.com" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Chemistry",
+]
+
+dependencies = [
+    "rdkit",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "pydompekeygen.__version__"}
+
+[project.urls]
+homepage = "https://github.com/OlivierBeq/PyDompeKeyGen"
+repository = "https://github.com/OlivierBeq/PyDompeKeyGen"
+
+[tool.setuptools]
+include-package-data = true
+package-dir = { "" = "src" }

pydompekeygen-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pydompekeygen-1.0.0/src/pydompekeygen/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+
+from .core import PyDompeKeys
+
+__version__ = "1.0.0"