eflips-model 1.1.3

A common data model for the eflips family of electric vehicle simulation & optimization tools.

eflips-model

This repository contains both the reference specification and an SQLALchemy implementation of the eFLIPS database.

Reference Specification

The reference specification is located (for now) in the huge PDF file schema.pdf. It is a UML diagram of the database schema. The diagram was created using OmniGraffle (proprietary).

SQLAlchemy Implementation

The SQLAlchemy implementation is located in the eflips/model directory. It is a Python package that contains the SQLAlchemy models and the database migration scripts. The package is structured as follows:

Installation

Releases of the package will be made available on https://pypi.org/. As such, it is installable with pip install eflips-model. However, it should be used by including it in other packages as a dependency. The versioning scheme is semantic versioning. This means that:

• patch releases (e.g. 1.0.0 to 1.0.1) are backwards compatible bug fixes, without schama changes
• minor releases (e.g. 1.0.0 to 1.1.0) are backwards compatible feature additions, with the schema changes being optional
• major releases (e.g. 1.0.0 to 2.0.0) are backwards incompatible changes, with the schema changes being mandatory

Supported database backends are

• PostgreSQL with the PostGIS extension and btree_gist (CREATE EXTENSION btree_gist;)

Usage

This package is not expected to be used directly. It is a dependency of the eflips-* packages.

This package utilizes GIS extensions through GeoAlchemy. However, we are not handling geometry on the python side in any special way. You will probably additionally need Shapely and pyProj, which are not pure python packages and require additional dependencies to be installed on the system.

Documentation

The documentation is generated using sphinx. To generate the documentation, execute the following command in the root directory of the repository:

sphinx-build doc/ doc/_build -W

Development

We utilize the GitHub Flow branching structure. This means that the main branch is always deployable and that all development happens in feature branches. The feature branches are merged into main via pull requests. We utilize the semantic versioning scheme for versioning.

Dependencies are managed using poetry. To install the dependencies, execute the following command in the root directory of the repository:

poetry install

We use black for code formatting. You can use black . to format the code.

We use MyPy for static type checking. You can use mypy --strict --explicit-package-bases eflips/ to run MyPy on the code.

Please make sure that your poetry.lock and pyproject.toml files are consistent before committing. You can use poetry check to check this. This is also checked by pre-commit.

You can use pre-commit to ensure that MyPy, Black, and Poetry are run before committing. To install pre-commit, execute the following command in the root directory of the repository:

We recommend utilizing linters such as PyLint for static code analysis (but not doing everything it says blindly).

Testing

We use pytest for testing. The tests are located in the tests directory. To run the tests, execute the following command in the root directory of the repository (after installing the dev dependencies):

---

NOTE: Be aware that the tests will clear the database specified in the DATABASE_URL environment variable. Make sure that you are not using a database that you want to keep.

---

# Change to your database URL
export DATABASE_URL=postgresql://user:pass@hostname:port/dbname 
pytest

License

This project is licensed under the AGPLv3 license - see the LICENSE file for details.