Merge branch 'main' into 954-document-how-to-load-plugins-into-docker…

…-container

.github/workflows/build.yml

@@ -50,12 +50,12 @@ jobs:
         run: docker cp prices-tomorrow.csv fm-container:/app/prices-tomorrow.csv
       - name: Add beliefs
         run: docker exec --env-file .env fm-container flexmeasures
-          add beliefs --sensor-id 1 --source toy-user prices-tomorrow.csv --timezone Europe/Amsterdam
+          add beliefs --sensor 1 --source toy-user prices-tomorrow.csv --timezone Europe/Amsterdam
       - name: Export TOMORROW
         run: echo "TOMORROW=$(date --date="next day" '+%Y-%m-%d')"
           >> $GITHUB_ENV
       - name: Add schedule
         run: docker exec --env-file .env fm-container flexmeasures
-          add schedule for-storage --sensor-id 2 --consumption-price-sensor 1 
+          add schedule for-storage --sensor 2 --consumption-price-sensor 1 
           --start ${TOMORROW}T07:00+01:00 --duration PT12H 
           --soc-at-start 50% --roundtrip-efficiency 90%

documentation/changelog.rst

@@ -16,6 +16,8 @@ Infrastructure / Support
 ----------------------
 
 * Deprecate use of flask's ``FLASK_ENV`` variable and replace it with ``FLEXMEASURES_ENV`` [see `PR #907 <https://github.com/FlexMeasures/flexmeasures/pull/907>`_]
+* Streamline CLI option naming by favoring ``--<entity>`` over ``--<entity>-id`` [see `PR #946 <https://github.com/FlexMeasures/flexmeasures/pull/946>`_]
+
 
 Bugfixes
 -----------

documentation/cli/change_log.rst

@@ -4,6 +4,19 @@
 FlexMeasures CLI Changelog
 **********************
 
+since v0.19.0 | February xx, 2024
+=======================================
+
+* Streamline CLI option naming by favoring ``--<entity>`` over ``--<entity>-id``. This affects the following options:
+
+    * ``--account-id`` -> ``--account``
+    * ``--asset-id`` -> ``--asset``
+    * ``--asset-type-id`` -> ``--asset-type``
+    * ``--sensor-id`` -> ``--sensor``
+    * ``--source-id`` -> ``--source``
+    * ``--user-id`` -> ``--user`
+
+
 since v0.18.1 | January 15, 2023
 =======================================
 
@@ -15,7 +28,6 @@ since v0.17.0 | November 8, 2023
 
 * Add ``--consultancy`` option to ``flexmeasures add account`` to create a consultancy relationship with another account.
 
-
 since v0.16.0 | September 29, 2023
 =======================================
 

documentation/dev/docker-compose.rst

@@ -96,7 +96,7 @@ Next, we put a scheduling job in the worker's queue. This only works because we
 
 .. code-block:: bash
 
-    $ flexmeasures add schedule for-storage --sensor-id 2 --consumption-price-sensor 1 \
+    $ flexmeasures add schedule for-storage --sensor 2 --consumption-price-sensor 1 \
         --start ${TOMORROW}T07:00+01:00 --duration PT12H --soc-at-start 50% \
         --roundtrip-efficiency 90% --as-job
 
@@ -113,7 +113,7 @@ We'll not go into the server container this time, but simply send a command:
 .. code-block:: bash
 
     $ TOMORROW=$(date --date="next day" '+%Y-%m-%d')
-    $ docker exec -it flexmeasures-server-1 bash -c "flexmeasures show beliefs --sensor-id 2 --start ${TOMORROW}T07:00:00+01:00 --duration PT12H"
+    $ docker exec -it flexmeasures-server-1 bash -c "flexmeasures show beliefs --sensor 2 --start ${TOMORROW}T07:00:00+01:00 --duration PT12H"
 
 The charging/discharging schedule should be there:
 

documentation/dev/introduction.rst

@@ -132,10 +132,10 @@ Otherwise, you need to add some other user first. Here is how we add an admin:
 
 .. code-block:: bash
     
-    $ flexmeasures add account --name MyCompany   
-    $ flexmeasures add user --username admin --account-id 1 --email admin@mycompany.io --roles admin
+    $ flexmeasures add account --name MyCompany
+    $ flexmeasures add user --username admin --account 1 --email admin@mycompany.io --roles admin
 
-(The account-id you need in the 2nd command is printed by the 1st)
+(The `account` you need in the 2nd command is printed by the 1st)
 
 
 .. note::

documentation/index.rst

@@ -40,11 +40,11 @@ A tiny, but complete example: Let's install FlexMeasures from scratch. Then, usi
     $ export SQLALCHEMY_DATABASE_URI="postgresql://postgres:docker@127.0.0.1:5433/flexmeasures-db" && export SECRET_KEY=notsecret 
     $ flexmeasures db upgrade  # create tables
     $ flexmeasures add toy-account --kind battery  # setup account incl. a user, battery (ID 1) and market (ID 2)
-    $ flexmeasures add beliefs --sensor-id 2 --source toy-user prices-tomorrow.csv --timezone utc  # load prices, also possible per API
-    $ flexmeasures add schedule for-storage --sensor-id 1 --consumption-price-sensor 2 \
+    $ flexmeasures add beliefs --sensor 2 --source toy-user prices-tomorrow.csv --timezone utc  # load prices, also possible per API
+    $ flexmeasures add schedule for-storage --sensor 1 --consumption-price-sensor 2 \
         --start ${TOMORROW}T07:00+01:00 --duration PT12H \
         --soc-at-start 50% --roundtrip-efficiency 90%  # this is also possible per API
-    $ flexmeasures show beliefs --sensor-id 1 --start ${TOMORROW}T07:00:00+01:00 --duration PT12H  # also visible per UI, of course
+    $ flexmeasures show beliefs --sensor 1 --start ${TOMORROW}T07:00:00+01:00 --duration PT12H  # also visible per UI, of course
 
 We discuss this in more depth at :ref:`tut_toy_schedule`.
 

documentation/tut/forecasting_scheduling.rst

@@ -75,7 +75,7 @@ Here we request 6-hour forecasts to be made for two sensors, for a period of two
 
 .. code-block:: bash
 
-    $ flexmeasures add forecasts --sensor-id 2 --sensor-id 3 \
+    $ flexmeasures add forecasts --sensor 2 --sensor 3 \
         --from-date 2015-02-01 --to-date 2015-08-31 \
         --horizon 6 --as-job
 
@@ -131,7 +131,7 @@ A second way to add scheduling jobs is via the CLI, so this is available for peo
 
 .. code-block:: bash
 
-    $ flexmeasures add schedule for-storage --sensor-id 1 --consumption-price-sensor 2 \
+    $ flexmeasures add schedule for-storage --sensor 1 --consumption-price-sensor 2 \
         --start 2022-07-05T07:00+01:00 --duration PT12H \
         --soc-at-start 50% --roundtrip-efficiency 90% --as-job
 

documentation/tut/installation.rst

@@ -163,9 +163,9 @@ Usually, we are here because we want to measure something with respect to our as
 
 .. code-block:: bash
 
-   $ flexmeasures add sensor --name power --unit MW --event-resolution 5 --timezone Europe/Amsterdam --asset-id 1 --attributes '{"capacity_in_mw": 7}'
+   $ flexmeasures add sensor --name power --unit MW --event-resolution 5 --timezone Europe/Amsterdam --asset 1 --attributes '{"capacity_in_mw": 7}'
 
-The asset ID I got from the last CLI command, or I could consult ``flexmeasures show account --account-id <my-account-id>``.
+The asset ID I got from the last CLI command, or I could consult ``flexmeasures show account --account <my-account-id>``.
 
 .. note: The event resolution is given in minutes. Capacity is something unique to power sensors, so it is added as an attribute.
 
@@ -179,7 +179,7 @@ First, you can load in data from a file (CSV or Excel) via the ``flexmeasures``
 
 .. code-block:: bash
    
-   $ flexmeasures add beliefs --file my-data.csv --skiprows 2 --delimiter ";" --source OurLegacyDatabase --sensor-id 1
+   $ flexmeasures add beliefs --file my-data.csv --skiprows 2 --delimiter ";" --source OurLegacyDatabase --sensor 1
 
 This assumes you have a file `my-data.csv` with measurements, which was exported from some legacy database, and that the data is about our sensor with ID 1. This command has many options, so do use its ``--help`` function.
 

documentation/tut/toy-example-expanded.rst

@@ -60,7 +60,7 @@ Setting the data source type to "forecaster" helps FlexMeasures to visually dist
 
     $ flexmeasures add source --name "toy-forecaster" --type forecaster
     Added source <Data source 4 (toy-forecaster)>
-    $ flexmeasures add beliefs --sensor-id 3 --source 4 solar-tomorrow.csv --timezone Europe/Amsterdam
+    $ flexmeasures add beliefs --sensor 3 --source 4 solar-tomorrow.csv --timezone Europe/Amsterdam
     Successfully created beliefs
 
 The one-hour CSV data is automatically resampled to the 15-minute resolution of the sensor that is recording solar production. We can see solar production in the `FlexMeasures UI <http://localhost:5000/sensors/3/>`_ :
@@ -79,7 +79,7 @@ Now, we'll reschedule the battery while taking into account the solar production
 
 .. code-block:: bash
 
-    $ flexmeasures add schedule for-storage --sensor-id 2 --consumption-price-sensor 1 \
+    $ flexmeasures add schedule for-storage --sensor 2 --consumption-price-sensor 1 \
         --inflexible-device-sensor 3 \
         --start ${TOMORROW}T07:00+02:00 --duration PT12H \
         --soc-at-start 50% --roundtrip-efficiency 90%

documentation/tut/toy-example-from-scratch.rst

@@ -24,7 +24,7 @@ To keep it short, we'll only ask for a 12-hour window starting at 7am. Finally,
 
 .. code-block:: bash
 
-    $ flexmeasures add schedule for-storage --sensor-id 2 --consumption-price-sensor 1 \
+    $ flexmeasures add schedule for-storage --sensor 2 --consumption-price-sensor 1 \
         --start ${TOMORROW}T07:00+01:00 --duration PT12H \
         --soc-at-start 50% --roundtrip-efficiency 90%
     New schedule is stored.
@@ -33,7 +33,7 @@ Great. Let's see what we made:
 
 .. code-block:: bash
 
-    $ flexmeasures show beliefs --sensor-id 2 --start ${TOMORROW}T07:00:00+01:00 --duration PT12H
+    $ flexmeasures show beliefs --sensor 2 --start ${TOMORROW}T07:00:00+01:00 --duration PT12H
     Beliefs for Sensor 'discharging' (ID 2).
     Data spans 12 hours and starts at 2022-03-04 07:00:00+01:00.
     The time resolution (x-axis) is 15 minutes.

documentation/tut/toy-example-process.rst

@@ -61,7 +61,7 @@ Now we are ready to schedule a process. Let's start with the INFLEXIBLE policy,
 
 .. code-block:: bash
 
-    flexmeasures add schedule for-process --sensor-id 4 --consumption-price-sensor 1\
+    flexmeasures add schedule for-process --sensor 4 --consumption-price-sensor 1\
       --start ${TOMORROW}T00:00:00+02:00 --duration PT24H --process-duration PT4H \
       --process-power 0.2MW --process-type INFLEXIBLE \ 
       --forbid "{\"start\" : \"${TOMORROW}T15:00:00+02:00\", \"duration\" : \"PT1H\"}"
@@ -72,7 +72,7 @@ Following the INFLEXIBLE policy, we'll schedule the same 4h block using a BREAKA
 
 .. code-block:: bash
 
-    flexmeasures add schedule for-process --sensor-id 5 --consumption-price-sensor 1\
+    flexmeasures add schedule for-process --sensor 5 --consumption-price-sensor 1\
       --start ${TOMORROW}T00:00:00+02:00 --duration PT24H --process-duration PT4H \
       --process-power 0.2MW --process-type BREAKABLE \ 
       --forbid "{\"start\" : \"${TOMORROW}T15:00:00+02:00\", \"duration\" : \"PT1H\"}"
@@ -83,7 +83,7 @@ Finally, we'll schedule the process using the SHIFTABLE policy.
 
 .. code-block:: bash
 
-    flexmeasures add schedule for-process --sensor-id 6 --consumption-price-sensor 1\
+    flexmeasures add schedule for-process --sensor 6 --consumption-price-sensor 1\
       --start ${TOMORROW}T00:00:00+02:00 --duration PT24H --process-duration PT4H \
       --process-power 0.2MW --process-type SHIFTABLE \ 
       --forbid "{\"start\" : \"${TOMORROW}T15:00:00+02:00\", \"duration\" : \"PT1H\"}"

documentation/tut/toy-example-reporter.rst

@@ -44,7 +44,7 @@ Run the command below to show the values for the `grid connection capacity`:
 .. code-block:: bash
 
     $ TOMORROW=$(date --date="next day" '+%Y-%m-%d')
-    $ flexmeasures show beliefs --sensor-id 7 --start ${TOMORROW}T00:00:00+02:00 --duration PT24H --resolution PT1H
+    $ flexmeasures show beliefs --sensor 7 --start ${TOMORROW}T00:00:00+02:00 --duration PT24H --resolution PT1H
       
       Beliefs for Sensor 'grid connection capacity' (ID 7).
         Data spans a day and starts at 2023-08-14 00:00:00+02:00.

documentation/tut/toy-example-setup.rst

@@ -20,7 +20,7 @@ Below are the ``flexmeasures`` CLI commands we'll run, and which we'll explain s
     # setup an account with a user and an energy market (ID 1)
     $ flexmeasures add toy-account
     # load prices to optimise the schedule against
-    $ flexmeasures add beliefs --sensor-id 1 --source toy-user prices-tomorrow.csv --timezone Europe/Amsterdam
+    $ flexmeasures add beliefs --sensor 1 --source toy-user prices-tomorrow.csv --timezone Europe/Amsterdam
 
 
 Okay, let's get started!
@@ -255,7 +255,7 @@ This is time series data, in FlexMeasures we call *"beliefs"*. Beliefs can also
 
 .. code-block:: bash
 
-    $ flexmeasures add beliefs --sensor-id 1 --source toy-user prices-tomorrow.csv --timezone Europe/Amsterdam
+    $ flexmeasures add beliefs --sensor 1 --source toy-user prices-tomorrow.csv --timezone Europe/Amsterdam
     Successfully created beliefs
 
 In FlexMeasures, all beliefs have a data source. Here, we use the username of the user we created earlier. We could also pass a user ID, or the name of a new data source we want to use for CLI scripts.
@@ -266,7 +266,7 @@ Let's look at the price data we just loaded:
 
 .. code-block:: bash
 
-    $ flexmeasures show beliefs --sensor-id 1 --start ${TOMORROW}T00:00:00+01:00 --duration PT24H
+    $ flexmeasures show beliefs --sensor 1 --start ${TOMORROW}T00:00:00+01:00 --duration PT24H
     
     Beliefs for Sensor 'day-ahead prices' (ID 1).
     Data spans a day and starts at 2022-03-03 00:00:00+01:00.