Commit 4dbbecd5 authored by Markus Scheidgen's avatar Markus Scheidgen
Browse files

Updated and fixed sphynx documentation.

parent 930610ea
......@@ -37,6 +37,11 @@
.. automodule:: nomad.user
```
## nomad.api
```eval_rst
.. automodule:: nomad.api
```
## nomad.utils
```eval_rst
.. automodule:: nomad.utils
......
......@@ -12,9 +12,20 @@
# See the License for the specific language governing permissions and
# limitations under the License.
from .app import app
from . import upload, repository, archive
"""
This module comprises the nomad@FAIRDI APIs.
The different APIs are upload, repository (raw data and search), and archive.
There is a separate documentation for the API endpoints from a client perspective.
.. autodata:: app
if __name__ == '__main__':
app.run(debug=True, port=8000)
.. automodule:: nomad.api.app
.. automodule:: nomad.api.upload
.. automodule:: nomad.api.repository
.. automodule:: nomad.api.archive
"""
from .app import app
from . import upload, repository, archive
......@@ -16,4 +16,4 @@ import nomad.api
if __name__ == '__main__':
nomad.api.app.run(debug=True, port=8000)
\ No newline at end of file
nomad.api.app.run(debug=True, port=8000)
......@@ -12,6 +12,16 @@
# See the License for the specific language governing permissions and
# limitations under the License.
"""
All APIs are served by one Flask app (:py:mod:`nomad.api.app`) under different paths.
Endpoints can use *flask_httpauth* based authentication either with basic HTTP
authentication or access tokens. Currently the authentication is validated against
users and sessions in the NOMAD-coe repository postgres db.
.. autodata:: base_path
.. autofunction:: login_really_required
"""
from flask import Flask, g
from flask_restful import Api, abort
from flask_cors import CORS
......@@ -23,11 +33,14 @@ from nomad.user import User
from nomad.processing import Upload
base_path = config.services.api_base_path
""" Provides the root path of the nomad APIs. """
app = Flask(
__name__,
static_url_path='%s/docs' % base_path,
static_folder=os.path.abspath(os.path.join(os.path.dirname(__file__), '../docs/.build/html')))
""" The Flask app that serves all APIs. """
CORS(app)
app.config['SECRET_KEY'] = config.services.api_secret
......@@ -59,6 +72,10 @@ def verify_password(username_or_token, password):
def login_really_required(func):
"""
A decorator for API endpoint implementations that forces user authentication on
endpoints.
"""
@auth.login_required
def wrapper(*args, **kwargs):
if g.user is None:
......@@ -73,6 +90,16 @@ def login_really_required(func):
@app.route('/api/token')
@login_really_required
def get_auth_token():
"""
Get a token for authenticated users. This is currently disabled and all authentication
matters are solved by the NOMAD-coe repository GUI.
.. :quickref: Get a token to authenticate the user in follow up requests.
:resheader Content-Type: application/json
:status 200: calc successfully retrieved
:returns: an authentication token that is valid for 10 minutes.
"""
assert False, 'All authorization is none via NOMAD-coe repository GUI'
# TODO all authorization is done via NOMAD-coe repository GUI
# token = g.user.generate_auth_token(600)
......@@ -81,6 +108,19 @@ def get_auth_token():
@app.route('%s/admin/<string:operation>' % base_path, methods=['POST'])
def call_admin_operation(operation):
"""
Allows to perform administrative operations on the nomad services. The possible
operations are *repair_uploads*
(cleans incomplete or otherwise unexpectedly failed uploads), *reset* (clears all
databases and resets nomad).
.. :quickref: Allows to perform administrative operations on the nomad services.
:param string operation: the operation to perform
:status 400: unknown operation
:status 200: operation successfully started
:returns: an authentication token that is valid for 10 minutes.
"""
if operation == 'repair_uploads':
Upload.repair_all()
if operation == 'reset':
......
......@@ -12,6 +12,11 @@
# See the License for the specific language governing permissions and
# limitations under the License.
"""
The archive API of the nomad@FAIRDI APIs. This API is about serving processed
(parsed and normalized) calculation data in nomad's *meta-info* format.
"""
import os.path
from flask import send_file
......
......@@ -12,6 +12,11 @@
# See the License for the specific language governing permissions and
# limitations under the License.
"""
The repository API of the nomad@FAIRDI APIs. Currently allows to resolve repository
meta-data as well as raw-calculation files.
"""
import os.path
from contextlib import contextmanager
from zipfile import ZIP_DEFLATED
......
......@@ -23,6 +23,11 @@ from nomad.utils import get_logger
from .app import api, base_path, login_really_required
"""
The upload API of the nomad@FAIRDI APIs. Provides endpoints to create uploads, upload
files, and retrieve the processing status of uploads.
"""
class UploadsRes(Resource):
""" Uploads """
......
......@@ -20,17 +20,26 @@ uploaded files, archive, files, raw files, etc. should be part of this module to
allow later introduction of real object storage systems.
.. note:: This module still uses ``os.path``. As long as the whole nomad runs on a
POSIX (or Windows) os everything should be fine. This means respective paths in the
dbs, and indices. In the future, this should be replaced with abstract path representations
ala ``PathLib``.
POSIX (or Windows) os everything should be fine. This means respective paths in the
dbs, and indices. In the future, this should be replaced with abstract path representations
ala ``PathLib``.
.. autoclass:: File
:members:
.. autoclass:: ZippedFile
:members:
.. autoclass:: ObjectFile
:members:
.. autoclass:: UploadFile
:members:
.. autoclass:: ArchiveFile
:members:
.. autoclass:: DataContainer
:members:
.. autoclass:: BaggedDataContainer
:members:
.. autoclass:: ZippedDataContainer
:members:
"""
from abc import ABC
from typing import List, Generator, IO, TextIO, cast, Dict, Any
......
# Copyright 2018 Markus Scheidgen
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an"AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import systax.analysis.symmetryanalyzer
......
......@@ -14,6 +14,22 @@
"""
Module with some prototypes/placeholder for future user management in nomad@FAIR.
It is currently based on the NOMAD-coe repository postgres API. This module allows
to authenticate users based on user password or session tokens. It allows to access
the user data like names and user_id.
This implementation is based on SQLAlchemy. There are model classes that represent
entries in the *users* and *session* tables.
.. autoclass:: User
:members:
:undoc-members:
.. autoclass:: Session
:members:
:undoc-members:
.. autofunction:: ensure_test_user
"""
from passlib.hash import bcrypt
......
......@@ -27,6 +27,10 @@ be used similar to the standard *logging.getLogger*.
Depending on the configuration all logs will also be send to a central logstash.
.. autofunc::nomad.utils.get_logger
.. autofunc::nomad.utils.hash
.. autofunc::nomad.utils.create_uuid
.. autofunc::nomad.utils.timer
.. autofunc::nomad.utils.lnr
"""
from typing import Union, IO, cast, List
......@@ -39,7 +43,6 @@ from structlog.stdlib import LoggerFactory
import logstash
from contextlib import contextmanager
import json
import sys
import uuid
import time
import re
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment