Metadata-Version: 2.1
Name: optimade
Version: 0.7.0
Summary: Tools for implementing and consuming OPTiMaDe APIs.
Home-page: https://github.com/Materials-Consortia/optimade-python-tools
Author: OPTiMaDe Development Team
Author-email: dev@optimade.org
License: MIT
Description: # OPTiMaDe Python tools
        
        | Latest release | Build status | Activity |
        |:--------------:|:------------:|:--------:|
        | [![PyPI Version](https://img.shields.io/pypi/v/optimade?logo=pypi)](https://pypi.org/project/optimade/)<br>[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/optimade?logo=python)](https://pypi.org/project/optimade/)<br>[![OPTiMaDe](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/master/.ci/optimade-version.json&logo=json)](https://github.com/Materials-Consortia/OPTiMaDe/) | [![Build Status](https://img.shields.io/github/workflow/status/Materials-Consortia/optimade-python-tools/Testing,%20linting,%20and%20OpenAPI%20validation?logo=github)](https://github.com/Materials-Consortia/optimade-python-tools/actions?query=branch%3Amaster+)<br>[![codecov](https://codecov.io/gh/Materials-Consortia/optimade-python-tools/branch/master/graph/badge.svg)](https://codecov.io/gh/Materials-Consortia/optimade-python-tools)<br>[![Heroku](https://heroku-badge.herokuapp.com/?app=optimade&root=v0/info)](https://optimade.herokuapp.com/v0/info) | [![Commit Activity](https://img.shields.io/github/commit-activity/m/Materials-Consortia/optimade-python-tools?logo=github)](https://github.com/Materials-Consortia/optimade-python-tools/pulse) |
        
        The aim of OPTiMaDe is to develop a common API, compliant with the [JSON API 1.0](http://jsonapi.org/format/1.0/) specification.
        This is to enable interoperability among databases that contain calculated properties of existing and hypothetical materials.
        
        This repository contains a library of tools for implementing and consuming [OPTiMaDe](https://www.optimade.org) APIs using Python.
        It also contains a server validator tool, which may be called from the shell or used as a GitHub Action.
        
        _Disclaimer_: While the package supports `elasticsearch-dsl` v6 & v7 and `django` v2 & v3, all tests are performed with the latest supported version.
        If you experience any issues with the older versions, you are most welcome to contribute to the repository (see below under Contributing).
        
        ## Status
        
        Both the OPTiMaDe specification and this repository are **under development**.
        
        The latest stable version can be obtained from [PyPI](https://pypi.org/project/optimade) `pip install optimade` or by cloning the master branch of this repository `git clone git@github.com:Materials-Consortia/optimade-python-tools`.
        
        ## Installation
        
        Installation instructions, for both the index meta-database, and for the main API can be found in [INSTALL.md](INSTALL.md).
        
        ## Contributing
        
        Contribution guidelines and tips can be found in [CONTRIBUTING.md](CONTRIBUTING.md).
        
        ## GitHub Action - OPTiMaDe validator
        
        This action runs `optimade_validator` from this repository on a running server.
        
        ### Example usage
        
        To run `optimade_validator` for an index meta-database at `http://gh_actions_host:5001/v0` do the following:  
        Within the same job, first, start a server, e.g., using the `docker-compose.yml` setup from this repository, and then add the step
        
        ```yml
        uses: Materials-Consortia/optimade-python-tools@master
        with:
          port: 5001
          path: /v0
          index: yes
        ```
        
        To run `optimade_validator` for a regular OPTiMaDe _deployed_ implementation, testing all possible versioned base URLs:
        
        - `https://example.org:443/optimade/example/v0`
        - `https://example.org:443/optimade/example/v0.10`
        - `https://example.org:443/optimade/example/v0.10.1`
        
        ```yml
        uses: Materials-Consortia/optimade-python-tools@master
        with:
          protocol: https
          domain: example.org
          port: 443
          path: /optimade/example
          all versioned paths: True
        ```
        
        ### Inputs
        
        #### `protocol`
        
        **Optional** Protocol for the OPTiMaDe URL.  
        **Default**: `http`
        
        #### `domain`
        
        **Optional** Domain for the OPTiMaDe URL (defaults to the GitHub Actions runner host).  
        **Default**: `gh_actions_host`
        
        #### `port`
        
        **Optional** Port for the OPTiMaDe URL.  
        **Default**: `5000`
        
        #### `path`
        
        **Optional** Path for the OPTiMaDe (versioned) base URL - MUST start with `/`  
        _Note_: If `all versioned paths` is `true`, this MUST be un-versioned, e.g., `/optimade` or `/`, otherwise it MUST be versioned, e.g., the default value.  
        **Default**: `/v0`
        
        #### `all versioned paths`
        
        **Optional** Whether to test all possible versioned base URLs:
        
        - /vMAJOR
        - /vMAJOR.MINOR
        - /vMAJOR.MINOR.PATCH
        
        If this is `'true'`, the input `'path'` MUST exempt the version part (e.g., `'/optimade'` instead of `'/optimade/v0'`).  
        If this is `'false'`, the input `'path'` MUST include the version part (e.g., `'/optimade/v0'` instead of `'/optimade'`).  
        **Default**: `false`
        
        #### `index`
        
        **Optional** Whether or not this is an index meta-database.  
        **Default**: `false`
        
        ## Links
        
        - [OPTiMaDe Specification](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.rst), the human-readable specification that this library is based on.
        - [OpenAPI](https://github.com/OAI/OpenAPI-Specification), the machine-readable format used to specify the OPTiMaDe API in [`openapi.json`](openapi.json).
        - [Interactive documentation](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/master/openapi.json) generated from [`openapi.json`](openapi.json) (see also [interactive JSON editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/master/openapi.json)).
        - [pydantic](https://pydantic-docs.helpmanual.io/), the library used for generating the OpenAPI schema from [Python models](optimade/models).
        - [FastAPI](https://fastapi.tiangolo.com/), the framework used for generating the reference implementation from the [`openapi.json`](openapi.json) specification.
        - [lark](https://github.com/lark-parser/lark), the library used to parse the filter language in OPTiMaDe queries.
        
Keywords: optimade jsonapi materials
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: server
Provides-Extra: testing
Provides-Extra: django
Provides-Extra: elastic
Provides-Extra: mongo
