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.
