# mofdb-client
A typed, fast, lightweight, client wrapping the [mofdb api](https://mof.tech.northwestern.edu/api). This client is the fastest way to access
mofdb since it utilizes the streaming bulk API. Using the regular paginated API will be slow for large page numbers.
### Installation
```shell
python3 -m pip install mofdb_client==0.9.0
```
### Example
```python3
from mofdb_client import fetch
for mof in fetch(vf_min=0.5, vf_max=0.99):
print(f"Mof {mof.name} has {len(mof.isotherms)} isotherms and elements {[str(e) for e in mof.elements]}")
print(f"This mof's cif file starts with: '{mof.cif.splitlines()[1]}'")
```
```
Mof UTEWUM_clean has 2 isotherms and elements ['Cu', 'H', 'C', 'N']
This mof's cif file starts with: '_audit_creation_date 2014-07-02'
Mof ZECKID_clean has 1 isotherms and elements ['Cu', 'H', 'C', 'N', 'O']
This mof's cif file starts with: '_audit_creation_date 2014-07-02'
Mof AQOMAW_clean has 2 isotherms and elements ['N', 'C', 'H', 'Co', 'Cl', 'O']
This mof's cif file starts with: '_cell_length_a 18.8345'
Mof AQOLOJ_clean has 2 isotherms and elements ['N', 'C', 'H', 'Co', 'Cl']
This mof's cif file starts with: '_cell_length_a 18.794'
Mof SENWOZ_clean has 2 isotherms and elements ['Zn', 'H', 'C', 'O']
This mof's cif file starts with: '_audit_creation_date 2014-07-02'
Mof IYUCIQ_clean has 2 isotherms and elements ['Dy', 'O', 'N', 'C', 'H']
This mof's cif file starts with: '_cell_length_a 29.162'
Mof ORUKET_clean has 2 isotherms and elements ['P', 'O', 'N', 'C', 'H', 'Mg']
This mof's cif file starts with: '_cell_length_a 18.571'
...
```
### Parameters
*fetch* supports a number of arguments
- name: str
- pressure_unit: str
- loading_unit: str
- mofid: str
- mofkey: str
- vf_min: float
- vf_max: float
- lcd_min: float
- lcd_max: float
- pld_min: float
- pld_max: float
- sa_m2g_min: float
- sa_m2g_max: float
- sa_m2cm3_min: float
- sa_m2cm3_max: float
- database: str
- limit: int
- telemetry: bool default true (see telemetry section)
For valid values of pressure_units go here [mof.tech.northwestern.edu/classifications.json](https://mof.tech.northwestern.edu/classifications.json). The mofdb_client will reject invalid
units/pressures and throw `InvalidUnit` exception.
### Design Note
`fetch` is lazy because mofDB is large. Be sure to loop over it with `for mof in fetch()` and NOT `for mof in list(fetch())` since
building the list will download all the mofs before it starts processing and this will be very slow and may well run out of memory.
### Compatibility
[Tested](https://app.travis-ci.com/github/n8ta/mofdb-client) on Python 3.7 to 3.11.
### Future Enhancements:
- [ ] Retries for transient network failures with exponential backoff
- [X] Support for unit conversions
- [ ] Only download some columns to save time/bandwidth?
### Telemetry
This package may phone home crash reports that happen in library code when the telemetry arg is true. This is done using
[sentry](https://docs.sentry.io/). Nothing in addition to fetch params and data captured by default by sentry is ever
captured.
For example this could include:
- a stack trace including your code
- operating system version
- time
- python runtime version
- hostname
- anything else sentry captures by default
### Publishing a new version
Update pyproject.toml version
```
python3 -m build -n
python3 -m twine upload dist/*
```
### Change log
#### 0.9.0
Do not report mofdb exceptions like "InvalidUnit" to sentry error monitoring. These indicate user error.
#### 0.8.0
Fix for crashes on queries returning no mofs. Required a change to mofdb repo as well. Add a 204.response file to zip stream to signal empty response.
Raw data
{
"_id": null,
"home_page": "https://github.com/n8ta/mofdb-client",
"name": "mofdb-client",
"maintainer": "Nathaniel Tracy-Amoroso",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "n8@u.northwestern.edu",
"keywords": "mofdb,client,metal organic frameworks,chemistry",
"author": "Nathaniel Tracy-Amoroso",
"author_email": "n8@u.northwestern.edu",
"download_url": "https://files.pythonhosted.org/packages/eb/e7/5fe09c82535bbb6fc4fd94cab167dd66fdd05e8ea0300cc671765b7b23b0/mofdb_client-0.10.0.tar.gz",
"platform": null,
"description": "# mofdb-client\n\n\nA typed, fast, lightweight, client wrapping the [mofdb api](https://mof.tech.northwestern.edu/api). This client is the fastest way to access\nmofdb since it utilizes the streaming bulk API. Using the regular paginated API will be slow for large page numbers.\n\n### Installation\n\n```shell\npython3 -m pip install mofdb_client==0.9.0\n```\n\n### Example\n\n\n\n```python3\nfrom mofdb_client import fetch\nfor mof in fetch(vf_min=0.5, vf_max=0.99):\n print(f\"Mof {mof.name} has {len(mof.isotherms)} isotherms and elements {[str(e) for e in mof.elements]}\")\n print(f\"This mof's cif file starts with: '{mof.cif.splitlines()[1]}'\")\n```\n\n```\nMof UTEWUM_clean has 2 isotherms and elements ['Cu', 'H', 'C', 'N']\nThis mof's cif file starts with: '_audit_creation_date 2014-07-02'\nMof ZECKID_clean has 1 isotherms and elements ['Cu', 'H', 'C', 'N', 'O']\nThis mof's cif file starts with: '_audit_creation_date 2014-07-02'\nMof AQOMAW_clean has 2 isotherms and elements ['N', 'C', 'H', 'Co', 'Cl', 'O']\nThis mof's cif file starts with: '_cell_length_a 18.8345'\nMof AQOLOJ_clean has 2 isotherms and elements ['N', 'C', 'H', 'Co', 'Cl']\nThis mof's cif file starts with: '_cell_length_a 18.794'\nMof SENWOZ_clean has 2 isotherms and elements ['Zn', 'H', 'C', 'O']\nThis mof's cif file starts with: '_audit_creation_date 2014-07-02'\nMof IYUCIQ_clean has 2 isotherms and elements ['Dy', 'O', 'N', 'C', 'H']\nThis mof's cif file starts with: '_cell_length_a 29.162'\nMof ORUKET_clean has 2 isotherms and elements ['P', 'O', 'N', 'C', 'H', 'Mg']\nThis mof's cif file starts with: '_cell_length_a 18.571'\n...\n```\n\n### Parameters\n*fetch* supports a number of arguments\n- name: str\n- pressure_unit: str\n- loading_unit: str\n- mofid: str \n- mofkey: str \n- vf_min: float \n- vf_max: float \n- lcd_min: float \n- lcd_max: float \n- pld_min: float \n- pld_max: float \n- sa_m2g_min: float \n- sa_m2g_max: float \n- sa_m2cm3_min: float \n- sa_m2cm3_max: float \n- database: str\n- limit: int\n- telemetry: bool default true (see telemetry section)\n\nFor valid values of pressure_units go here [mof.tech.northwestern.edu/classifications.json](https://mof.tech.northwestern.edu/classifications.json). The mofdb_client will reject invalid\nunits/pressures and throw `InvalidUnit` exception.\n\n### Design Note\n`fetch` is lazy because mofDB is large. Be sure to loop over it with `for mof in fetch()` and NOT `for mof in list(fetch())` since \nbuilding the list will download all the mofs before it starts processing and this will be very slow and may well run out of memory.\n\n### Compatibility\n[Tested](https://app.travis-ci.com/github/n8ta/mofdb-client) on Python 3.7 to 3.11. \n\n### Future Enhancements:\n- [ ] Retries for transient network failures with exponential backoff\n- [X] Support for unit conversions\n- [ ] Only download some columns to save time/bandwidth?\n\n### Telemetry\nThis package may phone home crash reports that happen in library code when the telemetry arg is true. This is done using \n[sentry](https://docs.sentry.io/). Nothing in addition to fetch params and data captured by default by sentry is ever\ncaptured.\n\nFor example this could include:\n- a stack trace including your code\n- operating system version\n- time\n- python runtime version\n- hostname\n- anything else sentry captures by default\n\n### Publishing a new version\nUpdate pyproject.toml version\n\n```\npython3 -m build -n\npython3 -m twine upload dist/*\n```\n\n### Change log\n\n\n#### 0.9.0\nDo not report mofdb exceptions like \"InvalidUnit\" to sentry error monitoring. These indicate user error.\n\n#### 0.8.0\nFix for crashes on queries returning no mofs. Required a change to mofdb repo as well. Add a 204.response file to zip stream to signal empty response.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Simple client for fetching data from mofdb",
"version": "0.10.0",
"split_keywords": [
"mofdb",
"client",
"metal organic frameworks",
"chemistry"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "00ac2e96216f903a5c9905cd1126b705df57800b4de2efc2c1e6bed62d5e2410",
"md5": "fac5fe1afdbd4e135a39aa3d41939954",
"sha256": "295671f873d4f78e82e77d152110a95a765d6f4f1fd4c14bac59296d2e70c85f"
},
"downloads": -1,
"filename": "mofdb_client-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fac5fe1afdbd4e135a39aa3d41939954",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8736,
"upload_time": "2023-04-10T01:11:26",
"upload_time_iso_8601": "2023-04-10T01:11:26.642344Z",
"url": "https://files.pythonhosted.org/packages/00/ac/2e96216f903a5c9905cd1126b705df57800b4de2efc2c1e6bed62d5e2410/mofdb_client-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ebe75fe09c82535bbb6fc4fd94cab167dd66fdd05e8ea0300cc671765b7b23b0",
"md5": "0562a23b109ab650785583f93c9181aa",
"sha256": "46c52b41ab514390577d92c7d0c9bdb0f3fcd3be129db7f8415a7b94f7397772"
},
"downloads": -1,
"filename": "mofdb_client-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "0562a23b109ab650785583f93c9181aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8882,
"upload_time": "2023-04-10T01:11:35",
"upload_time_iso_8601": "2023-04-10T01:11:35.485201Z",
"url": "https://files.pythonhosted.org/packages/eb/e7/5fe09c82535bbb6fc4fd94cab167dd66fdd05e8ea0300cc671765b7b23b0/mofdb_client-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-10 01:11:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "n8ta",
"github_project": "mofdb-client",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "mofdb-client"
}
JSON
