SEAMM Datastore
==============================
[//]: # (Badges)
[](https://github.com/molssi-seamm/seamm_datastore/actions?query=workflow%3ACI)
[](https://codecov.io/gh/molssi-seamm/seamm_datastore/branch/master)
This repository contains the SQLAlchemy models for the SEAMM datastore as well as some associated utilities such as dumping to JSON and checking permissions. These database models and permissions system were developed to be used inside a flask application context in the [SEAMM Dashboard](https://github.com/molssi-seamm/seamm_dashboard). However, you may use this package as a stand-alone (outside of flask) with limited permissions capabilities.
## Quickstart
This package contains SQLAlchemy models for the SEAMM datastore. The following gives an example of how to connect to a database in memory. You can switch the database by providing a different database URI.
```python
import seamm_datastore
# Create a database session
connection = seamm_datastore.connect("sqlite:///:memory:")
```
This will create a sqlite database stored in memory. Using `initialize=True` will result in a new database being created. You may substitute a different database URI in place of `sqlite:///memory`. When connecting to a database on disk, you will need to specify an additional argument, `initialize=True`, if creating a new database.
To login, use the login method. Your username is determined automatically by your username when running `connect` if `initialize` is `True.` An admin user is also create which you can use to login (username=`admin`, password=`admin`).
```python
connection.login(username="YOUR_USERNAME", password="default")
```
To import a datastore at a particular location, do:
```python
connection.import_datastore(FILEPATH)
```
To use the sample data in this repository,
```python
jobs, projects = connection.import_datastore("seamm_datastore/data/Projects")
```
JSON data of the added jobs and projects will be returned.
The `SEAMMDatastore` class has bound database models and a SQLAlchemy session factory which you can work with. These can be interacted with the same as other sqlalchemy models. To retrieve jobs for which you have "read" permissions from the database, use the bound SQLAlchemy models:
```
jobs = connection.Job.permissions_query("read").all()
```
To dump to json:
```python
from seamm_datastore.database.schema import JobSchema
# Create job schema
jobs_schema = JobSchema(many=True)
# To retrieve all users in db
all_jobs = connection.Job.permissions_query("read").all()
jobs_json = jobs_schema.dump(all_jobs)
```
## Permissions
The SEAMM datastore has a permissions system built in using [flask-authorize](https://flask-authorize.readthedocs.io/en/latest/) for authorization. This provides a "permissions" entry on each resource table (Jobs, Flowcharts, and Projects) where permissions for "owner", "group" and "world". The SEAMM datastore also has capabilities to set "special permissions" for users or groups on specific projects.
Permissions are not automatically enforced when working directly with database models. In the SEAMM Dashboard, permissions are enforced with **authentication** (verifying the user is who they say they are) using [flask-jwt-extended] and **authorization** using [flask-authorize](https://flask-authorize.readthedocs.io/en/latest/).
To use the permissions checking mechanisms of flask authorize outside of a flask app, use the helper function here `seamm_datastore.SEAMMDatastore`.
### Copyright
Copyright (c) 2021, Jessica A. Nash (The Molecular Sciences Software Institute)
#### Acknowledgements
Project based on the
[Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.5.
Raw data
{
"_id": null,
"home_page": "https://github.com/molssi-seamm/seamm_datastore",
"name": "seamm-datastore",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "SEAMM, datastore, dashboard",
"author": "Jessica A. Nash (The Molecular Sciences Software Institute)",
"author_email": "janash@vt.edu",
"download_url": "https://files.pythonhosted.org/packages/3f/af/e11e20876aba446e81b60872ba9214fc4990a4a63b915c40c4691ed5ab5e/seamm_datastore-2024.6.2.tar.gz",
"platform": "Linux",
"description": "SEAMM Datastore\n==============================\n[//]: # (Badges)\n[](https://github.com/molssi-seamm/seamm_datastore/actions?query=workflow%3ACI)\n[](https://codecov.io/gh/molssi-seamm/seamm_datastore/branch/master)\n\n\nThis repository contains the SQLAlchemy models for the SEAMM datastore as well as some associated utilities such as dumping to JSON and checking permissions. These database models and permissions system were developed to be used inside a flask application context in the [SEAMM Dashboard](https://github.com/molssi-seamm/seamm_dashboard). However, you may use this package as a stand-alone (outside of flask) with limited permissions capabilities.\n\n## Quickstart\n\nThis package contains SQLAlchemy models for the SEAMM datastore. The following gives an example of how to connect to a database in memory. You can switch the database by providing a different database URI.\n\n```python\nimport seamm_datastore\n\n# Create a database session\nconnection = seamm_datastore.connect(\"sqlite:///:memory:\")\n```\nThis will create a sqlite database stored in memory. Using `initialize=True` will result in a new database being created. You may substitute a different database URI in place of `sqlite:///memory`. When connecting to a database on disk, you will need to specify an additional argument, `initialize=True`, if creating a new database.\n\nTo login, use the login method. Your username is determined automatically by your username when running `connect` if `initialize` is `True.` An admin user is also create which you can use to login (username=`admin`, password=`admin`).\n\n```python\nconnection.login(username=\"YOUR_USERNAME\", password=\"default\")\n```\n\nTo import a datastore at a particular location, do:\n\n```python\nconnection.import_datastore(FILEPATH)\n```\n\nTo use the sample data in this repository,\n\n```python\njobs, projects = connection.import_datastore(\"seamm_datastore/data/Projects\")\n```\n\nJSON data of the added jobs and projects will be returned.\n\nThe `SEAMMDatastore` class has bound database models and a SQLAlchemy session factory which you can work with. These can be interacted with the same as other sqlalchemy models. To retrieve jobs for which you have \"read\" permissions from the database, use the bound SQLAlchemy models:\n\n```\njobs = connection.Job.permissions_query(\"read\").all()\n```\n\nTo dump to json:\n\n```python\nfrom seamm_datastore.database.schema import JobSchema\n\n# Create job schema\njobs_schema = JobSchema(many=True)\n\n# To retrieve all users in db\nall_jobs = connection.Job.permissions_query(\"read\").all()\n\njobs_json = jobs_schema.dump(all_jobs)\n```\n\n## Permissions\n\nThe SEAMM datastore has a permissions system built in using [flask-authorize](https://flask-authorize.readthedocs.io/en/latest/) for authorization. This provides a \"permissions\" entry on each resource table (Jobs, Flowcharts, and Projects) where permissions for \"owner\", \"group\" and \"world\". The SEAMM datastore also has capabilities to set \"special permissions\" for users or groups on specific projects.\n\nPermissions are not automatically enforced when working directly with database models. In the SEAMM Dashboard, permissions are enforced with **authentication** (verifying the user is who they say they are) using [flask-jwt-extended] and **authorization** using [flask-authorize](https://flask-authorize.readthedocs.io/en/latest/). \n\nTo use the permissions checking mechanisms of flask authorize outside of a flask app, use the helper function here `seamm_datastore.SEAMMDatastore`.\n\n### Copyright\n\nCopyright (c) 2021, Jessica A. Nash (The Molecular Sciences Software Institute)\n\n\n#### Acknowledgements\n \nProject based on the \n[Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.5.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "seamm_datastore",
"version": "2024.6.2",
"project_urls": {
"Homepage": "https://github.com/molssi-seamm/seamm_datastore"
},
"split_keywords": [
"seamm",
" datastore",
" dashboard"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "907d4e6f6838df470b6341eb8abdf6e8381c9b2d9b5ef140647742d220aa31a1",
"md5": "ce39cc041e52dfd8090448238c37fd94",
"sha256": "337829b17e8b598831784fa071321b6b7ade5bd818f94503ff14ed451e335268"
},
"downloads": -1,
"filename": "seamm_datastore-2024.6.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce39cc041e52dfd8090448238c37fd94",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 90151,
"upload_time": "2024-06-02T18:57:12",
"upload_time_iso_8601": "2024-06-02T18:57:12.688103Z",
"url": "https://files.pythonhosted.org/packages/90/7d/4e6f6838df470b6341eb8abdf6e8381c9b2d9b5ef140647742d220aa31a1/seamm_datastore-2024.6.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3fafe11e20876aba446e81b60872ba9214fc4990a4a63b915c40c4691ed5ab5e",
"md5": "583b4d45b52d3542ebd00c1367839620",
"sha256": "d1eb0d0a1909b4670c3115c2bb82522a30e0302a525e23d1b97fca6632478492"
},
"downloads": -1,
"filename": "seamm_datastore-2024.6.2.tar.gz",
"has_sig": false,
"md5_digest": "583b4d45b52d3542ebd00c1367839620",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 95929,
"upload_time": "2024-06-02T18:57:14",
"upload_time_iso_8601": "2024-06-02T18:57:14.399479Z",
"url": "https://files.pythonhosted.org/packages/3f/af/e11e20876aba446e81b60872ba9214fc4990a4a63b915c40c4691ed5ab5e/seamm_datastore-2024.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-02 18:57:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "molssi-seamm",
"github_project": "seamm_datastore",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "seamm-datastore"
}
JSON
