Metadata-Version: 2.4
Name: mavedb
Version: 2025.5.0
Summary: API for MaveDB, the database of Multiplexed Assays of Variant Effect.
License: AGPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Provides-Extra: server
Requires-Dist: IDUtils (>=1.2.0,<1.3.0)
Requires-Dist: SQLAlchemy (>=2.0.29,<2.1.0)
Requires-Dist: alembic (>=1.14.0,<1.15.0) ; extra == "server"
Requires-Dist: alembic-utils (==0.8.1) ; extra == "server"
Requires-Dist: arq (>=0.25.0,<0.26.0) ; extra == "server"
Requires-Dist: authlib (>=1.6.5,<1.7.0) ; extra == "server"
Requires-Dist: biocommons (>=0.0.0,<0.1.0) ; extra == "server"
Requires-Dist: boto3 (>=1.34.97,<1.35.0) ; extra == "server"
Requires-Dist: cdot (>=0.2.21,<0.3.0) ; extra == "server"
Requires-Dist: cryptography (>=44.0.1,<44.1.0) ; extra == "server"
Requires-Dist: email_validator (>=2.1.1,<2.2.0)
Requires-Dist: eutils (>=0.6.0,<0.7.0)
Requires-Dist: fastapi (>=0.121.0,<0.122.0) ; extra == "server"
Requires-Dist: fqfa (>=1.3.0,<1.4.0)
Requires-Dist: ga4gh-va-spec (>=0.4.2,<0.5.0) ; extra == "server"
Requires-Dist: hgvs (>=1.5.4,<1.6.0) ; extra == "server"
Requires-Dist: httpx (>=0.26.0,<0.27.0)
Requires-Dist: mavehgvs (>=0.7.0,<0.8.0)
Requires-Dist: numpy (>=1.26,<1.27)
Requires-Dist: orcid (>=1.0.3,<1.1.0) ; extra == "server"
Requires-Dist: pandas (>=1.4.1,<1.5.0)
Requires-Dist: psycopg2 (>=2.9.3,<2.10.0) ; extra == "server"
Requires-Dist: pyathena (>=3.14.1,<3.15.0) ; extra == "server"
Requires-Dist: pydantic (>=2.10.0,<2.11.0)
Requires-Dist: pyhumps (>=3.8.0,<3.9.0)
Requires-Dist: python-dotenv (>=0.20.0,<0.21.0)
Requires-Dist: python-jose[cryptography] (>=3.5.0,<3.6.0) ; extra == "server"
Requires-Dist: python-json-logger (>=2.0.7,<2.1.0)
Requires-Dist: python-multipart (>=0.0.5,<0.1.0) ; extra == "server"
Requires-Dist: pyyaml (>=6.0.1,<6.1.0)
Requires-Dist: requests (>=2.32.2,<2.33.0) ; extra == "server"
Requires-Dist: slack-sdk (>=3.21.3,<3.22.0) ; extra == "server"
Requires-Dist: starlette (>=0.49.0,<0.50.0) ; extra == "server"
Requires-Dist: starlette-context (>=0.3.6,<0.4.0) ; extra == "server"
Requires-Dist: uvicorn[standard] ; extra == "server"
Requires-Dist: watchtower (>=3.2.0,<3.3.0) ; extra == "server"
Project-URL: Documentation, https://mavedb.org/docs/mavedb/
Project-URL: Homepage, https://mavedb.org
Project-URL: Repository, https://github.com/VariantEffect/mavedb-api
Description-Content-Type: text/markdown

# mavedb-api

API for MaveDB. MaveDB is a biological database for Multiplex Assays of Variant Effect (MAVE) datasets.
The API powers the MaveDB website at [mavedb.org](https://www.mavedb.org) and can also be called separately (see
instructions [below](#using-mavedb-api)).


For more information about MaveDB or to cite MaveDB please refer to the
[MaveDB paper in Genome Biology](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-019-1845-6).

## Using mavedb-api

### Using the library as an API client or validator for MaveDB data sets

Simply install the package using PIP:

```
pip install mavedb
```

Or add `mavedb` to your Python project's dependencies.

## Building and running mavedb-api

### Prerequisites

- Python 3.11 or later
- PIP
- [Poetry](https://python-poetry.org/) for building and publishing distributions. For details on installing poetry, consult its [documentation](https://python-poetry.org/docs/#installation).

### Building distribution packages

To build the source distribution and wheel, run

```
poetry build
```

The build utility will look at `pyproject.toml` and invoke Poetry to build the distributions. Note that it will output build artifacts to `./dist` by default.

The distribution can be uploaded to PyPI using Poetry as well. After building the packaged, simply invoke

```
poetry publish -r pypi -u <username> -p <password>
```

To build and publish the package in one go, just pass the `--build` flag to the publish command.

For use as a server, this distribution includes an optional set of dependencies, which are only invoked if the package
is installed with `poetry install mavedb --extras server`.

### Running a local version of the API server

First build the application's Docker image:
```
docker build --tag mavedb-api/mavedb-api .
```
Then start the application and its database:
```
docker-compose -f docker-compose-local.yml up -d
```
Omit `-d` (daemon) if you want to run the application in your terminal session, for instance to see startup errors without having
to inspect the Docker container's log.

To stop the application when it is running as a daemon, run
```
docker-compose -f docker-compose-local.yml down
```

`docker-compose-local.yml` configures four containers: one for the API server, one for the PostgreSQL database, one for the
worker node and one for the Redis cache which acts as the job queue for the worker node. The worker node stores data in a Docker
volume named `mavedb-redis` and the database stores data in a Docker volume named `mavedb-data`. Both these volumes will persist
after running `docker-compose down`.

**Notes**
1. The `mavedb-api` container requires the following environment variables, which are configured in
  `docker-compose-local.yml`:

    - DB_HOST
    - DB_PORT
    - DB_DATABASE_NAME
    - DB_USERNAME
    - DB_PASSWORD
    - NCBI_API_KEY
    - REDIS_IP
    - REDIS_PORT

    The database username and password should be edited for production deployments. `NCBI_API_KEY` will be removed in
    the future. **TODO** Move these to an .env file.

### Running the API server in Docker for development

A similar procedure can be followed to run the API server in development mode on your local machine. There are a couple
of differences:

- Your local source code directory is mounted to the Docker container, instead of copying it into the container.
- The Uvicorn web server is started with a `--reload` option, so that code changes will cause the application to be
  reloaded, and you will not have to restart the container.
- The API uses HTTP, whereas in production it uses encrypted communication via HTTPS.

To start the Docker container for development, make sure that the mavedb-api directory is allowed to be shared with
Docker.  In Docker Desktop, this can be configured under Settings > Resources > File sharing.

To start the application, run
```
docker-compose -f docker-compose-dev.yml up --build -d
```

Docker integration can also be configured in IDEs like PyCharm.

### Running the API server directly for development

Sometimes you may want to run the API server outside of Docker. There are two ways to do this:

Before using either of these methods, configure the environment variables described above.

1. Run the server_main.py script. This script will create the FastAPI application, start up an instance of the Uvicorn,
  and pass the application to it.
  ```
  export PYTHONPATH=${PYTHONPATH}:"`pwd`/src"
  python src/mavedb/server_main.py
  ```
2. Run Uvicorn and pass it the application. This method supports code change auto-reloading.
  ```
  export PYTHONPATH=${PYTHONPATH}:"`pwd`/src"
  uvicorn mavedb.server_main:app --reload
  ```

If you use PyCharm, the first method can be used in a Python run configuration, but the second method supports PyCharm's
FastAPI run configuration.

### Running the API server for production

We maintain deployment configuration options and steps within a [private repository](https://github.com/VariantEffect/mavedb-deployment) used for deploying this source code to
the production MaveDB environment. The main difference between the production setup and these local setups is that
the worker and api services are split into distinct environments, allowing them to scale up or down individually
dependent on need.

