| Name | ChemInformant JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | None |
| Summary | A Python library for streamlined access to PubChem chemical data with caching, validation, ambiguity handling, and batch retrieval. |
| upload_time | 2025-07-17 01:38:01 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2024 Ang <ang@hezhiang.com>
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.
|
| keywords |
chemistry
cheminformatics
pubchem
api
compound
drug
cache
pydantic
batch
smiles
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ChemInformant <img src="https://raw.githubusercontent.com/HzaCode/ChemInformant/joss-review-response/images/logo.png" align="right" width="120px" />
[](https://pypi.org/project/ChemInformant/)[](https://pypi.org/project/ChemInformant/)
**ChemInformant** is a modern, workflow-centric **Python client** for the [PubChem](https://pubchem.ncbi.nlm.nih.gov/) database. It's designed to feel native and intuitive for researchers and data scientists working within the **Python data science ecosystem (e.g., Pandas, Jupyter)**.
It's built to be robust by default, with built-in request caching, smart rate limiting, and automatic retries to handle real-world network conditions.
---
### Key Features
* **Analysis-Ready Pandas Output:** The core API (`get_properties`) returns a clean Pandas DataFrame, eliminating data wrangling boilerplate and enabling immediate integration with the Python data science ecosystem.
* **Zero-Configuration Robustness:** Built-in, persistent caching, smart rate-limiting, and automatic retries for server errors are enabled by default to ensure your workflows run reliably.
* **A Dual API for Simplicity and Power:** Offers a clear `get_<property>()` convenience layer for quick lookups, backed by a powerful `get_properties` engine for high-performance batch operations.
* **Effortless Large-Scale Queries:** Transparently handles PubChem's `ListKey`-based pagination in the background, ensuring you retrieve complete result sets from large queries without manual intervention.
* **Guaranteed Data Integrity:** Employs Pydantic v2 models for rigorous, runtime data validation, preventing malformed or unexpected data from corrupting your analysis pipeline.
* **Modern and Actively Maintained:** Built on a contemporary tech stack for long-term stability and compatibility, providing a reliable alternative to older or less frequently updated libraries.
### Installation
Install the library from PyPI:
```bash
pip install ChemInformant
```
To include plotting capabilities for use with the tutorial, install the `[plot]` extra:
```bash
pip install "ChemInformant[plot]"
```
---
### Quick Start
Retrieve multiple properties for multiple compounds, directly into a Pandas DataFrame, in a single function call:
```python
import ChemInformant as ci
# 1. Define your identifiers
identifiers = ["aspirin", "caffeine", 1983] # 1983 is paracetamol's CID
# 2. Specify the properties you need
properties = ["molecular_weight", "xlogp", "cas"]
# 3. Call the core function
df = ci.get_properties(identifiers, properties)
# 4. Analyze your results!
print(df)
```
**Output:**
```
input_identifier cid status molecular_weight xlogp cas
0 aspirin 2244.0 OK 180.16 1.20 50-78-2
1 caffeine 2519.0 OK 194.19 -0.07 58-08-2
2 1983 1983.0 OK 151.16 0.51 103-90-2
```
<details>
<summary><b>➡️ Click to see Convenience API Cheatsheet</b></summary>
<br>
| Function | Description |
|----------------------------|-----------------------------------------------|
| `get_weight(id)` | Molecular weight *(float)* |
| `get_formula(id)` | Molecular formula *(str)* |
| `get_cas(id)` | CAS Registry Number *(str)* |
| `get_iupac_name(id)` | IUPAC name *(str)* |
| `get_canonical_smiles(id)` | Canonical SMILES with Canonical→Connectivity fallback *(str)* |
| `get_isomeric_smiles(id)` | Isomeric SMILES *(str)* |
| `get_xlogp(id)` | XLogP (calculated hydrophobicity) *(float)* |
| `get_synonyms(id)` | List of synonyms *(List[str])* |
| `get_compound(id)` | Full, validated **`Compound`** object (Pydantic v2 model) |
*All functions accept a **CID, name, or SMILES** and return `None`/`[]` on failure.*
</details>
---
### Documentation & Examples
This quick start only scratches the surface. For a deep dive, please see our detailed guides:
* **➡️ Interactive User Manual:** Our [**Jupyter Notebook Tutorial**](examples/ChemInformant_User_Manual_v1.0.ipynb)provides a complete, end-to-end walkthrough. **This is the best place to start.**
* **➡️ Performance Benchmarks:** You can review and run our [**Benchmark Script**](./benchmark.py) to see the performance advantages of batching and caching.
---
### Why ChemInformant?
ChemInformant's core mission is to serve as a high-performance data backbone for the Python cheminformatics ecosystem. By delivering clean, validated, and analysis-ready Pandas DataFrames, it enables researchers to effortlessly pipe PubChem data into powerful toolkits like RDKit, Scikit-learn, or custom machine learning models, transforming multi-step data acquisition and wrangling tasks into single, elegant lines of code.
A detailed comparison with other existing tools is provided in our JOSS paper.
### Contributing
Contributions are welcome! Please feel free to open an issue or submit a pull request.
### License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "ChemInformant",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "chemistry, cheminformatics, pubchem, api, compound, drug, cache, pydantic, batch, smiles",
"author": null,
"author_email": "Zhiang He <ang@hezhiang.com>",
"download_url": "https://files.pythonhosted.org/packages/9d/70/cf5371650b5700faa1ff48e4ab0849925df618e9a644118d11563a67eead/cheminformant-2.0.0.tar.gz",
"platform": null,
"description": "# ChemInformant <img src=\"https://raw.githubusercontent.com/HzaCode/ChemInformant/joss-review-response/images/logo.png\" align=\"right\" width=\"120px\" />\r\n\r\n\r\n\r\n\r\n[](https://pypi.org/project/ChemInformant/)[](https://pypi.org/project/ChemInformant/)\r\n\r\n\r\n\r\n**ChemInformant** is a modern, workflow-centric **Python client** for the [PubChem](https://pubchem.ncbi.nlm.nih.gov/) database. It's designed to feel native and intuitive for researchers and data scientists working within the **Python data science ecosystem (e.g., Pandas, Jupyter)**.\r\n\r\nIt's built to be robust by default, with built-in request caching, smart rate limiting, and automatic retries to handle real-world network conditions.\r\n\r\n---\r\n\r\n### Key Features\r\n\r\n* **Analysis-Ready Pandas Output:** The core API (`get_properties`) returns a clean Pandas DataFrame, eliminating data wrangling boilerplate and enabling immediate integration with the Python data science ecosystem.\r\n* **Zero-Configuration Robustness:** Built-in, persistent caching, smart rate-limiting, and automatic retries for server errors are enabled by default to ensure your workflows run reliably.\r\n* **A Dual API for Simplicity and Power:** Offers a clear `get_<property>()` convenience layer for quick lookups, backed by a powerful `get_properties` engine for high-performance batch operations.\r\n* **Effortless Large-Scale Queries:** Transparently handles PubChem's `ListKey`-based pagination in the background, ensuring you retrieve complete result sets from large queries without manual intervention.\r\n* **Guaranteed Data Integrity:** Employs Pydantic v2 models for rigorous, runtime data validation, preventing malformed or unexpected data from corrupting your analysis pipeline.\r\n* **Modern and Actively Maintained:** Built on a contemporary tech stack for long-term stability and compatibility, providing a reliable alternative to older or less frequently updated libraries.\r\n### Installation\r\n\r\nInstall the library from PyPI:\r\n\r\n```bash\r\npip install ChemInformant\r\n```\r\n\r\nTo include plotting capabilities for use with the tutorial, install the `[plot]` extra:\r\n```bash\r\npip install \"ChemInformant[plot]\"\r\n```\r\n\r\n---\r\n\r\n### Quick Start\r\n\r\nRetrieve multiple properties for multiple compounds, directly into a Pandas DataFrame, in a single function call:\r\n\r\n```python\r\nimport ChemInformant as ci\r\n\r\n# 1. Define your identifiers\r\nidentifiers = [\"aspirin\", \"caffeine\", 1983] # 1983 is paracetamol's CID\r\n\r\n# 2. Specify the properties you need\r\nproperties = [\"molecular_weight\", \"xlogp\", \"cas\"]\r\n\r\n# 3. Call the core function\r\ndf = ci.get_properties(identifiers, properties)\r\n\r\n# 4. Analyze your results!\r\nprint(df)\r\n```\r\n\r\n**Output:**\r\n\r\n```\r\n input_identifier cid status molecular_weight xlogp cas\r\n0 aspirin 2244.0 OK 180.16 1.20 50-78-2\r\n1 caffeine 2519.0 OK 194.19 -0.07 58-08-2\r\n2 1983 1983.0 OK 151.16 0.51 103-90-2\r\n```\r\n\r\n<details>\r\n<summary><b>\u27a1\ufe0f Click to see Convenience API Cheatsheet</b></summary>\r\n<br>\r\n\r\n| Function | Description |\r\n|----------------------------|-----------------------------------------------|\r\n| `get_weight(id)` | Molecular weight *(float)* |\r\n| `get_formula(id)` | Molecular formula *(str)* |\r\n| `get_cas(id)` | CAS Registry Number *(str)* |\r\n| `get_iupac_name(id)` | IUPAC name *(str)* |\r\n| `get_canonical_smiles(id)` | Canonical SMILES with Canonical\u2192Connectivity fallback *(str)* |\r\n| `get_isomeric_smiles(id)` | Isomeric SMILES *(str)* |\r\n| `get_xlogp(id)` | XLogP (calculated hydrophobicity) *(float)* |\r\n| `get_synonyms(id)` | List of synonyms *(List[str])* |\r\n| `get_compound(id)` | Full, validated **`Compound`** object (Pydantic v2 model) |\r\n\r\n\r\n*All functions accept a **CID, name, or SMILES** and return `None`/`[]` on failure.*\r\n\r\n</details>\r\n\r\n---\r\n\r\n### Documentation & Examples\r\n\r\nThis quick start only scratches the surface. For a deep dive, please see our detailed guides:\r\n\r\n* **\u27a1\ufe0f Interactive User Manual:** Our [**Jupyter Notebook Tutorial**](examples/ChemInformant_User_Manual_v1.0.ipynb)provides a complete, end-to-end walkthrough. **This is the best place to start.**\r\n* **\u27a1\ufe0f Performance Benchmarks:** You can review and run our [**Benchmark Script**](./benchmark.py) to see the performance advantages of batching and caching.\r\n\r\n---\r\n\r\n### Why ChemInformant?\r\n\r\nChemInformant's core mission is to serve as a high-performance data backbone for the Python cheminformatics ecosystem. By delivering clean, validated, and analysis-ready Pandas DataFrames, it enables researchers to effortlessly pipe PubChem data into powerful toolkits like RDKit, Scikit-learn, or custom machine learning models, transforming multi-step data acquisition and wrangling tasks into single, elegant lines of code.\r\n\r\nA detailed comparison with other existing tools is provided in our JOSS paper.\r\n\r\n### Contributing\r\n\r\nContributions are welcome! Please feel free to open an issue or submit a pull request.\r\n\r\n### License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": "MIT License\r\n \r\n Copyright (c) 2024 Ang <ang@hezhiang.com>\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a copy\r\n of this software and associated documentation files (the \"Software\"), to deal\r\n in the Software without restriction, including without limitation the rights\r\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n copies of the Software, and to permit persons to whom the Software is\r\n furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in all\r\n copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n SOFTWARE.\r\n ",
"summary": "A Python library for streamlined access to PubChem chemical data with caching, validation, ambiguity handling, and batch retrieval.",
"version": "2.0.0",
"project_urls": {
"Documentation": "https://github.com/HzaCode/ChemInformant#readme",
"Homepage": "https://github.com/HzaCode/ChemInformant",
"Issues": "https://github.com/HzaCode/ChemInformant/issues"
},
"split_keywords": [
"chemistry",
" cheminformatics",
" pubchem",
" api",
" compound",
" drug",
" cache",
" pydantic",
" batch",
" smiles"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "896197ebc1cfb50437123ea1b85637546aeb8a83d7b38d159d293d089e85a093",
"md5": "e0ba0c0e0ab1882ca722c3c0437bfa6f",
"sha256": "39382307ea9a1619955a769280f7c54603a71ab3e299722c7b9bc3ad02f5f0be"
},
"downloads": -1,
"filename": "cheminformant-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0ba0c0e0ab1882ca722c3c0437bfa6f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11119,
"upload_time": "2025-07-17T01:37:59",
"upload_time_iso_8601": "2025-07-17T01:37:59.680531Z",
"url": "https://files.pythonhosted.org/packages/89/61/97ebc1cfb50437123ea1b85637546aeb8a83d7b38d159d293d089e85a093/cheminformant-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9d70cf5371650b5700faa1ff48e4ab0849925df618e9a644118d11563a67eead",
"md5": "f93ec95fbeb97e180ed757340a263ef5",
"sha256": "8e4ee7b19bf7ed2a864f8b8e08a6fa71ed575b1c6149ddad7e82cd7f5192e490"
},
"downloads": -1,
"filename": "cheminformant-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "f93ec95fbeb97e180ed757340a263ef5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15264,
"upload_time": "2025-07-17T01:38:01",
"upload_time_iso_8601": "2025-07-17T01:38:01.032161Z",
"url": "https://files.pythonhosted.org/packages/9d/70/cf5371650b5700faa1ff48e4ab0849925df618e9a644118d11563a67eead/cheminformant-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 01:38:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HzaCode",
"github_project": "ChemInformant#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cheminformant"
}
