From d1b238638cb39442a0154740c43a89c608cee634 Mon Sep 17 00:00:00 2001 From: Dirk Makowski Date: Fri, 11 Jan 2013 03:21:06 +0100 Subject: [PATCH] Update the "how to contribute" docs with py3k info. --- docs/contribute.rst | 56 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/docs/contribute.rst b/docs/contribute.rst index c302dcc6..3ab86263 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -58,6 +58,21 @@ To do so, you can use the following two commands:: samples/content/ $ LC_ALL="C" pelican -o tests/output/basic/ samples/content/ +testing for python3 +------------------- + +On Python 3, if you have installed the Py3k compatible versions of the +plugins manual testing with ``unit2 discover`` is also straightforward. + +However, you must tell tox to use those Py3k libraries. If you forget this, +tox will pull the regular packages from PyPi and the tests will fail. + +Tell tox about the local packages thusly: enter the source directory of +smartypants and run tox there. Do this again for typogrify and webassets. +Smartypants and typogrify do not have real tests, and webassets will fail +noisily, but as a result we get these libraries neatly packaged in tox's +distshare directory. And this we need to run tox for Pelican. + Coding standards ================ @@ -67,3 +82,44 @@ eased via the `pep8 `_ or `flake8 `_ tools, the latter of which in particular will give you some useful hints about ways in which the code/formatting can be improved. + +Python3 support +=============== + +Here are some tips that may be useful when doing some code for both python2 and +python3 at the same time: + +- Assume, every string and literal is unicode (import unicode_literals): + + - Do not use prefix ``u'``. + - Do not encode/decode strings in the middle of sth. Follow the code to the + source (or target) of a string and encode/decode at the first/last possible + point. + - In other words, write your functions to expect and to return unicode. + - Encode/decode strings if e.g. the source is a Python function that is known + to handle this badly, e.g. strftime() in Python 2. + +- Use new syntax: print function, "except ... *as* e" (not comma) etc. +- Refactor method calls like ``dict.iteritems()``, ``xrange()`` etc. in a way + that runs without code change in both Python versions. +- Do not use magic method ``__unicode()__`` in new classes. Use only ``__str()__`` + and decorate the class with ``@python_2_unicode_compatible``. +- Do not start int literals with a zero. This is a syntax error in Py3k. +- Unfortunately I did not find an octal notation that is valid in both + Pythons. Use decimal instead. +- use six, e.g.: + + - ``isinstance(.., basestring) -> isinstance(.., six.string_types)`` + - ``isinstance(.., unicode) -> isinstance(.., six.text_type)`` + +- ``setlocale()`` in Python 2 bails when we give the locale name as unicode, + and since we are using ``from __future__ import unicode_literals``, we do + that everywhere! As a workaround, I enclosed the localename with ``str()``; + in Python 2 this casts the name to a byte string, in Python 3 this should do + nothing, because the locale name already had been unicode. + +- Kept range() almost everywhere as-is (2to3 suggests list(range())), just + changed it where I felt necessary. + +- Changed xrange() back to range(), so it is valid in both Python versions. +