Development.md

Naming conventions

There are two main conventions used in Python DEV, snake_case and camelCase.

snake_case

• lower_snake_case -- filenames, Python variable / function names
• Upper_Snake_Case
• SCREAMING_SNAKE_CASE -- Python constant names
• _private_snake_case -- Python private variable / function names
• _dunder_ (aka _double_underscore_) -- Python reserved names

camelCase

• lowerCamelCase -- Javascript variable / function / attribute names
• UpperCamelCase (aka StudlyCaps) -- Python class / exception names, Javascript constructor funtion names

WARNING: lower_snake_case - always for variables and function names, UpperCamelCase used only for class names!

Docstring formatting guide

To obtain nice autogenerated documentation, one should follow the next requitements:

Used docsting-style is sphinx, you can enable autogenerative plugins in your VS Code

Basic docsting structure:

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)  -- **for our current Convention is optional**
...
:raises [ErrorType]: [ErrorDescription]. -- **for our current Convention is optional**
...
:return: [ReturnDescription]
:rtype: [ReturnType] -- **for our current Convention is optional**
"""

If the description of Summary, praram, return is consists of more than one line, one should use tabulations on next line:

"""Example with multilines

    :param example: if your line length is too long
        <- the tabulation should used here
    :param other_param: like this
"""

Advanced docstring formatting

One can use additional formatting, full description is here.

For instance bullet-lists, must start from separate blank line and also ends with separate blank line, allowed symbols - + *.

Codeblock: before codeblock, :: should be included, same with bullet-list, must start from separate blank line and also ends with separate blank line. Code block starts from additional intendation.

See code example to get better understanding:

 def remove_from_table(table: str, reason: Dict[str, str]) -> str:
        """Remove data from specified table

        Data should have columns:

        - currency - string eth or btc

        - type - int, 1 - trx; 2 - aid; 3 - pubkey

        - data - int. Note - only one value

        - reason - string

        Example:
        ::

            with pyclain.DBA() as db_client:
                q = db_client.remove_from_table('exceptions', {'reason':'TestCase tk'})
                db_client.execute_query(q)

        :param table: string, name of table
        :param reason: dict, {columns_name: value}

        :returns: query - str. Your SQL query
        """

Result:

References

https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html