Coding guide ¶

Committing changes ¶

When committing changes to AbiPy, there are a few things to bear in mind.

if your changes are non-trivial, please make an entry in the CHANGELOG.rst Note that the changelog is written following the format employed by the releases Sphinx extension.
if you change the API, please document the modifications in the docstring with the versionadded role:
```
.. versionadded:: 0.2
   Add new argument ``foobar``
```
Can you pass the automatic tests?
Can you add a test to test your changes?
If you have added new files or directories, or reorganized existing ones, are the new files included in the match patterns in MANIFEST.in. This file determines what goes into the source distribution of the build.

Importing and name spaces ¶

For numpy, use:

import numpy as np
a = np.array([1,2,3])

For matplotlib, avoid using the high-level interface such as in:

import matplotlib.pyplot as plt
plt.plot(x, y)

and use the object-oriented API provided by matplotlib.axes.Axes:

from abipy.tools.plotting import get_ax_fig_plt
ax, fig, plt = get_ax_fig_plt(ax=None)
ax.plot(x, y)

It is recommended to pass the Axes ax to the plotting method and use the decorator add_fig_kwargs:

@add_fig_kwargs
def plot(self, ax=None, **kwargs):
    """
    Plot the object ...

    Args:
        ax: |matplotlib-Axes| or None if a new figure should be created.

    Returns: |matplotlib-Figure|
    """
    ax, fig, plt = get_ax_fig_plt(ax=ax)
    ax.plot(self.xvals, self.yvalsm, **kwargs)
    return fig

Naming, spacing, and formatting conventions ¶

In general, we want to stay as closely as possible to the standard coding guidelines for python written by Guido van Rossum in PEP0008.

functions and class methods: lower or lower_underscore_separated
attributes and variables: lower
classes: Upper or MixedCase

Prefer the shortest names that are still readable.

Configure your editor to use spaces, not hard tabs. The standard indentation unit is always four spaces; if there is a file with tabs or a different number of spaces it is a bug – please fix it.

Keep docstrings uniformly indented as in the example below, with nothing to the left of the triple quotes.

Limit line length to (around) 90 characters. If you wonder why we are violating pep8 that specifies a maximum line length of 79 characters, check out this video by Raymond Hettinger:

If a logical line needs to be longer, use parentheses to break it; do not use an escaped newline. It may be preferable to use a temporary variable to replace a single long line with two shorter and more readable lines.

Please do not commit lines with trailing white space, as it causes noise in diffs.

Writing examples ¶

We have examples in subdirectories of abipy/examples, and these are automatically generated when the website is built to show up both in the examples and gallery sections of the website.

Many people find these examples from the website, and do not have ready access to the examples directory in which they reside. Thus any example data that is required for the example should be added to the abipy/data directory

Testing ¶

Abipy has a testing infrastructure based on unittest and pytest.

Common test support is provided by abipy.core.testing, data files are stored in abipy/data, in particular in abipy/data/refs that contains several output files that can be used for writing unit tests and examples.

To install pytest with useful plugins, use:

pip install -r requirements-tests.txt

in the top-level directory of the package. To run the tests associated to the abio.inputs module, use:

pytest -v abio/tests/test_inputs.py

or use:

pytest -v

to run the entire test suite.

Coding guide¶

Committing changes¶

Importing and name spaces¶

Naming, spacing, and formatting conventions¶

Writing examples¶

Testing¶