<commit_before>About tgext.utils
=================

.. image:: https://travis-ci.org/TurboGears/tgext.utils.png?branch=master
    :target: https://travis-ci.org/TurboGears/tgext.utils

.. image:: https://coveralls.io/repos/TurboGears/tgext.utils/badge.png?branch=master
    :target: https://coveralls.io/r/TurboGears/tgext.utils?branch=master

.. image:: https://img.shields.io/pypi/v/tgext.utils.svg
   :target: https://pypi.python.org/pypi/tgext.utils

tgext.utils is a collection of utilities for the TurboGears2 web framework.

Installing
----------

tgext.utils can be installed from pypi::

    pip install tgext.utils

should just work for most of the users.

CSRF Protection
===============

.. Note::
   Before CSRF protection, be sure to protect your app from XSS attacks

``tgext.utils.csrf`` provides two decorators ``@csrf_token`` and ``@csrf_protect`` which
generate a CSRF token for inclusion in a form and check that the token is valid.

The user must apply ``@csrf_token`` decorator to the action that exposes the form,
and put an ``<input type="hidden">`` into the form with a ``request.csrf_token`` as
the value and ``_csrf_token`` as name:

The user also should register the ``CSRFConfigurationComponent`` in it's application configuration
and configure at least ``csrf.secret`` in the blueprint/ini file (uuid4 is a good choice)

.. code-block:: python

    @csrf_token
    @expose()
    def form(self):
        return '''
        <form method="POST" action="/post_form">
            <input type="hidden" name="_csrf_token" value="%s"><commit_msg>document that sessions must be enabled for csrf protection<commit_after>About tgext.utils
=================

.. image:: https://travis-ci.org/TurboGears/tgext.utils.png?branch=master
    :target: https://travis-ci.org/TurboGears/tgext.utils

.. image:: https://coveralls.io/repos/TurboGears/tgext.utils/badge.png?branch=master
    :target: https://coveralls.io/r/TurboGears/tgext.utils?branch=master

.. image:: https://img.shields.io/pypi/v/tgext.utils.svg
   :target: https://pypi.python.org/pypi/tgext.utils

tgext.utils is a collection of utilities for the TurboGears2 web framework.

Installing
----------

tgext.utils can be installed from pypi::

    pip install tgext.utils

should just work for most of the users.

CSRF Protection
===============

.. Note::
   Before CSRF protection, be sure to protect your app from XSS attacks

``tgext.utils.csrf`` provides two decorators ``@csrf_token`` and ``@csrf_protect`` which
generate a CSRF token for inclusion in a form and check that the token is valid.

You must apply ``@csrf_token`` decorator to the action that exposes the form,
and put an ``<input type="hidden">`` into the form with a ``request.csrf_token`` as
the value and ``_csrf_token`` as name:

You must make sure sessions are enabled
You also should register the ``CSRFConfigurationComponent`` in it's application configuration
and configure at least ``csrf.secret`` in the blueprint/ini file (uuid4 is a good choice)

.. code-block:: python

    @csrf_token
    @expose()
    def form(self):
        return '''
        <form method="POST" action="/post_form">
            <input type="hidden" name="_csrf_token" value="%s">
{'fraction_non_alphanumeric': 0.1407661164746185, 'fraction_numerical': 0.0012457178449081284, 'mean_word_length': 4.003115264797508, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1612921', 'n_tokens_mistral': 1037, 'n_tokens_neox': 1013, 'n_words': 316}