Merge branch 'master' of github.com:django-ftl/django-ftl

README.rst

@@ -87,8 +87,8 @@ Gettext where the developer would have to create separate message strings for
 each case, because the message format is not powerful enough to allow the
 translator to add variant selection. Also, these different message strings will
 be identical in languages which don't have that feature — in other words, the
-grammatical features of all languages end up having a disproportionate affect on
-the source code and on other translators.
+grammatical features of all languages end up either having a disproportionate
+effect on the source code and on other translators, or being neglected entirely.
 
 
 Documentation
@@ -97,6 +97,52 @@ Documentation
 The documentation for how to use django-ftl is in the docs/folder and online at
 https://django-ftl.readthedocs.io.
 
+Status
+------
+
+This package should be considered a beta. While it has a good feature set, test
+suite and docs, it has not been used a huge amount in production. In addition,
+it currently relies on `our fork <https://github.com/django-ftl/python-fluent>`_
+of `python-fluent <https://github.com/projectfluent/python-fluent>`_, which has
+the following significant features/changes not yet merged to the official
+version:
+
+* Refined error handling for functions (see `PR
+  <https://github.com/projectfluent/python-fluent/pull/92>`_).
+
+* Compiler implementation (see `compiler branch
+  <https://github.com/django-ftl/python-fluent/tree/compiler_implementation>`_).
+  This is an additional and much faster implementation of ``FluentBundle`` that
+  compiles FTL messages to Python `AST
+  <https://docs.python.org/3/library/ast.html>`_, running the result through
+  `compile
+  <https://docs.python.org/3/library/functions.html?highlight=compile#compile>`_
+  and `exec
+  <https://docs.python.org/3/library/functions.html?highlight=compile#exec>`_.
+
+  Use of ``exec`` for high performance Python code is an established technique
+  used by other projects (e.g. `Jinja2 <http://jinja.pocoo.org/>`_ and `Mako
+  <https://www.makotemplates.org/>`_), and we only use exec on data derived from
+  FTL files, which will normally be created by translators and not potential
+  attackers. Nevertheless there are understandably some security concerns. Using
+  AST objects rather than strings for creating Python code dynamically makes our
+  use of ``exec`` intrinsically safer than some of these other projects, and we
+  also use some `defence-in-depth techniques
+  <https://github.com/django-ftl/python-fluent/blob/compiler_implementation/fluent.runtime/fluent/runtime/codegen.py>`_.
+
+  When using the compiler as opposed to the resolver, the additional up-front
+  processing of the FTL messages could incur a noticeable startup cost
+  (typically of the order of .5ms per message). For long running Django
+  processes this is usually a very good trade-off given the performance
+  benefits.
+
+* 'Escaper' functionality (see `escapers branch
+  <https://github.com/django-ftl/python-fluent/tree/implement_escapers>`_). This
+  allows us to `handle embedded HTML correctly
+  <https://django-ftl.readthedocs.io/en/latest/usage.html#html-escaping>`_. The
+  mechanism for doing this has been implemented as part of python-fluent in a
+  generic way, and then used in django-ftl to handle HTML escaping in templates
+  with a minimum of work.
 
 Credits
 -------

setup.py

@@ -18,6 +18,7 @@
     'flake8-future-import>=0.4.5',
     'django-functest==1.0.4',
     'check-manifest',
+    'isort',
 ]