pdfdata-api 0.2.0__tar.gz

pdfdata_api-0.2.0/LICENSE.txt

@@ -0,0 +1,31 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, yanglonggroup
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+For more information please email Prof. Long Yang at long_yang@tongji.edu.cn

pdfdata_api-0.2.0/PDFData_API.py

@@ -0,0 +1,4 @@
+"""Compatibility import for pre-0.2 source users."""
+from pdfdata_api import MaterialsAPI, PDFData_API, __version__
+
+__all__ = ["PDFData_API", "MaterialsAPI", "__version__"]

pdfdata_api-0.2.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: pdfdata-api
+Version: 0.2.0
+Summary: Python client for the PDFData materials database API
+Author-email: PDF Database Team <contact@pdfdata.org>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://pdfdata.org
+Project-URL: Documentation, https://pdfdata.org/documents/api
+Project-URL: Source, https://github.com/yanglonggroup/pdfDBflask
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# PDFData Python client
+
+Standalone client for `https://pdfdata.org/api/v1`. Requires Python 3.9+ and
+`requests`; Flask, MongoDB and scientific packages are not client dependencies.
+Version 0.2.0 source and build configuration are in this repository. A public
+PyPI release has not been made as part of this change.
+
+Install from a local checkout (repository root):
+
+```sh
+python -m pip install ./src/pdfdb_backend
+```
+
+Or install the built wheel supplied with a release:
+
+```sh
+python -m pip install /path/to/pdfdata_api-0.2.0-py3-none-any.whl
+```
+
+Generate a key on the website's API page after signing in. Set it in an
+environment variable and query:
+
+```python
+import os
+from pdfdata_api import PDFData_API
+
+with PDFData_API(api_key=os.environ["PDFDATA_API_KEY"]) as client:
+    page = client.get_materials(elements="Si,O", per_page=20)
+    material = client.get_material("mp-10009-X")
+    curve = client.get_pdf_data("mp-10009-X")
+    all_matches = client.get_all_materials(elements="Si,O")
+```
+
+`get_materials()` and `search()` return one page by default. Page size is 1–100.
+`get_all_materials()` and `search_all()` collect successive pages. Legacy client
+calls with `per_page=0` also collect successive pages; direct HTTP requests must
+use page sizes 1–100. Collection is not a database snapshot while data changes.
+
+Advanced search:
+
+```python
+result = client.search({
+    "elements": {"all": ["Si"], "none": ["Au"]},
+    "qmax": "[10,30]",
+    "page": 1,
+    "per_page": 20,
+})
+```
+
+For applications already holding a website **access JWT**, `PDFData_API()` can
+call `generate_api_key(jwt_token)`, `get_api_keys(jwt_token)` and
+`delete_api_key(jwt_token, "Key 1")`. The generated key is set on the client.
+Key management requires the login JWT; material queries require the API key.
+`generate_api_key` creates a new key on each call and is not automatically retried.
+
+`MaterialsAPI` remains an alias of `PDFData_API`. The old import
+`from PDFData_API import PDFData_API` remains supported. Backend source imports
+`from app.api.client import MaterialsAPI` forward to the same implementation.
+The default timeout is 30 seconds and can be set with `timeout=60`. HTTP errors
+raise `requests.HTTPError`; inspect `exc.response.status_code` and JSON `code`.
+
+Build from this directory:
+
+```sh
+python -m build
+```
+
+Only `pdfdata_api` and the legacy `PDFData_API` module are included in the
+distribution. Production environment files and backend code are excluded.

pdfdata_api-0.2.0/README.md

@@ -0,0 +1,69 @@
+# PDFData Python client
+
+Standalone client for `https://pdfdata.org/api/v1`. Requires Python 3.9+ and
+`requests`; Flask, MongoDB and scientific packages are not client dependencies.
+Version 0.2.0 source and build configuration are in this repository. A public
+PyPI release has not been made as part of this change.
+
+Install from a local checkout (repository root):
+
+```sh
+python -m pip install ./src/pdfdb_backend
+```
+
+Or install the built wheel supplied with a release:
+
+```sh
+python -m pip install /path/to/pdfdata_api-0.2.0-py3-none-any.whl
+```
+
+Generate a key on the website's API page after signing in. Set it in an
+environment variable and query:
+
+```python
+import os
+from pdfdata_api import PDFData_API
+
+with PDFData_API(api_key=os.environ["PDFDATA_API_KEY"]) as client:
+    page = client.get_materials(elements="Si,O", per_page=20)
+    material = client.get_material("mp-10009-X")
+    curve = client.get_pdf_data("mp-10009-X")
+    all_matches = client.get_all_materials(elements="Si,O")
+```
+
+`get_materials()` and `search()` return one page by default. Page size is 1–100.
+`get_all_materials()` and `search_all()` collect successive pages. Legacy client
+calls with `per_page=0` also collect successive pages; direct HTTP requests must
+use page sizes 1–100. Collection is not a database snapshot while data changes.
+
+Advanced search:
+
+```python
+result = client.search({
+    "elements": {"all": ["Si"], "none": ["Au"]},
+    "qmax": "[10,30]",
+    "page": 1,
+    "per_page": 20,
+})
+```
+
+For applications already holding a website **access JWT**, `PDFData_API()` can
+call `generate_api_key(jwt_token)`, `get_api_keys(jwt_token)` and
+`delete_api_key(jwt_token, "Key 1")`. The generated key is set on the client.
+Key management requires the login JWT; material queries require the API key.
+`generate_api_key` creates a new key on each call and is not automatically retried.
+
+`MaterialsAPI` remains an alias of `PDFData_API`. The old import
+`from PDFData_API import PDFData_API` remains supported. Backend source imports
+`from app.api.client import MaterialsAPI` forward to the same implementation.
+The default timeout is 30 seconds and can be set with `timeout=60`. HTTP errors
+raise `requests.HTTPError`; inspect `exc.response.status_code` and JSON `code`.
+
+Build from this directory:
+
+```sh
+python -m build
+```
+
+Only `pdfdata_api` and the legacy `PDFData_API` module are included in the
+distribution. Production environment files and backend code are excluded.

pdfdata_api-0.2.0/pdfdata_api/__init__.py

@@ -0,0 +1,5 @@
+"""Standalone PDFData client; no Flask, MongoDB or scientific dependencies."""
+
+from .client import MaterialsAPI, PDFData_API, __version__
+
+__all__ = ["PDFData_API", "MaterialsAPI", "__version__"]

pdfdata_api-0.2.0/pdfdata_api/client.py

@@ -0,0 +1,143 @@
+"""One implementation for the public client and legacy import paths."""
+
+from copy import deepcopy
+import math
+from urllib.parse import urlsplit
+
+import requests
+
+
+__version__ = "0.2.0"
+DEFAULT_BASE_URL = "https://pdfdata.org/api/v1"
+
+
+class PDFData_API:
+    """Query public materials with an API key; manage keys with a login JWT."""
+
+    def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, *, timeout=30, session=None):
+        parsed = urlsplit(base_url)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.query or parsed.fragment:
+            raise ValueError("base_url must be an HTTP(S) API URL without a query or fragment")
+        if parsed.username or parsed.password:
+            raise ValueError("base_url must not contain credentials")
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be a positive, finite number of seconds")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session if session is not None else requests.Session()
+        self.api_key = api_key
+        self.headers = {"Content-Type": "application/json",
+                        "User-Agent": f"PDFData-Python-Client/{__version__}"}
+        if api_key is not None:
+            self._key(api_key)
+            self.headers["Authorization"] = f"Bearer {api_key}"
+
+    @staticmethod
+    def _key(value):
+        if not isinstance(value, str) or not value or len(value) > 512 or any(c.isspace() for c in value):
+            raise ValueError("A non-empty API key is required")
+        return value
+
+    def _request(self, method, path, *, params=None, body=None, jwt_token=None):
+        headers = dict(self.headers)
+        if jwt_token is not None:
+            if not isinstance(jwt_token, str) or not jwt_token or any(c.isspace() for c in jwt_token):
+                raise ValueError("A login access JWT is required")
+            headers["Authorization"] = f"Bearer {jwt_token}"
+        else:
+            headers["Authorization"] = f"Bearer {self._key(self.api_key)}"
+        response = self._session.request(method, f"{self.base_url}{path}", headers=headers,
+                                         params=params, json=body, timeout=self.timeout)
+        response.raise_for_status()
+        return response.json()
+
+    def get_materials(self, page=1, per_page=20, **filters):
+        """One page (1..100 items); legacy per_page=0 uses automatic pagination."""
+        if per_page == 0 and not isinstance(per_page, bool):
+            if not filters.get("detail") and filters.get("data_type") is None:
+                return self.get_all_materials(**filters)
+            per_page = 20
+        return self._request("GET", "/materials/search",
+                             params={"page": page, "per_page": per_page, **filters})
+
+    def get_material(self, material_id):
+        return self.get_materials(material_id=material_id, detail="true")
+
+    def get_pdf_data(self, material_id):
+        return self.get_data(material_id, "pdf")
+
+    def get_data(self, material_id, data_type):
+        return self.get_materials(material_id=material_id, data_type=data_type)
+
+    def search(self, criteria):
+        """Advanced POST search; the caller's criteria are never modified."""
+        if not isinstance(criteria, dict):
+            raise ValueError("criteria must be a dictionary")
+        criteria = deepcopy(criteria)
+        if criteria.get("per_page") == 0 and not isinstance(criteria.get("per_page"), bool):
+            if not criteria.get("detail") and criteria.get("data_type") is None:
+                return self.search_all(criteria)
+            criteria["per_page"] = 20
+        return self._request("POST", "/materials/search", body=criteria)
+
+    @staticmethod
+    def _collect(fetch):
+        first = fetch(1)
+        if not isinstance(first.get("materials"), list):
+            # Legacy calls combining get_all with detail/data_type return one object.
+            return first
+        rows = list(first["materials"])
+        for page in range(2, first["pages"] + 1):
+            response = fetch(page)
+            rows.extend(response["materials"])
+            if not response["materials"]:
+                break
+        return {"materials": rows, "total": first["total"], "returned": len(rows),
+                "query": first.get("query", {})}
+
+    def get_all_materials(self, **filters):
+        """Fetch every page with bounded requests; datasets are not snapshot-isolated."""
+        filters = deepcopy(filters)
+        filters.pop("page", None)
+        filters.pop("per_page", None)
+        return self._collect(lambda page: self.get_materials(page=page, per_page=100, **filters))
+
+    def search_all(self, criteria):
+        if not isinstance(criteria, dict):
+            raise ValueError("criteria must be a dictionary")
+        criteria = deepcopy(criteria)
+        criteria["per_page"] = 100
+        return self._collect(lambda page: self.search({**criteria, "page": page}))
+
+    def generate_api_key(self, jwt_token):
+        """Works on PDFData_API() before the user has their first API key."""
+        if jwt_token is None:
+            raise ValueError("A login access JWT is required")
+        result = self._request("POST", "/user/create_key", jwt_token=jwt_token)
+        self.api_key = result["api_key"]
+        self.headers["Authorization"] = f"Bearer {self.api_key}"
+        return result
+
+    def get_api_keys(self, jwt_token):
+        if jwt_token is None:
+            raise ValueError("A login access JWT is required")
+        return self._request("GET", "/user/get_keys", jwt_token=jwt_token)
+
+    def delete_api_key(self, jwt_token, label):
+        if jwt_token is None:
+            raise ValueError("A login access JWT is required")
+        if not isinstance(label, str) or not label:
+            raise ValueError("label is required")
+        return self._request("DELETE", "/user/del_keys", body={"label": label}, jwt_token=jwt_token)
+
+    def close(self):
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+MaterialsAPI = PDFData_API

pdfdata_api-0.2.0/pdfdata_api.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: pdfdata-api
+Version: 0.2.0
+Summary: Python client for the PDFData materials database API
+Author-email: PDF Database Team <contact@pdfdata.org>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://pdfdata.org
+Project-URL: Documentation, https://pdfdata.org/documents/api
+Project-URL: Source, https://github.com/yanglonggroup/pdfDBflask
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# PDFData Python client
+
+Standalone client for `https://pdfdata.org/api/v1`. Requires Python 3.9+ and
+`requests`; Flask, MongoDB and scientific packages are not client dependencies.
+Version 0.2.0 source and build configuration are in this repository. A public
+PyPI release has not been made as part of this change.
+
+Install from a local checkout (repository root):
+
+```sh
+python -m pip install ./src/pdfdb_backend
+```
+
+Or install the built wheel supplied with a release:
+
+```sh
+python -m pip install /path/to/pdfdata_api-0.2.0-py3-none-any.whl
+```
+
+Generate a key on the website's API page after signing in. Set it in an
+environment variable and query:
+
+```python
+import os
+from pdfdata_api import PDFData_API
+
+with PDFData_API(api_key=os.environ["PDFDATA_API_KEY"]) as client:
+    page = client.get_materials(elements="Si,O", per_page=20)
+    material = client.get_material("mp-10009-X")
+    curve = client.get_pdf_data("mp-10009-X")
+    all_matches = client.get_all_materials(elements="Si,O")
+```
+
+`get_materials()` and `search()` return one page by default. Page size is 1–100.
+`get_all_materials()` and `search_all()` collect successive pages. Legacy client
+calls with `per_page=0` also collect successive pages; direct HTTP requests must
+use page sizes 1–100. Collection is not a database snapshot while data changes.
+
+Advanced search:
+
+```python
+result = client.search({
+    "elements": {"all": ["Si"], "none": ["Au"]},
+    "qmax": "[10,30]",
+    "page": 1,
+    "per_page": 20,
+})
+```
+
+For applications already holding a website **access JWT**, `PDFData_API()` can
+call `generate_api_key(jwt_token)`, `get_api_keys(jwt_token)` and
+`delete_api_key(jwt_token, "Key 1")`. The generated key is set on the client.
+Key management requires the login JWT; material queries require the API key.
+`generate_api_key` creates a new key on each call and is not automatically retried.
+
+`MaterialsAPI` remains an alias of `PDFData_API`. The old import
+`from PDFData_API import PDFData_API` remains supported. Backend source imports
+`from app.api.client import MaterialsAPI` forward to the same implementation.
+The default timeout is 30 seconds and can be set with `timeout=60`. HTTP errors
+raise `requests.HTTPError`; inspect `exc.response.status_code` and JSON `code`.
+
+Build from this directory:
+
+```sh
+python -m build
+```
+
+Only `pdfdata_api` and the legacy `PDFData_API` module are included in the
+distribution. Production environment files and backend code are excluded.

pdfdata_api-0.2.0/pdfdata_api.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE.txt
+PDFData_API.py
+README.md
+pyproject.toml
+setup.py
+pdfdata_api/__init__.py
+pdfdata_api/client.py
+pdfdata_api.egg-info/PKG-INFO
+pdfdata_api.egg-info/SOURCES.txt
+pdfdata_api.egg-info/dependency_links.txt
+pdfdata_api.egg-info/requires.txt
+pdfdata_api.egg-info/top_level.txt

pdfdata_api-0.2.0/pdfdata_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pdfdata_api-0.2.0/pdfdata_api.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25.0

pdfdata_api-0.2.0/pdfdata_api.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+PDFData_API
+pdfdata_api

pdfdata_api-0.2.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdfdata-api"
+version = "0.2.0"
+description = "Python client for the PDFData materials database API"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{name = "PDF Database Team", email = "contact@pdfdata.org"}]
+dependencies = ["requests>=2.25.0"]
+license = "BSD-3-Clause"
+license-files = ["LICENSE.txt"]
+
+[project.urls]
+Homepage = "https://pdfdata.org"
+Documentation = "https://pdfdata.org/documents/api"
+Source = "https://github.com/yanglonggroup/pdfDBflask"
+
+[tool.setuptools]
+packages = ["pdfdata_api"]
+py-modules = ["PDFData_API"]

pdfdata_api-0.2.0/setup.cfg

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

pdfdata_api-0.2.0/setup.py

@@ -0,0 +1,5 @@
+"""Legacy setuptools entry point; metadata lives in pyproject.toml."""
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()