Contributing

To contribute to the braincube_connector project, please make use of the following tools.

Contribute to :

The project
The development

Project Contribution:

Code of conduct

All contributors are expecting to abide by our Code of Conduct.

Opening Issues

Before opening an issue, please follow those steps:

Search existing issues for your problem.
Update your Braincube-Connector.

Finally, if you are up to date, supported, have collected information about the problem, and have the best reproduction instructions you can give, you are ready to open an issue:

Fill out the provided issue template.
Describe your problem, not your solution.
Explain how to reproduce the issue.

Update Version

Please ensure you use the latest version of the connector before filling an issue. Here is the command to use to update the connector if you installed it with pip:

pip install braincube_connector -U

Development Contribution:

Install

The project uses poetry to manage the configuration and the package building.

To install braincube_connector run

poetry install

This will install all the project dependencies. To run a command within the project virtual environment run

$ poetry run <command>
# or
$ poetry shell
(.venv) $ <command>

Next it is recommended to install the git hooks so that several tests are run before each commit:

poetry run pre-commit install -t pre-commit -t pre-push

pre-commit runs the continuous integration tests before a commit or a push depending on the configuration.
You can manually run the configured tests with poetry run pre-commit run --all-files

Note: pre-commit behavior is configured within the .pre-commit-config.yaml

Style

The code style is fixed with the black library:

black braincube_connector

The overall quality is checked with the flake8 and several extensions provided by the wemake-python-styleguide package.

flake8 braincube_connector

flake8 has a few parameters set: max-line-length = 100, inline-quotes = "

A few violations could not be fixed and were ignored in the .flake8 file:

I001 isort found an import in the wrong position → Incompatible with WPS318, WPS319, and black.
I002: no configuration found (.isort.cfg or [isort] in configs)
DAR401: Missing exception(s) in Raises section: -r KeyError
WPS326: Found implicit string concatenation → Incompatible with black
C812, 815: missing trailing comma → Incompatible with black
D100: Missing docstring in public module
RST: Ignore rst format related warnings. → Incompatible with **kwargs gets confused with **title in rst format. Removing this warning has no effect since we are using markdown.

docstring style

The braincube_connector project uses the google docstring styles:

def function(val: int) -> int:
    """ Description of the functions.

    Args:
        val: val parameter.

    Return:
        a multiplication of val.
    """
    return 2*val

Type hint

Since python 3.5, there is the possibility to use the type hints on the function definitions. It should help detect an important number errors and enforce better practice so we decided to incorporate it in the project.

The consistence of the type hints is checked with mypy:

mypy braincube_connector/

Test

The test suite rely on the to libraries pytest and pytest_mock.

To run the tests, simply run the following command:

poetry run pytest tests/*

To ease development phase, we use pytest-watch. You can run it like this :

poetry run ptw --config pytest-watch.conf.ini

Once running, you can edit files, and tests will be run when you save your file.

Continuous integration (CI)

At every push on the project the CI executes a set of action defined in the .github/workflows/ci.yml script.

Setup project environment (with poetry)
Check the type hint consistency (with mypy)
Fix the code style (with black)
Check the style (with flake8)
Run the test suite (with pytest)