Skip to main content

ewx-public

ewx-public is the public Python API for writing custom rules. Installing it locally gives you type hints, IDE autocompletion, and the ewx_public.testing module to unit-test rules on your machine before uploading them to the platform.

This page covers installation only. For what to do next:

Prerequisites​

  • Python (see the version range on this page)
  • The gcloud CLI
  • A Google Account with access to the python-shared repository in the ewx-global Artifact Registry project. Ask Service Desk to grant it if you do not have it yet.

Authenticate once per machine:

gcloud auth application-default login

ewx-public is pinned to Python 3.11, the version the platform executes rules with. Give it its own virtual environment; the other shareable packages run on newer Python versions.

Installation​

The examples pin ewx-public to 26.8.0, the version that matches platform release 26.08. Replace it with the version matching your environment, see Versioning. Python 3.11 only; the examples use 3.11.

Install with pip

mkdir my_ewx_rules
cd my_ewx_rules
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install keyring keyrings.google-artifactregistry-auth
pip install \
  --index-url https://europe-west1-python.pkg.dev/ewx-global/python-shared/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  ewx-public==26.8.0

Install with uv

Use this pyproject.toml as a starting point:

pyproject.toml
[project]
name = "my-ewx-rules"
version = "0.1.0"
description = "Local rule development project for Energyworx."
requires-python = ">=3.11,<3.12"
dependencies = [
  "ewx-public==26.8.0",
]

[dependency-groups]
dev = [
  "pytest>=8.0",
]

[tool.uv]
package = false

[[tool.uv.index]]
name = "ewx-global"
url = "https://europe-west1-python.pkg.dev/ewx-global/python-shared/simple/"
explicit = true

[tool.uv.sources]
ewx-public = { index = "ewx-global" }

Then resolve and install:

gcloud auth application-default login
export UV_INDEX_EWX_GLOBAL_USERNAME=oauth2accesstoken
export UV_INDEX_EWX_GLOBAL_PASSWORD="$(gcloud auth print-access-token)"
uv sync --python 3.11

The access token expires after an hour. Re-run the UV_INDEX_EWX_GLOBAL_PASSWORD assignment when uv sync reports an authorization error.

Testing module availability

ewx_public.testing (factories, make_testable, assertion helpers) ships from platform release 26.05, package version 26.5.0. Environments on an older release can still use ewx-public for type hints, but not the testing utilities.

Verify the installation​

python -c "import ewx_public; print(ewx_public.__name__)"

The command prints ewx_public without an error.

Installation issues​

SymptomCause and fix
401/403 or Authorization error from pkg.devYour Google Account is not authenticated or has no access to the repository. Re-run gcloud auth application-default login; if it persists, ask Service Desk to check your access. With uv, re-export UV_INDEX_EWX_GLOBAL_PASSWORD, the token expires after an hour.
No matching distribution or doesn't match any versionspip is not looking at the Energyworx index (check --index-url) or the pinned version does not exist. Pins follow the platform release, see Versioning; 2.x versions are no longer published.
keyring backend not foundInstall keyring keyrings.google-artifactregistry-auth in the same environment before running pip install against the index.
Activate.ps1 cannot be loaded (Windows)Run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned once and reopen PowerShell.
Plugin not loaded in pytestConfirm pytest-bdd-ewx is installed in the active environment (pip show pytest-bdd-ewx).

If the problem persists, contact Service Desk with the full command, the full error output, your Python version and whether you use pip or uv.

Next steps​