echo-postgres¶

Package used to interact with performance PostgreSQL database (performance_db).

Installation¶

This package can be installed using pip running the following command. It will also install other Echoenergia packages just to make sure that all dependencies are met.

uv pip install -r https://raw.githubusercontent.com/performance-echo/.github/main/echo_packages.txt

Note

The command above uses uv for faster installs. If you don't have it installed, install it using pip install uv. After that you can always use uv pip for faster installs than regular pip.
This command assumes that you are logged into GitHub. If you are not, please do gh auth login and follow the instructions before running the command above.

Documentation¶

The documentation of this module is available at echo-postgres.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.

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.

Usage¶

From version 2.0 onwards there is only one top level class that should be imported to use the functionalities of this package. The class is called PerfDB and should be imported as shown below.

from echo_postgres import PerfDB

If by any means you need to import the entire package, it is recommended to call it e_pg for consistency. Below is an example of how to do it.

import echo_postgres as e_pg

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.

{
    "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:
```
pytest
```
Using the command line to run a specific test:
```
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.

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

Improvements¶

Improvements to the package are highly encouraged! As more people work here the better functionality we will have. Regardless of that, please follow the rules below when updating or adding new functionality:

Type Hints: For all methods and classes, use type hints to make it easier to understand what the input and output types are. This is extremely important for the user to understand how to use the package.

It's also extremely recommended that you use Pydantic's validate_call decorator to validate the input types, ensuring that the user is passing the right types to the methods. This will make it easier to debug as we catch the errors earlier in the process, avoiding unnecessary manual type checking and improving code robustness.

Docstrings: For every method or class, keep a well documented docstring. This is extremely important for the user to understand how to use the package.
Documentation: Add or update the documentation present in the docs folder, giving enough explanation and examples to make it very clear to understand how the methods work and how to use them. Also validate if the documentation is nicely formatted using mkdocs serve -a localhost:8111 before pushing changes.
Add/Edit Tests: Add or update unit tests present in the tests folder in a way that they are able to identify if the functionality is working as expected.
Run Tests: Run all the tests present in the tests folder to make sure that the new functionality is working as expected and did not break any existing functionality.
: Version: Update de version number of the package in the file pyproject.toml following the Semantic Versioning rules. The version number should be updated in the format major.minor.patch, where:
major is incremented when there are breaking changes in the package.
minor is incremented when new functionality is added to the package.
patch is incremented when bug fixes are made to the package.

For example, if you are adding a new functionality to the package, you should update the version number from 1.0.0 to 1.1.0. If you are fixing a bug, you should update it from 1.1.0 to 1.1.1. If you are making a breaking change, you should update it from 1.1.1 to 2.0.0. 7. Changelog: Write in more details what has been changed in the CHANGELOG file following the existing pattern. 8. Commit: Commit your changes to GitHub.