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.toml`file, 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](https://github.com/psf/black/blob/main/docs/the_black_code_style/current_style.md).

#### Code formatting
We use [Black](https://github.com/psf/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"
            ]
        },
    )