@@ -2,18 +2,18 @@ Over time, some general coding rules have been established and some common patte
## Overview
Here some general thoughts on coding rules:
Here are some general thoughts on coding rules:
- Follow [PEP8](https://www.python.org/dev/peps/pep-0008/), if possible. Also read [PEP20](https://www.python.org/dev/peps/pep-0020/) and follow it by idea and spirit.
- Use variable names that are self-explaining and consisted. Some database scheme names are currently not following this and should be renames (lot of work)
- Use variable names that are self-explaining and consisted. Some database scheme names are currently not following this and should be renamed (lot of work)
- If possible, do typing of new functions. Do typing (or correct typing) in docstrings. Hint: flask render_template returns a string (str) and flask redirect returns a response object (from werkzeug.wrappers.response import Response).
Before submit to git:
- Code should be formatted by "black" with 105 character per line.
- Code should be checked by pylint and seen, if the complains make sense. It has problems with SQLAlchemy as it contains a lot of "Meta" stuff - we started a pylintrc to suppress some of the false positives.
- Code should be checked by pylint and seen if the complaints make sense. It has problems with SQLAlchemy as it contains a lot of "Meta" stuff - we started a pylintrc to suppress some of the false positives.
- Docstrings should be checked with pydocstyle using the "numpy" style.
- Code is in parts typed and we have a working mypy.ini. Hence, run mypy and see, if there are any (new) problems.
- Code is in parts typed, and we have a working mypy.ini. Hence, run mypy and see, if there are any (new) problems.
- Run the tests with pytest.
## Variables
...
...
@@ -34,7 +34,7 @@ We have a set of reserved variables that should be used throughout the project:
Remember: Special cases aren't special enough to break the rules.
Beside this, more relaxed, the use of following things is suggested:
Besides this, more relaxed, the use of following things is suggested:
| Variable| What for|
| ------ | ------ |
...
...
@@ -46,17 +46,17 @@ Beside this, more relaxed, the use of following things is suggested:
All functions should have a docsstring following the [numpy style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
We encourage to do typing of the variable inside the docstring. We use sphinx to automatically create a HTML documentation of the API. Needs more work and improvement. To make our life easier, we use markdown files for sphinx.
We encourage to do typing of the variable inside the docstring. We use sphinx to automatically create an HTML documentation of the API. Needs more work and improvement. To make our life easier, we use markdown files for sphinx.
We use the read_the_docs theme as it makes much nicer output.
We use the read_the_docs theme, as it makes much nicer output.
## Database access and transaction
We use Flask-SQLALchemy for all database accesses and transaction. No direct SQL or no direct SQLAlchemy.
If we have more complex database transaction, i.e. more then one line like a query, the database_transaction module should be used. It already contains general functions for create and update of most database schemes.
If we have more complex database transaction, i.e. more than one line like a query, the database_transaction module should be used. It already contains general functions for create and update of most database schemes.
To ensure that things are really written to the database, we implemented a context manger for the database and it should be used for anything that changes the database (updates, delete and create of entries). The common pattern is
To ensure that things are really written to the database, we implemented a context manger for the database, and it should be used for anything that changes the database (updates, delete and create of entries). The common pattern is
~~~~
import ResearchNotes.database_transactions as dbt
...
...
@@ -80,7 +80,7 @@ Some times the db_model_object is created and just passed to the function. We mi
## Working with the session cookie
To avoid confusion with the database session, the session cookie from flask is importat as `login_session` and should be addressed like this
To avoid confusion with the database session, the session cookie from flask is imported as `login_session` and should be addressed like this
