harmonsmile 0.1.1__tar.gz

harmonsmile-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - "dev-v*"
+      - "release/*"
+
+jobs:
+  test-build-smoke:
+    name: Test, build, and smoke install
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package and validation tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "setuptools>=68" wheel
+          python -m pip install -e ".[dev]" build twine
+
+      - name: Run tests
+        run: python -m pytest tests -p no:cacheprovider --basetemp .pytest_tmp
+
+      - name: Check CLI version
+        run: harmonsmile --version
+
+      - name: Check public import boundary
+        run: python -c "import harmonsmile; print(harmonsmile.__version__, harmonsmile.__all__, hasattr(harmonsmile, 'RDKitStandardizer'))"
+
+      - name: Build distributions
+        run: python -m build 
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Smoke install built wheel
+        shell: bash
+        run: |
+          set -euo pipefail
+          WHEEL="$(ls dist/*.whl | head -n 1)"
+          python -m venv .smoke_venv
+          .smoke_venv/bin/python -m pip install --upgrade pip
+          .smoke_venv/bin/python -m pip install "$WHEEL"
+          mkdir -p .smoke_outside_checkout
+          cd .smoke_outside_checkout
+          ../.smoke_venv/bin/harmonsmile --version
+          ../.smoke_venv/bin/python -c "import harmonsmile; print(harmonsmile.__version__, harmonsmile.__all__, hasattr(harmonsmile, 'RDKitStandardizer'))"

harmonsmile-0.1.1/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,91 @@
+name: Publish Python package to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to publish, for example v0.1.0"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out release tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+          persist-credentials: false
+
+      - name: Validate release tag
+        run: |
+          case "${{ inputs.tag }}" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *)
+              echo "Input tag must look like vX.Y.Z, for example v0.1.1"
+              exit 1
+              ;;
+          esac
+
+          git fetch --tags --force
+          git rev-parse -q --verify "refs/tags/${{ inputs.tag }}" >/dev/null
+
+      - name: Verify package version matches tag
+        run: |
+          expected="${{ inputs.tag }}"
+          expected="${expected#v}"
+          actual="$(python -c "import runpy; print(runpy.run_path('harmonsmile/version.py')['__version__'])")"
+
+          if [ "$actual" != "$expected" ]; then
+            echo "Package version $actual does not match tag ${{ inputs.tag }}"
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish distribution to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/harmonsmile
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

harmonsmile-0.1.1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Environments
+.venv/
+.env
+
+# Local data and outputs
+data/*
+results/*
+logs/*
+
+# Keep folders empty
+!data/.gitkeep
+!results/.gitkeep
+!logs/.gitkeep
+
+# Distribution and build files
+dist/
+*.egg-info/
+build/
+__pycache__/
+*.pyc
+.pytest_tmp/
+.pytest_cache/
+tests_output.txt

harmonsmile-0.1.1/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}

harmonsmile-0.1.1/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.1.1] - 2026-05-18
+
+### Added
+- `RDKitStandardizer` class with two SMILES normalization methods:
+  - `to_iso_kek()` — canonical + isomeric + Kekulized SMILES (COCONUT 2.0 convention)
+  - `to_conn_kek()` — canonical + connectivity-only + Kekulized SMILES
+- `PubChemIngest` pipeline: fetches all available properties from PubChem REST API
+  (SMILES, ConnectivitySMILES, MolecularWeight, MolecularFormula, InChI, InChIKey,
+  XLogP, TPSA, Charge, HBondDonorCount, HBondAcceptorCount, RotatableBondCount,
+  HeavyAtomCount) and appends standardized `SMILES_RDKit` column.
+- `ChEMBLIngest` pipeline: fetches properties from ChEMBL REST API by ChEMBL ID
+  (canonical_smiles, InChI, InChIKey, MW, MolecularFormula, ALogP, TPSA, HBA, HBD,
+  RotatableBonds, HeavyAtoms, QED, Ro5Violations) and appends standardized `SMILES_RDKit` column.
+- `SMILESPrep` pipeline: standardizes SMILES from any CSV/Excel file using RDKit —
+  accepts any tabular source (COCONUT, ChEMBL downloads, in-house databases, etc.).
+- `_PubChemClient` with configurable retries, exponential backoff, persistent
+  `requests.Session`, context manager protocol, and pluggable logger.
+- `_ChEMBLClient` with same design as `_PubChemClient` — ChEMBL ID format validation,
+  exponential backoff, context manager protocol.
+- `Config` frozen dataclass for pipeline configuration with `__post_init__` validation.
+- `load_table()` and `save_table()` I/O utilities supporting CSV, TSV, XLSX, and XLS
+  formats, with `PathLike` support.
+- `version.py` as single source of truth for package metadata (`__version__`,
+  `PROJECT_NAME`, `PROJECT_VERSION`, `PROJECT_STATUS`).
+- Command-line interface via `harmonsmile` entry point and `python -m harmonsmile`,
+  with paired argument validation, grouped help output, and `--version` flag.
+- `pyproject.toml` for PyPI packaging (build backend: hatchling).
+- SPDX license headers (`LGPL-3.0-or-later`) in all source files.
+- NumPy-style docstrings with Examples in all public modules and classes.
+- `CITATION.cff` for software citation.
+- `CHANGELOG.md` following Keep a Changelog format.
+- `environment.yml` and `requirements-dev.txt` for reproducible environments.
+- Unit test suite with pytest covering standardize, config, io,
+  pubchem, chembl, and security.
+
+### Security
+- `_PubChemClient`: bounds validation on `sleep` (0.1–10.0 s) and `retries` (1–10).
+- `_PubChemClient.fetch_props()`: CID sanitization strips non-numeric characters
+  before URL construction.
+- `_ChEMBLClient`: same bounds validation; ChEMBL ID format validated against
+  `^CHEMBL\d+$` regex before network calls.
+- `Config`: path traversal guard rejects `output_path` containing `..`.
+- `Config`: `VALID_PUBCHEM_PROPS` allowlist validates requested PubChem properties.
+
+### Changed
+- License changed from MIT to GNU Lesser General Public License v3.0 or later
+  (LGPL-3.0-or-later).
+- `__main__.py` now delegates to `harmonsmile._cli` instead of `cli.harmonize`,
+  making the package self-contained and installable from PyPI.
+- Console status messages changed to English for international audience.
+- `Config` is now immutable (`frozen=True`).
+- `CoconutPrep` renamed to `SMILESPrep` to reflect its universal scope. `CoconutPrep`
+  remains available as a deprecated alias and will be removed in a future release.
+- `PubChemClient` renamed to `_PubChemClient` (private) to prevent direct use that
+  could abuse the PubChem REST API. `PubChemClient` remains available as a deprecated
+  alias and will be removed in a future release.
+- Default `props` in `Config` expanded to include all available PubChem properties.
+- Development status set to Alpha (`3 - Alpha`) reflecting first public release.
+
+### Fixed
+- Double `time.sleep()` call in `_PubChemClient.fetch_props()` that caused unnecessary
+  delays on successful requests.
+- Missing column validation in `PubChemIngest.run()` before initiating network calls.
+- Incorrect guard condition for `SMILES_RDKit` counter in `PubChemIngest.run()`.
+- Unguarded `Chem.MolToSmiles()` call in `RDKitStandardizer` that could raise unhandled
+  C++ exceptions for unusual aromaticity models.
+- Fallback encoding in `load_table()` changed to `latin-1` to correctly handle
+  non-UTF-8 encoded files.
+
+### Removed
+- Redundant `cli/` scripts (`harmonize.py`, `ingest_pubchem.py`, `prep_coconut.py`)
+  superseded by the unified `harmonsmile` entry point.
+- Unused `id_col` field from `Config` dataclass.
+
+---
+
+## Future Releases (Planned)
+
+### [0.2.0] — COCONUT source
+- Add `CoconutIngest` pipeline — knows COCONUT 2.0 schema automatically
+  (`canonical_smiles` column, `identifier`, molecular properties).
+- Optional COCONUT REST API integration (authenticated).
+
+### [0.3.0] — ML-ready features
+- Standardized pipeline to generate ECFP fingerprints (with/without chirality).
+- InChI / InChIKey generation for deduplication and robust cross-database matching.
+
+---
+
+[Unreleased]: https://github.com/NanoBiostructuresRG/harmonsmile/compare/v0.1.0...HEAD
+[0.1.1]: https://github.com/NanoBiostructuresRG/harmonsmile/releases/tag/v0.1.1
+[0.1.0]: https://github.com/NanoBiostructuresRG/harmonsmile/releases/tag/v0.1.0

harmonsmile-0.1.1/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "HARMONSMILE: Harmonize SMILES Strings for Cheminformatics and Machine Learning"
+version: "0.1.1"
+date-released: "2026-05-18"
+authors:
+  - family-names: "Contreras-Torres"
+    given-names: "Flavio F."
+    orcid: "https://orcid.org/0000-0003-2375-131X"
+    affiliation: "Tecnologico de Monterrey"
+repository-code: "https://github.com/NanoBiostructuresRG/harmonsmile"
+license: "LGPL-3.0-or-later"
+abstract: >-
+  HARMONSMILE is a toolkit for harmonizing SMILES strings to a consistent
+  convention: canonical + isomeric + Kekulized, as used by RDKit and COCONUT 2.0.
+  It automates the preparation of SMILES for cheminformatics workflows and
+  machine learning applications within the computational drug discovery pipeline,
+  enabling standardized comparison across PubChem, COCONUT, and independent
+  molecular databases.
+keywords:
+  - cheminformatics
+  - SMILES
+  - SMILES standardization
+  - RDKit
+  - COCONUT
+  - PubChem
+  - drug discovery
+  - molecular datasets