Emmet API Server

Warnings

• breaking The Emmet project is under active development with frequent pre-release versions (e.g., `0.87.0.devX`). While `emmet-api` has stable releases, significant architectural and API changes are common across the broader Emmet ecosystem, which may lead to breaking changes in minor versions or impact integration with other Emmet packages.
  Fix: Refer to the GitHub changelog and release notes for each specific version before upgrading, especially pre-releases. Pin dependencies to exact versions to avoid unexpected breakage.
• gotcha While `emmet-api` is a standalone PyPI package, it is part of a larger 'Emmet toolkit' from the Materials Project. Full functionality and understanding of the data models often require interaction with or knowledge of `emmet-core`. Users might need to install `emmet-core` separately to access core document definitions and utilities.
  Fix: Familiarize yourself with the `emmet-core` library and install it if you need to work directly with Materials Project data models or schema definitions: `pip install emmet-core`.
• gotcha The `emmet-api` package explicitly requires Python >=3.11. Attempting to install or run it with older Python versions will result in installation failures or runtime errors.
  Fix: Ensure your Python environment is at version 3.11 or newer. Use tools like `pyenv` or `conda` to manage multiple Python versions if needed.

Install

• pip install emmet-api Install stable version
• pip install 'emmet-api[test,docs]' # for optional extras Install with optional extras

Imports

• FastAPI

  from fastapi import FastAPI

  emmet-api is built on FastAPI, so many core FastAPI components are imported directly.
• build_router

  from emmet_api.routes import build_router

  This function is used to integrate Emmet's predefined API routes into a FastAPI application.
• EmmetSettings

  from emmet_api.core.config import EmmetSettings

  Used for loading application-specific configurations, such as database connection details.

Quickstart

The `emmet-api` library primarily provides an API server, built on FastAPI. The quickstart demonstrates how to set up a basic FastAPI application and integrate Emmet's routers. To run the API server, you would typically use the `uvicorn` command, pointing to the configured FastAPI application instance, whether it's a custom script or the default `emmet_api.main:app` entry point provided by the package. Ensure necessary environment variables for `EmmetSettings` (e.g., database connection) are configured.

import uvicorn
from fastapi import FastAPI
from emmet_api.routes import build_router
from emmet_api.core.config import EmmetSettings

# Initialize FastAPI app
app = FastAPI(
    title="Emmet API Server Example",
    description="Minimal Emmet API instance for demonstration",
    version="0.86.3"
)

# Load settings (adjust as per your environment variables or config files)
settings = EmmetSettings() # This will load settings from environment variables or .env file

# Build and include routers into the FastAPI app
# The build_router function modifies the app in-place.
build_router(app, settings)

# To run this application, save it as, e.g., `my_api.py` and execute:
# uvicorn my_api:app --host 0.0.0.0 --port 8000 --reload
# Alternatively, if running directly from the installed emmet-api package's entry point:
# uvicorn emmet_api.main:app --host 0.0.0.0 --port 8000 --reload

# The following lines are for demonstration if this script were the entry point
# if __name__ == "__main__":
#     uvicorn.run(app, host="0.0.0.0", port=8000)

# Note: This quickstart primarily shows the Python setup. 
# Running the server typically involves the `uvicorn` command-line tool.