From d4f4abfb499a2a7d736e7583cc55884b0d6a4608 Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Fri, 14 Oct 2016 15:57:57 -0700 Subject: [PATCH] Fix python3 developer docs to build. A couple small refactors to clarify meaning. --- docsite/rst/dev_guide/conf.py | 2 +- .../dev_guide/developing_modules_python3.rst | 31 ++++++++++--------- 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docsite/rst/dev_guide/conf.py b/docsite/rst/dev_guide/conf.py index a70301afbd8..0e14a2c83d2 100644 --- a/docsite/rst/dev_guide/conf.py +++ b/docsite/rst/dev_guide/conf.py @@ -45,7 +45,7 @@ source_suffix = '.rst' # source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index2.rst' +master_doc = 'index' # General information about the project. project = u'dev_guide' diff --git a/docsite/rst/dev_guide/developing_modules_python3.rst b/docsite/rst/dev_guide/developing_modules_python3.rst index 256e252c0c1..8fdf9f1b808 100644 --- a/docsite/rst/dev_guide/developing_modules_python3.rst +++ b/docsite/rst/dev_guide/developing_modules_python3.rst @@ -16,8 +16,9 @@ porting: Much of the knowledge of porting code will be usable on all three of these pieces but there are some special considerations for some of it as well. +-------------------------------------------- Minimum Version of Python-3.x and Python-2.x -============================================ +-------------------------------------------- In controller side code, we support Python-3.5 or greater and Python-2.6 or greater. @@ -55,7 +56,7 @@ to port code is `Lennart Regebro's book: Porting to Python 3 `_ Controller String Strategy ========================== @@ -88,7 +89,7 @@ programmer to proactively define a strategy for working with strings in their program so that they don't mix text and byte strings unintentionally. Unicode Sandwich ---------------- +---------------- In controller-side code we use a strategy known as the Unicode Sandwich (named after Python-2's :class:`unicode` text type). For Unicode Sandwich we know that @@ -97,8 +98,8 @@ environment variables, and some library calls) we are going to receive bytes. We need to transform these bytes into text and use that throughout the internal portions of our code. When we have to send those strings back out to the outside world we first convert the text back into bytes. -To visual this, imagine a 'sandwich' consisting of a top and bottom layer of bytes, a layer of -conversion between, and all text type in the center. +To visualize this, imagine a 'sandwich' consisting of a top and bottom layer +of bytes, a layer of conversion between, and all text type in the center. Common Borders -------------- @@ -163,16 +164,18 @@ works on both versions:: When you are only manipulating a filename as a string without talking to the filesystem (or a C library which talks to the filesystem) you can often get -away without converting to bytes. If the code needs to manipulate the -filename and also talk to the filesystem, it can be more convenient to -transform to bytes right away and manipulate in bytes. For example:: +away without converting to bytes:: import os.path os.path.join(u'/var/tmp/café', u'くらとみ') os.path.split(u'/var/tmp/café/くらとみ') -.. warn:: Make sure all variables passed to a function are the same type. +On the other hand, if the code needs to manipulate the filename and also talk +to the filesystem, it can be more convenient to transform to bytes right away +and manipulate in bytes. + +.. warning:: Make sure all variables passed to a function are the same type. If you're working with something like :func:`os.path.join` which takes multiple strings and uses them in combination, you need to make sure that all the types are the same (either all bytes or all text). Mixing @@ -197,8 +200,8 @@ transform the output into text strings. Tips, tricks, and idioms to adopt ================================= -Forwards Compatability Boilerplate ---------------------------- +Forwards Compatibility Boilerplate +---------------------------------- Use the following boilerplate code at the top of all controller-side modules to make certain constructs act the same way on Python-2 and Python-3:: @@ -225,8 +228,8 @@ The ``__future__`` imports do the following: * `PEP 0238: Division `_ * `PEP 3105: Print function `_ -Prefix byte strings with "b_" ------------------------------ +Prefix byte strings with "b\_" +------------------------------ Since mixing text and bytes types leads to tracebacks we want to be clear about what variables hold text and what variables hold bytes. We do this by @@ -237,7 +240,7 @@ prefixing any variable holding bytes with ``b_``. For instance:: with open(b_filename) as f: data = f.read() -We do not recommend prefixing the text strings instead because we only operate +We do not prefix the text strings instead because we only operate on byte strings at the borders, so there are fewer variables that need bytes than text.