echo-dataimporter¶

Package to import data from multiple sources

Installation¶

This package can be installed using pip by following the latest instructions on the main README of the Performance Echo organization in GitHub.

Documentation¶

The documentation of this module is available at echo-dataimporter.pages.dev. It uses the mkdocs tool alongside mkdocs-material and mkdocstrings to generate a static website with all the information needed to use the package. All relevant configuration files are present in mkdocs.yml and the documentation files are in the docs folder.

To see the documentation while developing the package, run the command below and open the browser at the address http://localhost:8111. You can change the port if needed.

Bash

mkdocs serve -a localhost:8111

When pushing changes to the repository, the documentation will be automatically updated in Cloudfare Pages due to the connection configured in Cloudflare. This way, you don't need to worry about updating the documentation when pushing changes to the repository. The process of configuring the connection in Cloudflare Pages is explained in this link, but there are details were considered:

The deployment uses Cloudflare credentials bruno.macedo@echoenergia.com.br and 1cY&l@EZTx6e9d.
Add the requirements-cloudflare.txt file to the repository, containing the dependencies needed to build the documentation
Change the build command to pip install -r requirements-cloudflare.txt && mkdocs build
To avoid Cloudflare trying to install the requirements from the requirements.txt file, you should add environment variable SKIP_DEPENDENCY_INSTALL with the value 1 to the build settings.
Add the values below in the extra field of the mkdocs.yml file to avoid the page being indexed by search engines like Google and Bing.
YAML
```
extra:
  meta:
    - name: robots
      content: noindex
```
Specify the Python version to be used in the Cloudflare Pages build settings by adding .python-version file to the root of the repository. Don't forget to remove any mentions to this file in .gitignore file.

Testing¶

Pytest¶

Configuration¶

To tell VS Code to use pytest as the testing framework, its recommended that you add the following configuration to the settings.json file in the .vscode folder of your project.

JSON

{
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.autoTestDiscoverOnSaveEnabled": false,
}

Running Tests¶

Several pre-defined tests are configured in the tests/auto folder using pytest. There ae severeal ways to run these tests, like:

Using the command line, running:
Bash
```
pytest
```
Using the command line to run a specific test:
Bash
```
pytest -k <test_name>
```
Through the Visual Studio Code testing module. To do so, just open the icon on the left side of the screen that looks like a test tube and run or debug the tests using pytest.
Using the _run_pytest.py script, which is a convenience script that you can just run. In it you should specify the test you want to run. This is the best way to debug tests if you need to.

Warning

Keep in mind that the pre-configured tests in this file assumes that you have connectivity to the Performance server, so they will fail if you are not in Echo VPN.

Local installation¶

During development the package can be installed from the local repository using the command below.

Bash

uv pip install . --no-deps --reinstall --no-cache

Pre-commit hooks¶

This repository uses pre-commit to run a set of checks on every commit. The configuration lives in .pre-commit-config.yaml and includes:

General checks: YAML/TOML validity, large files, merge conflicts, debug statements, private keys, case conflicts, end-of-file / trailing whitespace.
ruff for linting (with --fix) and formatting.
mdformat for Markdown formatting (with the mkdocs, gfm, and frontmatter plugins so it understands mkdocs-material syntax).
validate-pyproject and pyproject-fmt for pyproject.toml.
actionlint for the GitHub Actions workflows.
A local hook that runs mkdocs build --strict whenever mkdocs.yml, files in docs/, or Python source files change — fails the commit on any docs warning (broken links, missing pages, bad references).

To set it up locally (only needed once per clone):

Bash

uv pip install pre-commit
pre-commit install

To run all hooks against the whole repo (useful after pulling config changes):

Bash

pre-commit run --all-files

Note

The mkdocs build --strict hook uses language: system, meaning it runs mkdocs from your active environment. Make sure the dev extras from pyproject.toml are installed (uv pip install ".[dev]").

Auto-tagging¶

Every push to main triggers the .github/workflows/tag-version.yml workflow, which reads the project.version field from pyproject.toml and creates (or force-moves) a git tag with that exact value (e.g. 4.2.1). This means:

If the version was bumped in the commit, a new tag is created.
If the version was not bumped, the existing tag is moved to the new commit.

This removes the need to manually run git tag / git push --tags after each release. The version bump in pyproject.toml is the single source of truth for the released tag.

AI¶

Instructions for AI agents are written in the CLAUDE.md file. This file is also symlinked to copilot-instructions.md to be easily accessible for GitHub Copilot. If you are an AI agent, please read the CLAUDE.md file before doing any task related to this repository.

Bash

# symlink command
ln -s ../CLAUDE.md .github/copilot-instructions.md