Pip-installable

.gitignore

@@ -1,3 +1,6 @@
+build
+dist
+
 raw_data
 instance
 venv

Developing.md

@@ -21,11 +21,28 @@ Install all dependencies including the ones needed for development:
 
     make install-for-dev
 
+## Configuration
+
+Follow the confguration Quickstart advice in `Installation.md`.
+
+
+## Loading data
+
+If you have a SQL Dump file, you can load that:
+
+    psql -U {user_name} -h {host_name} -d {database_name} -f {file_path}
+
+
+
 ## Run locally
 
 Now, to start the web application, you can run:
 
-    python flexmeasures/run-local.py
+    flexmeasures run
+
+Or:
+
+    python run-local.py
 
 And access the server at http://localhost:5000
 
@@ -47,3 +64,16 @@ You can add --cov-report=html after which a htmlcov/index.html is generated.
 It's also possible to use:
 
     python setup.py test
+
+
+## Versioning
+
+We use [setuptool_scm](https://github.com/pypa/setuptools_scm/) for versioning, which bases the FlexMeasures version on the latest git tag and the commits since then.
+
+So as a developer, it's crucial to use git tags for versions only.
+
+We use semantic versioning, and we always include the patch version, not only max and min, so that setuptools_scm makes the correct guess about the next minor version. Thus, we should use `2.0.0` instead of `2.0`.
+
+See `to_pypi.sh` for more commentary on the development versions.
+
+Our API has its own version, which moves much slower. This is important to explicitly support outside apps who were coded against older versions. 

Installation.md

@@ -1,76 +1,139 @@
-# Building & Running FlexMeasures
+# Installing & Running FlexMeasures
 
 
-## Dependencies
+## Install FlexMeasures
 
 Install dependencies and the `flexmeasures` platform itself:
 
-      make install
+    pip install flexmeasures
 
-## Configure environment
 
-* Set an env variable to indicate in which environment you are operating (one out of development|testing|staging|production), e.g.:
+## Quickstart: database, one user & one asset
 
-    `echo "FLASK_ENV=development" >> .env`
+### Preparing the time series database
 
-    `export FLASK_ENV=production`
-* If you need to customise settings, create `flexmeasures/<development|testing|staging|production>_config.py` and add required settings.
-  If you're unsure what you need, just continue for now and the app will tell you what it misses.
+* Make sure you have a Postgres (Version 9+) database for FlexMeasures to use. See `data/Readme.md` for instructions on this.
+* Tell `flexmeasures` about it:
 
-## Make a secret key for sessions
+    `export SQLALCHEMY_DATABASE_URI='postgresql://<user>:<password>@<host-address>[:<port>]/<db>'`
+
+  (on Windows, use `set` instead of `export`)
+* Create the Postgres DB structure for FlexMeasures:
 
-    mkdir -p /path/to/flexmeasures/instance
-    head -c 24 /dev/urandom > /path/to/flexmeasures/instance/secret_key
+    `flexmeasures db upgrade`
 
-## Preparing the time series database
+Note that for a more permanent configuration, you can create your FlexMeasures configuration file at `~/.flexmeasures.cfg`.
+TODO: the configuration file can also be in the Flask instance directory.
 
-* Make sure you have a Postgres (Version 9+) database. See `data/Readme.md` for instructions on this.
-* Tell `flexmeasures` about it. Either you are using the default for the environment you're in (see `flexmeasures/utils/config_defaults`),
-   or you can configure your own connection string: In `flexmeasures/<development|testing|staging|production>_conf.py`,
-  set the variable `SQLALCHEMY_DATABASE_URI = 'postgresql://<user>:<password>@<host-address>[:<port>]/<db>'`
-* Run `flask db upgrade` to create the Postgres DB structure.
 
-## Preparing the job queue database
+### Configure environment
 
-To let FlexMeasures queue forecasting and scheduling jobs, install a Redis server and configure access to it within FlexMeasures' config file (see above). You can find the default settings in `flexmeasures/utils/config_defaults.py`.
+Set an environment variable to indicate in which environment you are operating (one out of development|testing|staging|production), e.g.:
 
-TODO: more detail
+   `echo "FLASK_ENV=development" >> .env`
 
-## Install an LP solver
+or:
 
-For planning balancing actions, the flexmeasures platform uses a linear program solver. Currently that is the Cbc solver. See the `FLEXMEASURES_LP_SOLVER` config setting if you want to change to a different solver.
+   `export FLASK_ENV=development`
 
-Installing Cbc can be done on Unix via:
+(on Windows, use `set` instead of `export`)
 
-    apt-get install coinor-cbc
+Note: The default is `production`, which will not work well on localhost due to SSL issues. 
 
-(also available in different popular package managers).
 
-We provide a script for installing from source (without requiring `sudo` rights) in [the CI Readme](ci/Readme.md).
+### Make a secret key for sessions and password salts
+
+Set a secret key which is used to sign user sessions and re-salt their passwords. The simplest way is again with an environment variable, like this:
+
+   `export "SECRET_KEY=something-secret"`
+
+(on Windows, use `set` instead of `export`)
+
+Actually, we recommend you add this setting to your config file (see above). Here is a Pythonic way to generate good random string for this:
+
+    `python -c "import secrets; print(secrets.token_urlsafe())"`
+
+
+### Add a user
 
-More information (e.g. for installing on Windows) on [the website](https://projects.coin-or.org/Cbc).
+FlexMeasures is a web-based platform, so we need a user account:
 
+`flexmeasures --username <your-username> --email <your-email-address>`
 
-## Run
+(this will ask you to set a password for the user)
 
-Now, to start the web application, you can run:
 
-    python flexmeasures/run-local.py
+### Add structure
 
-But in a production context, you shouldn't run a script - hand the `app` object to a WSGI process, as your platform of choice describes.
+Populate the database with some standard energy asset types:
+
+   `flexmeasures db_populate --structure`
+
+
+### Run FlexMeasures
+
+It's finally time to start running FlexMeasures:
+
+`flexmeasures run`
+
+(This might print some warnings, see the next section where we go into more detail)
+
+Note that in a production context, you shouldn't run a script - hand the `app` object to a WSGI process, as your platform of choice describes.
 
 Often, that requires a WSGI script. We provide an example WSGI script in [the CI Readme](ci/Readme.md).
 
 
-## Loading data
+### Add your first asset 
+
+Head over to `http://localhost:5000/assets` and add a new asset there.
+
+TODO: [issue 57](https://github.com/SeitaBV/flexmeasures/issues/57) should create a CLI function for this.
+
+Note: You can also use the [`POST /api/v2_0/assets`](https://flexmeasures.readthedocs.io/en/latest/api/v2_0.html#post--api-v2_0-assets) endpoint in the FlexMeasures API to create an asset.
+
+### Add data
+
+You can use the [`POST /api/v2_0/postMeterData`](https://flexmeasures.readthedocs.io/en/latest/api/v2_0.html#post--api-v2_0-postMeterData) endpoint in the FlexMeasures API to send meter data.
 
-If you have a SQL Dump file, you can load that:
+TODO: [issue 56](https://github.com/SeitaBV/flexmeasures/issues/56) should create a CLI function for adding a lot of data at once, from a CSV dataset.
 
-    psql -U {user_name} -h {host_name} -d {database_name} -f {file_path}
+Also, you can add forecasts for your meter data with the `db_populate` command, here is an example:
+
+   `flexmeasures db_populate --forecasts --from-date 2020-03-08 --to-date 2020-04-08 --asset-type Asset --asset my-solar-panel `
+
+Note: You can also use the API to send forecast data.
+
+
+## Other settings, for full functionality
+
+### Set mail settings
+
+For FlexMeasures to be able to send email to users (e.g. for resetting passwords), set MAIL_* settings. `flexmeasures run` should tell you which ones you need.
+
+
+### Preparing the job queue database
+
+To let FlexMeasures queue forecasting and scheduling jobs, install a Redis server and configure access to it within FlexMeasures' config file (see above). You can find the necessary settings in `flexmeasures/utils/config_defaults.py`.
+
+When forecasts are generated they should be visible at `http://localhost:5000/analytics` but you can also access them via the FlexMeasures API at [GET  /api/v2_0/getPrognosis](https://flexmeasures.readthedocs.io/en/latest/api/v2_0.html#get--api-v2_0-getPrognosis).
+
+TODO: more detail
+
+
+### Install an LP solver
+
+For planning balancing actions, the flexmeasures platform uses a linear program solver. Currently that is the Cbc solver. See the `FLEXMEASURES_LP_SOLVER` config setting if you want to change to a different solver.
+
+Installing Cbc can be done on Unix via:
+
+    apt-get install coinor-cbc
+
+(also available in different popular package managers).
+
+We provide a script for installing from source (without requiring `sudo` rights) in [the CI Readme](ci/Readme.md).
 
-Else, you can populate some standard data, most of which comes from files:
+More information (e.g. for installing on Windows) on [the Cbc website](https://projects.coin-or.org/Cbc).
 
-* Finally, run `flask db_populate --structure --data --small` to load this data into the database.
-  The `--small` parameter will only load four assets and four days, so use this first to try things out. TODO: check which command is possible at the moment. Also add a TODO saying where we want to go with this (support for loading data).
+When schedules are generated they should be visible at `http://localhost:5000/analytics` but you can also access them via the FlexMeasures API at [GET  /api/v2_0/getDeviceMessage](https://flexmeasures.readthedocs.io/en/latest/api/v2_0.html#get--api-v2_0-getDeviceMessage).
 
 

Makefile

@@ -6,7 +6,7 @@
 # ---- Development ---
 
 run-local:
-	python flexmeasures/run-local.py
+	python run-local.py
 
 test:
 	make install-for-dev

NOTICE

@@ -1,7 +1,3 @@
 FlexMeasures
-Copyright 2018 Seita Energy Flexibility
+Copyright 2018-2021 Seita Energy Flexibility
 Apache 2.0 license
-
-Sphinx RTD Theme (see documentation/_themes/sphinx_rtd_flexmeasures_theme)
-Copyright 2010-2021 Dave Snider, Read the Docs, Inc., FontAwesome, Łukasz Dziedzic, The Modernizr Team, Google Inc., Seita Energy Flexibility
-MIT license, BSD license, SIL Open Font license 1.1, Apache2.0 license

documentation/changelog.rst

@@ -3,6 +3,14 @@ FlexMeasures Changelog
 **********************
 
 
+v0.2.4 | March XX, 2021
+===========================
+
+Infrastructure / Support
+----------------------
+* FlexMeasures can be installed with `pip` and CLI commands can be run with `flexmeasures` [see `PR #54 <http://www.github.com/SeitaBV/flexmeasures/pull/54>`_]
+
+
 v0.2.3 | February 27, 2021
 ===========================
 
@@ -21,7 +29,7 @@ Bugfixes
 * Password reset link on account page was broken [see `PR #23 <http://www.github.com/SeitaBV/flexmeasures/pull/23>`_]
 
 
-Infrastructure/Support
+Infrastructure / Support
 ----------------------
 * CI via Github Actions [see `PR #1 <http://www.github.com/SeitaBV/flexmeasures/pull/1>`_]
 * Integration with `timely beliefs <https://github.com/SeitaBV/timely-beliefs>`__ lib: Sensors [see `PR #13 <http://www.github.com/SeitaBV/flexmeasures/pull/13>`_]

documentation/conf.py

@@ -6,31 +6,26 @@
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/stable/config
 
-import os
-import sys
 from datetime import datetime
+from pkg_resources import get_distribution
 
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 
-# Insert FlexMeasures' path into the system.
-sys.path.insert(0, os.path.abspath(".."))
-from flexmeasures import __version__  # noqa: E402
-
 
 # -- Project information -----------------------------------------------------
 
 project = "FlexMeasures"
 copyright = f"{datetime.now().year}, Seita Energy Flexibility, developed in partnership with A1 Engineering, South Korea"
 author = "Seita B.V."
 
-# The short X.Y version
-version = __version__
 # The full version, including alpha/beta/rc tags
-release = __version__
+release = get_distribution("flexmeasures").version
+# The short X.Y.Z version
+version = ".".join(release.split(".")[:3])
 
 rst_prolog = """
 """

flexmeasures/__init__.py

@@ -1 +1,12 @@
-__version__ = "0.3.2"
+from importlib_metadata import version, PackageNotFoundError
+
+
+__version__ = "Unknown"
+
+# This uses importlib.metadata behaviour added in Python 3.8
+# and relies on setuptools_scm.
+try:
+    __version__ = version("flexmeasures")
+except PackageNotFoundError:
+    # package is not installed
+    pass

flexmeasures/api/__init__.py

@@ -4,6 +4,7 @@
 from flask_json import as_json
 from flask_login import current_user
 
+from flexmeasures import __version__ as flexmeasures_version
 from flexmeasures.data.models.user import User
 from flexmeasures.api.common.utils.args_parsing import (
     FMValidationError,
@@ -75,6 +76,7 @@ def get_versions() -> dict:
         "/api/v1/getService and /api/v1_1/getService. An authentication token can be requested at: "
         "/api/requestAuthToken",
         "versions": ["v1", "v1_1", "v1_2", "v1_3", "v2_0"],
+        "flexmeasures_version": flexmeasures_version,
     }
     return response