root/HelpIM3_chi/programming.txt

Hints on programming on HelpIM3.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Unicode / utf8
To keep the decoding / encoding uniform adhere to the following rules:
- All encodings on the web and webserver are set to UTF-8
- When recieving data one of the first processing steps must be decoding the
  strings from UTF-8 to python unicode objects.
- All internal processing must be able to handle both strings in plain ascii
  and unicode objects.
- The last step of the handler is encodig the returned python unicode to UTF-8

* Escaping output
Escaping is the responsibility of the templates, they know what language or
kind of text they spit out and how that should be escaped. Do use the escaping
functions of the TemplateBase class: then we are sure al escaping has the same
bugs.

* De-escaping input
ToDo: this is not nessecary yet. Probably the page-script is the most logical
place. In that case the PageBase class is the most logical place to include
functions for that.

* Dynamic loading and paths
To ensure no modules are dynamicly loaded that aren't meant to be loaded,
adhere to the following rules:
- use the HelpIM.dynamicLoad.load function for it
- hardcode the paths (eg: 'HelpIM.web.pages') where the modules are loaded from
- make seperate directories for the modules that might be loaded. Place no
  other modules or subdirectories in that directory.

* Preventing SQL-injections
Use SQLAlchemy, it prevents SQL injections for you. If you need to use
sqlalchemy.sql.text, always use the collon keywords for variables in your
queries.

* Input validation
Yes, do so! It is ok to do it implicitly; to do operations on the input that raise an
exception if the input is different from what is expected.

* Prefered programming style:
First of all read pep-8: http://www.python.org/dev/peps/pep-0008/ it is
very usefull to keep HelpIM readable.
In HelpIM the following variable naming conventions are used:
- use long, descriptive variable names, except for variables that are used
  locally and only during a few lines of code. You use a single uppercase
  character for them. Preferably the first character of the type of variable
  they are.
- use mixedCase, except for class names, use for these CapitalizedWords
Examples:

    templateConfigs = configFunction()

    class PageBase:

    S = "this is a string to be used locally and for a short period"