flaschengeist/readme.md

Flaschengeist

This is the backend of the Flaschengeist.

Installation

Requirements

• mysql or mariadb
  • including development files libmariadb-dev
• python 3.6+

Install python files

pip3 install --user .

or with ldap support

pip3 install --user ".[ldap]"

or if you want to also run the tests:

pip3 install --user ".[ldap,test]"

You will also need a MySQL driver, recommended drivers are

• mysqlclient
• PyMySQL

setup.py will try to install a matching driver.

Windows

Same as above, but if you want to use mysqlclient instead of PyMySQL (performance?) you have to follow this guide:

https://www.radishlogic.com/coding/python-3/installing-mysqldb-for-python-3-in-windows/

Configuration

Configuration is done within the a flaschengeist.tomlfile, you can copy the one located inside the module path (where flaschegeist is installed) or create an empty one and place it inside either:

1. ~/.config/
2. A custom path and set environment variable FLASCHENGEIST_CONF

Uncomment and change at least all the database parameters!

Database installation

The user needs to have full permissions to the database. If not you need to create user and database manually do (or similar on Windows):

(
    echo "CREATE DATABASE flaschengeist;"
    echo "CREATE USER 'flaschengeist'@'localhost' IDENTIFIED BY 'flaschengeist';"
    echo "GRANT ALL PRIVILEGES ON 'flaschengeist'.* TO 'flaschengeist'@'localhost';"
    echo "FLUSH PRIVILEGES;"
) | sudo mysql

Then you can install the database tables and initial entries:

run_flaschengeist install

Run

run_flaschengeist run

or with debug messages:

run_flaschengeist run --debug

This will run the backend on http://localhost:5000

Tests

$ pip install '.[test]'
$ pytest

Run with coverage report:

$ coverage run -m pytest
$ coverage report

Or with html output (open htmlcov/index.html in a browser):

$ coverage html

Development

Code Style

We enforce you to use PEP 8 code style with a line length of 120 as used by Black. See also Black Code Style.

Code formatting

We use Black as the code formatter.

Installation:

pip install black

Usage:

black -l 120 DIRECTORY_OR_FILE

Misc

Git blame

When using git blame use this to ignore the code formatting commits:

$ git blame FILE.py --ignore-revs-file .git-blame-ignore-revs

Or if you just want to use git blame, configure git like this:

$ git config blame.ignoreRevsFile .git-blame-ignore-revs

Ignore changes on config

git update-index --assume-unchanged flaschengeist/flaschengeist.toml

Plugin Development

File Structure

flaschengeist-example-plugin
 |> __init__.py
 |> model.py
 |> setup.py

Files

__init__.py

from flask import Blueprint
from flaschengeist.modules import Plugin

    
example_bp = Blueprint("example", __name__, url_prefix="/example")
permissions = ["example_hello"]

class PluginExample(Plugin):
    def __init__(self, conf):
        super().__init__(blueprint=example_bp, permissions=permissions)

    def install(self):
        from flaschengeist.system.database import db
        import .model
        db.create_all()
        db.session.commit()


@example_bp.route("/hello", methods=['GET'])
@login_required(roles=['example_hello'])
def __hello(id, **kwargs):
    return "Hello"

model.py

Optional, only needed if you need your own models (database)

from flaschengeist.system.database import db


class ExampleModel(db.Model):
    """Example Model"""
    __tablename__ = 'example'
    id = db.Column(db.Integer, primary_key=True)
    description = db.Column(db.String(240))

setup.py

from setuptools import setup, find_packages

setup(
    name="flaschengeist-example-plugin",
    version="0.0.0-dev",
    packages=find_packages(),
    install_requires=[
        "flaschengeist >= 2",
    ],
    entry_points={
        "flaschengeist.plugin": [
            "example = flaschengeist-example-plugin:ExampleModel"
        ]
    },
)