This page documents the coding standards, tools and procedure that the lab applies to its python projects.

Coordinator: Javier Peralta

Contributors: Ariel Mora, Daniel García Vaglio

Note: Most of these sections (specially the tools ones) are meant as a small show case and generally have link to the relevant documentation. Please read this links since the information presented here is not exhaustive nor complete.

Python projects should strictly follow PEP8.

The following tools can aid you to keep your styling on point:

Flake8 is a code checker, it will check python files and raise errors and warnings when code breaks PEP8 or if there is a syntax error.

To install:

apt-get install flake8

Usage:

flake8 path/to/code/

Yet another python formatter (yapf) is a code formatter, a program that reformat code to comply with a style guide (like PEP8 which is the default style). Running this over your python project will clear most PEP8 compliance errors.

To install:

apt-get install yapf3

Usage:

yapf3 -ir path/to/code_dir

or

yapf3 -i path/to/code/file.py

The recommended project layout for a python projected named

ptoject_name

is as follows:

project_name
├── AUTHORS.rst
├── docs
├── examples
│  └── example1.py
├── LICENSE
├── Makefile
├── MANIFEST.in
├── README.rst
├── requirements.dev.txt
├── requirements.txt
├── setup.cfg
├── setup.py
├── src
│  └── package_name
│     ├── __init__.py
│     └── module1.py
├── tests
└── tox.ini

cookiecutter is a command-line utility that creates projects from cookiecutters (project templates). E.g. Python package projects, jQuery plugin projects.

To install:

apt-get install cookiecutter

Arcos template for python is hosted in this repo, to create a new project run:

cookiecutter https://github.com/arcoslab/arcos-python-cookiecutter

after the initial clone you can other new repos refering to the cookicutter by name:

cookiecutter arcos-python-cookiecutter

The lab have some Python 2 repos that need to migrated to Python3. The process will be as follow:

1. Migrate all repos one by one to support both python 2 and 3 from the same file
2. After all repos are migrated we will drop python 2 support for good

For each repo the following process will be applied:

1. An issue to track the repo's migration progress will be opened
2. Open a new py3stage1 branch
3. Using futurize apply stage1 changes to all files
4. Open a pull request and have another member check the changes.
5. Tag the pre-stage1 release so people can easily use that if an issue raises
6. Merge the changes to master, rebase all other branches from master and resolve merge conflicts
7. Test the changes, this is probably going to be manual since most repos have no unit tests. This may be a good time to write some.
8. Open a new py3stage2 branch.
9. Repeat the process for stage1, testing both for python2 and python3
10. Check everything twice
11. Close the issue

Any problems encountered due to migration should be reported with a github issue on the corresponding repo.

To see progress please take a look to the following project tracker on github