Skip to main content

Local Rule Development

Rules are Python code blobs stored in a rule configuration on the platform. You can write them in the console's code editor, but for anything beyond a few lines it pays to develop them locally: with the ewx-public package installed you get type hints and autocompletion for the rule framework, you can unit-test a rule in seconds without touching a namespace, and the code lives in git.

This page describes that loop. Each step links to the page that covers it in depth.

1. Set up a project​

Install ewx-public following the ewx-public package page. It needs Python 3.11, the version the platform runs rules with, so give it its own virtual environment.

A project that works well with both the platform and pytest looks like this:

my-ewx-rules/
├── pyproject.toml          # ewx-public pinned to your platform release, pytest in the dev group
├── src/rules/
│   ├── unit_conversion.py  # one rule class per file
│   └── normalize.py
└── tests/
    ├── conftest.py
    ├── test_unit_conversion.py
    └── test_normalize.py

Keep one rule class per file under src/rules/. The content of that file is exactly what you paste into the rule configuration's code blob, so it must not import anything from the rest of your project; only from ewx_public, the standard library and the packages available on the platform such as pandas. The ewx-public package ships this layout as a complete working project in its examples/my-ewx-rules/ directory.

2. Write the rule​

Pick the base class for the job and write the rule in your IDE:

The ewx-public Package page lists every class the package exports and maps the legacy energyworx imports onto the new ones.

3. Test it locally​

The ewx_public.testing module wraps your rule with an in-memory backend, so a test creates the rule with factory-made data, runs it, and asserts on what it stored, tagged, triggered or logged, with no mocks and no platform access. Run the suite with pytest tests/ -v.

Unit Testing Rules is the tutorial: your first test, factories, assertion helpers, seeding data for lookups, testing error paths and transform rules, and moving off MagicMock. The ewx-public Package page is the reference of every factory, assertion and stub.

4. Upload it​

Once the tests pass, get the code onto the platform:

  • Console: open the rule configuration and paste the file into the code blob. See Rule configurations for the fields, in particular the technical name, which must match the class name.
  • ewx-cli: keep the rule configurations in a directory alongside your project and release them with ewx-cli config upload, which resolves dependencies, shows the plan and records the upload so it can be rolled back. See Managing configurations.

The platform caches rule code for a while after an upload; on a development namespace, lower rule_cache_ttl to see changes immediately. See Namespace Properties.

5. Iterate​

Change the rule, run the tests, upload again. Because the tests run against the in-memory backend, a failing case found in production can usually be turned into a unit test first and fixed locally, then uploaded once.