Metadata-Version: 2.4
Name: httk-serve
Version: 2.1.0
Summary: HTTP, web, DSP, and OPTIMADE serving tooling for httk₂
Author-email: Rickard Armiento <rickard-gpg@armiento.net>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://httk.org
Project-URL: Documentation, https://docs.httk.org/httk-serve/
Project-URL: Repository, https://github.com/httk/httk-serve
Project-URL: Issues, https://github.com/httk/httk-serve/issues
Keywords: Materials Discovery,Materials Informatics,Materials Science
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httk-core<3,>=2.1.0
Requires-Dist: httk-store<3,>=2.1.0
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: referencing<1,>=0.35
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown>=3.5
Requires-Dist: PyYAML>=6.0
Requires-Dist: docutils>=0.20
Requires-Dist: starlette>=0.37
Requires-Dist: uvicorn>=0.30
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: httk-atomistic<3,>=2.1.0; extra == "dev"
Requires-Dist: httk-store[db]; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: openapi-spec-validator<0.8,>=0.7; extra == "dev"
Requires-Dist: rdflib<8,>=7; extra == "dev"
Requires-Dist: pyshacl<1,>=0.30; extra == "dev"
Requires-Dist: types-jsonschema; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Requires-Dist: pydoclint<1,>=0.9; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6.0; extra == "release"
Provides-Extra: default
Dynamic: license-file

# httk-serve

![Status: Early beta](https://img.shields.io/badge/status-early--beta-orange)

> **⚠️ EARLY BETA**
>
> This is an early beta release of *httk₂*. The organization of the packages
> and their APIs should not yet be regarded as stable, and may change between
> releases.

*httk-serve* is a [*httk₂*](https://github.com/httk/httk2) distribution providing a generic implementation of the [OPTIMADE](https://www.optimade.org/) protocol. Durable deployments can pass an `httk.store.EntryStore` directly to `create_asgi_app`, which discovers registered OPTIMADE families and queries them lazily; `EntryProvider` remains the in-memory path for generated and compatibility datasets.

The served API version is **OPTIMADE v1.3.0**. Implemented optional parts of the
specification include sorting, the `references`, `files`, and `trajectories` entry types,
relationships with the `include` query parameter, per-property metadata, the partial data
protocol (JSON Lines format and `dimension_slices`) with the compact list representation,
and the `license`/`available_licenses`/warnings meta and base-info fields. Optional parts
that remain unimplemented: cross-source sort merging, filtering on relationship
`.target.*`/`.description`/`.role` properties, the sparse JSON Lines layout, and
rejection of unrecognized query parameters. See
`docs/optimade/how_it_works.md` for the protocol architecture and backend/web seams.

Multiple Starlette services can be composed at explicit paths. For example, an
OPTIMADE index and database can share a parent application without coupling
their URL configuration:

```python
from httk.serve import ASGIAppMount, compose_asgi_apps
from httk.serve.optimade import OptimadeIndexConfig, create_index_asgi_app

index = create_index_asgi_app(OptimadeIndexConfig(links=[...]), baseurl="https://example.org/optimade/index/")
app = compose_asgi_apps([ASGIAppMount("/optimade/index", index)], root=ASGIAppMount("/", website_app))
```

The implementation was ported from the OPTIMADE server in httk v1 (which served OPTIMADE
v1.0.0) and then upgraded to v1.3.0. The legacy client-side `validation/` subpackage has
intentionally not been ported; use the official
[`optimade-validator`](https://github.com/Materials-Consortia/optimade-python-tools) tool
to check conformance of a running server.

## HTTP helpers

`httk.serve.http` provides lightweight, mountable JSON, JSON-LD, and explicit
file-map applications without requiring a website source tree. Protocol-owned
schemas, vocabulary rules, and discovery document construction remain with
the caller.

## Web tooling

`httk.serve.web` provides Jinja2 rendering, legacy `.httkweb` compatibility,
static publication, and an ASGI runtime. Its trusted widgets include
`httk.serve.table` for provider-backed pagination and
`httk.serve.optimade_table` for browser-side OPTIMADE access. Use
`httk serve web serve`, `httk serve web check`, or `httk serve web list`.
