Newer
Older
-----------------------------
Python code should follow **PEP 8**
We have a few requirements for our developers in addition to the original PEP8.
These are grabbed from the `Coding Guidelines for astropy-affiliated packages`_.
.. _Coding Guidelines for astropy-affiliated packages: https://docs.astropy.org/en/latest/development/codeguide.html#coding-style-conventions
- Only use 4-space indent
- ``import *`` is not allowed
- The use of automatic code formatters (e.g., Black) is strongly discouraged
Exceptions to PEP 8
-------------------
The following table summarizes all PEP 8 guidelines that are **not followed**
by the this Code Style Guide.
E501
Allow lines to have > 80 characters, but <=120
E722
Allow use of bare ``try ... except ...``
E121, E123, E126, E133, E226, E241, E242, E704, W503, W504 and W505
They are ignored because they are not rules unanimously accepted,
and PEP 8 does not enforce them.
.. tip::
Click `here`_ for error code explanations and conventions
.. _here: https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes
All CSST Python source code is consistent with PEP 8 naming in the following ways:
- class names are ``CamelCase`` with leading uppercase
- function names should be ``lower_case_with_underscore``
- module variables used as module global constants are ``UPPERCASE_WITH_UNDERSCORES``
Code style check
----------------
Many tools can be used to check code style, such as
- PyLint: https://pylint.pycqa.org/en/latest/index.html
- Flake8: https://flake8.pycqa.org/en/latest/index.html
- pycodestyle: https://pycodestyle.pycqa.org/en/latest/index.html
All of them are from the PyCQA organization.
In our case, we recommend our developers to use the following command
(with pycodestyle) to check code style before committing code.
.. code-block:: bash
pycodestyle ./**/*.py --ignore=E121,E123,E126,E226,E24,E704,W503,W504,E501,E722
Recommended IDEs
----------------
For writing Python packages, two powerful IDEs are worth to recommend:
- PyCharm: https://www.jetbrains.com/pycharm/
- VSCode: https://code.visualstudio.com/
Both of them have plugins or built-in tools to check code style.
There are several popular docstring styles, namely Google, reStructuredText, and Numpy.
The CSST DAS adopts Numpydoc-style among the three.
We refer our developers to the Numpydoc official style guide for instructions on
how to write docstrings.
- https://numpydoc.readthedocs.io/en/latest/example.html
In our case, we recommend the following method to check docstring
.. code-block:: bash
For example,
.. code-block:: bash
python -m numpydoc --validate csst_proto.top_level_interface.flip_image
An example with typical Numpy-style docstring is shown below
.. literalinclude:: ../../csst_proto/demo.py
:linenos:
:language: python
.. note::
Numpy-style docstring uses a two-section summary for functions / classes,
including ``a short summary`` (usually a single line) right after the quote
and a following detailed ``extended summary``.
.. note::
The ``See Also`` section is not required for our development.
.. note::
Presently, Numpy style docstring check is only performed on the functions / classes
listed in the ``__all__`` variable in ``top_level_interface`` module.
Markdown and reStructrured Text are two of popular markup languages.
reStructrured Text is used in Numpydoc docstrings as well as sphinx-based documentation.
Markdown is much easier and usually used to write `README` for a package.