Annotate data models in Pydantic and APIs in FastAPI with the Bioregistry to make them more FAIR
MIT License
Annotate your data models in Pydantic and APIs in FastAPI with the Bioregistry to make them more FAIR
You can use one of the several extensions to Pydantic and FastAPI's Field
classes.
from pydantic import BaseModel, Field
from semantic_pydantic import SemanticField
class Scholar(BaseModel):
"""A model representing a researcher, who might have several IDs on different services."""
orcid: str = SemanticField(..., prefix="orcid")
name: str = Field(..., example="Charles Tapley Hoyt")
wos: str | None = SemanticField(default=None, prefix="wos.researcher")
dblp: str | None = SemanticField(default=None, prefix="dblp.author")
github: str | None = SemanticField(default=None, prefix="github")
scopus: str | None = SemanticField(default=None, prefix="scopus")
semion: str | None = SemanticField(default=None, prefix="semion")
publons: str | None = SemanticField(default=None, prefix="publons.researcher")
authorea: str | None = SemanticField(default=None, prefix="authorea.author")
Similarly, this can be used in FastAPI.
from fastapi import FastAPI
from semantic_pydantic import SemanticPath
app = FastAPI(title="Semantic Pydantic Demo")
Scholar = ... # defined before
@app.get("/api/orcid/{orcid}", response_model=Scholar)
def get_scholar_from_orcid(orcid: str = SemanticPath(prefix="orcid")):
"""Get xrefs for a researcher in Wikidata, given ORCID identifier."""
... # full implementation in https://github.com/cthoyt/semantic-pydantic
return Scholar(...)
Here's what the Swagger UI looks like, including all the annotations on both the data model and endpoint arguments.
The demo can be run by cloning the repository, installing its requirements, and
running the self-contained demo.py
.
The most recent release can be installed from PyPI with:
pip install semantic_pydantic
The most recent code and data can be installed directly from GitHub with:
pip install git+https://github.com/cthoyt/semantic-pydantic.git
Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See CONTRIBUTING.md for more information on getting involved.
The code in this package is licensed under the MIT License.
This work was initially funded by the Chan Zuckerberg Initiative (CZI) under award 2023-329850.
This package was created with @audreyfeldroy's cookiecutter package using @cthoyt's cookiecutter-snekpack template.
The final section of the README is for if you want to get involved by making a code contribution.
To install in development mode, use the following:
git clone git+https://github.com/cthoyt/semantic-pydantic.git
cd semantic-pydantic
pip install -e .
This project uses cruft
to keep boilerplate (i.e., configuration, contribution guidelines, documentation
configuration)
up-to-date with the upstream cookiecutter package. Update with the following:
pip install cruft
cruft update
More info on Cruft's update command is available here.
After cloning the repository and installing tox
and tox-uv
with pip install tox tox-uv
,
the unit tests in the tests/
folder can be run reproducibly with:
tox
Additionally, these tests are automatically re-run with each commit in a GitHub Action.
The documentation can be built locally using the following:
git clone git+https://github.com/cthoyt/semantic-pydantic.git
cd semantic-pydantic
tox -e docs
open docs/build/html/index.html
The documentation automatically installs the package as well as the docs
extra specified in the pyproject.toml
. sphinx
plugins
like texext
can be added there. Additionally, they need to be added to the
extensions
list in docs/source/conf.py
.
The documentation can be deployed to ReadTheDocs using
this guide.
The .readthedocs.yml
YAML file contains all the configuration you'll need.
You can also set up continuous integration on GitHub to check not only that
Sphinx can build the documentation in an isolated environment (i.e., with tox -e docs-test
)
but also that ReadTheDocs can build it too.
Zenodo is a long-term archival system that assigns a DOI to each release of your package.
After these steps, you're ready to go! After you make "release" on GitHub (steps for this are below), you can navigate to https://zenodo.org/account/settings/github/repository/cthoyt/semantic-pydantic to see the DOI for the release and link to the Zenodo record for it.
You only have to do the following steps once.
You have to do the following steps once per machine. Create a file in your home directory called
.pypirc
and include the following:
[distutils]
index-servers =
pypi
testpypi
[pypi]
username = __token__
password = <the API token you just got>
# This block is optional in case you want to be able to make test releases to the Test PyPI server
[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = <an API token from test PyPI>
Note that since PyPI is requiring token-based authentication, we use __token__
as the user, verbatim.
If you already have a .pypirc
file with a [distutils]
section, just make sure that there is an index-servers
key and that pypi
is in its associated list. More information on configuring the .pypirc
file can
be found here.
After installing the package in development mode and installing tox
and tox-uv
with pip install tox tox-uv
,
the commands for making a new release are contained within the finish
environment
in tox.ini
. Run the following from the shell:
tox -e finish
This script does the following:
pyproject.toml
, CITATION.cff
, src/semantic_pydantic/version.py
,docs/source/conf.py
to not have the -dev
suffixbuild
twine
.tox -e bumpversion -- minor
after.This will trigger Zenodo to assign a DOI to your release as well.