From fb41621a56bc5964d5375926be777023e984028f Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 10:31:59 -0600
Subject: [PATCH 001/805] Two easily.
---
Readme.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Readme.rst b/Readme.rst
index 07106e2f0..bf7f1838b 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -26,7 +26,7 @@ Topics include:
- Server configurations & tools for various web frameworks
- Documentation: writing it
- Testing: Jenkins & tox guides
-- How to easily interface ``hg`` from ``git`` easily
+- How to easily interface ``hg`` from ``git``
If you aren't fond of reading reStructuredText, there is an
almost up-to-date `HTML version at docs.python-guide.org
From 951f210d022819403ce5884aeb1abb714cc34ac8 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 11:06:59 -0600
Subject: [PATCH 002/805] Some grammar fixes for writing/structure.
---
docs/writing/structure.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 7d3978e61..72a4798dd 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -99,12 +99,12 @@ which is not the case. There is an
`example `_ of how the
dot notation should be used in the Python docs.
-If you'd like you could name it as :file:`my_spam.py` but even our friend the
-underscore should not be seen often in module names.
+If you'd like you could name your module :file:`my_spam.py`, but even our
+friend the underscore should not be seen often in module names.
-Aside for some naming restrictions, nothing special is required for a Python file
-to be a module, but the import mechanism needs to be understood in order to use
-this concept properly and avoid some issues.
+Aside from some naming restrictions, nothing special is required for a Python
+file to be a module, but you need to understand the import mechanism in order
+to use this concept properly and avoid some issues.
Concretely, the ``import modu`` statement will look for the proper file, which is
:file:`modu.py` in the same directory as the caller if it exists. If it is not
@@ -134,7 +134,7 @@ compartmentalized**.
Using ``from modu import func`` is a way to pinpoint the function you want to
import and put it in the global namespace. While much less harmful than ``import
*`` because it shows explicitly what is imported in the global namespace, its
-advantage over a simpler ``import modu`` is only that it will save some typing.
+only advantage over a simpler ``import modu`` is that it will save a little typing.
**Very bad**
From 404c2581ee125b81fe17258fb126f79fecbfcaf5 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 11:07:49 -0600
Subject: [PATCH 003/805] More grammar and cross reference for #132.
---
docs/writing/structure.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 72a4798dd..8f14b8d3d 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -161,11 +161,11 @@ only advantage over a simpler ``import modu`` is that it will save a little typi
[...]
x = modu.sqrt(4) # sqrt is visibly part of modu's namespace
-As said in the section about style, readability is one of the main features of
-Python. Readability means to avoid useless boilerplate text and clutter,
-therefore some efforts are spent trying to achieve a certain level of brevity.
-But terseness and obscurity are the limits where brevity should stop. Being
-able to tell immediately where a class or function comes from, as in the
+As mentioned in the :ref:`code_style` section, readability is one of the main
+features of Python. Readability means to avoid useless boilerplate text and
+clutter, therefore some efforts are spent trying to achieve a certain level of
+brevity. But terseness and obscurity are the limits where brevity should stop.
+Being able to tell immediately where a class or function comes from, as in the
``modu.func`` idiom, greatly improves code readability and understandability in
all but the simplest single file projects.
From 707628d2af5fc8098502ba6c723353e6ffb4db88 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 11:50:47 -0600
Subject: [PATCH 004/805] More writing/structure changes.
---
docs/writing/structure.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 8f14b8d3d..37764c99b 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -183,13 +183,13 @@ gather all package-wide definitions.
A file :file:`modu.py` in the directory :file:`pack/` is imported with the statement ``import
pack.modu``. This statement will look for an :file:`__init__.py` file in :file:`pack`, execute
-all of its top-level statements. Then it will look for a file :file:`pack/modu.py` and
+all of its top-level statements. Then it will look for a file named :file:`pack/modu.py` and
execute all of its top-level statements. After these operations, any variable,
function, or class defined in :file:`modu.py` is available in the pack.modu namespace.
A commonly seen issue is to add too much code to :file:`__init__.py`
files. When the project complexity grows, there may be sub-packages and
-sub-sub-packages in a deep directory structure, and then, importing a single item
+sub-sub-packages in a deep directory structure. In this case, importing a single item
from a sub-sub-package will require executing all :file:`__init__.py` files met while
traversing the tree.
@@ -207,7 +207,7 @@ Python is sometimes described as an object-oriented programming language. This
can be somewhat misleading and needs to be clarified.
In Python, everything is an object, and can be handled as such. This is what is
-meant when we say that, for example, functions are first-class objects.
+meant when we say, for example, that functions are first-class objects.
Functions, classes, strings, and even types are objects in Python: like any
objects, they have a type, they can be passed as function arguments, they may
have methods and properties. In this understanding, Python is an
@@ -284,7 +284,7 @@ The Python language provides a simple yet powerful syntax called 'decorators'.
A decorator is a function or a class that wraps (or decorates) a function
or a method. The 'decorated' function or method will replace the original
'undecorated' function or method. Because functions are first-class objects
-in Python, it can be done 'manually', but using the @decorator syntax is
+in Python, this can be done 'manually', but using the @decorator syntax is
clearer and thus preferred.
.. code-block:: python
From 2e9ae2152f10862ce479cf14cc477e8b88c2d2b2 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:18:51 -0600
Subject: [PATCH 005/805] Grammar and a couple line wraps for writing/style.
---
docs/writing/style.rst | 46 +++++++++++++++++++++++-------------------
1 file changed, 25 insertions(+), 21 deletions(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 9ca14896d..d1e5ebf28 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -101,7 +101,7 @@ calls to ``send('Hello', 'World')`` and ``point(1, 2)``.
2. **Keyword arguments** are not mandatory and have default values. They are often
used for optional parameters sent to the function. When a function has more than
-two or three positional parameters, its signature will be more difficult to remember
+two or three positional parameters, its signature is more difficult to remember
and using keyword argument with default values is helpful. For instance, a more
complete ``send`` function could be defined as ``send(message, to, cc=None, bcc=None)``.
Here ``cc`` and ``bcc`` are optional, and evaluate to ``None`` when they are not
@@ -176,15 +176,15 @@ possible to do each of the following:
However, all these options have many drawbacks and it is always better to use
the most straightforward way to achieve your goal. The main drawback is that
-readability suffers deeply from them. Many code analysis tools, such as pylint
-or pyflakes, will be unable to parse this "magic" code.
+readability suffers greatly when using these constructs. Many code analysis
+tools, such as pylint or pyflakes, will be unable to parse this "magic" code.
We consider that a Python developer should know about these nearly infinite
-possibilities, because it grows the confidence that no hard-wall will be on the
-way. However, knowing how to use them and particularly when **not** to use
-them is the most important.
+possibilities, because it instills confidence that no impassable problem will
+be on the way. However, knowing how and particularly when **not** to use
+them is very important.
-Like a Kungfu master, a Pythonista knows how to kill with a single finger, and
+Like a kung fu master, a Pythonista knows how to kill with a single finger, and
never to actually do it.
We are all consenting adults
@@ -195,10 +195,10 @@ dangerous. A good example is that any client code can override an object's
properties and methods: there is no "private" keyword in Python. This
philosophy, very different from highly defensive languages like Java, which
give a lot of mechanisms to prevent any misuse, is expressed by the saying: "We
-are consenting adults".
+are all consenting adults".
This doesn't mean that, for example, no properties are considered private, and
-that no proper encapsulation is possible in Python. But, instead of relying on
+that no proper encapsulation is possible in Python. Rather, instead of relying on
concrete walls erected by the developers between their code and other's, the
Python community prefers to rely on a set of conventions indicating that these
elements should not be accessed directly.
@@ -210,8 +210,8 @@ the code is modified is the responsibility of the client code.
Using this convention generously is encouraged: any method or property that is
not intended to be used by client code should be prefixed with an underscore.
-This will guarantee a better separation of duties and easier modifications of
-existing code, and it will always be possible to publicize a private property,
+This will guarantee a better separation of duties and easier modification of
+existing code; it will always be possible to publicize a private property,
while privatising a public property might be a much harder operation.
Returning values
@@ -235,7 +235,7 @@ statement can assume the condition is met to further compute the function's main
Having multiple such return statements is often necessary.
However, when a function has multiple main exit points for its normal course, it becomes
-difficult to debug the returned result, and it may be preferable to keep a single exit
+difficult to debug the returned result, so it may be preferable to keep a single exit
point. This will also help factoring out some code paths, and the multiple exit points
are a probable indication that such a refactoring is needed.
@@ -281,7 +281,7 @@ a tuple of two elements for each item in list:
for index, item in enumerate(some_list):
# do something with index and item
-You can use this to swap variables, as well:
+You can use this to swap variables as well:
.. code-block:: python
@@ -360,9 +360,13 @@ Take the following code for example:
def lookup_list(l):
return 's' in l
-Even though both functions look identical, because *lookup_dict* is utilizing the fact that dictionaries in Python are hashtables, the lookup performance between the two is very different.
-Python will have to go through each item in the list to find a matching case, which is time consuming. By analysing the hash of the dictionary, finding keys in the dict can be done very quickly.
-For more information see this `StackOverflow `_ page.
+Even though both functions look identical, because *lookup_dict* is utilizing
+the fact that dictionaries in Python are hashtables, the lookup performance
+between the two is very different. Python will have to go through each item
+in the list to find a matching case, which is time consuming. By analysing
+the hash of the dictionary, finding keys in the dict can be done very quickly.
+For more information see this `StackOverflow `_
+page.
Zen of Python
-------------
@@ -406,7 +410,7 @@ PEP 8
Conforming your Python code to PEP 8 is generally a good idea and helps make
code more consistent when working on projects with other developers. There
-exists a command-line program, `pep8 `_,
+is a command-line program, `pep8 `_,
that can check your code for conformance. Install it by running the following
command in your Terminal:
@@ -584,19 +588,19 @@ files for you.
print line
The ``with`` statement is better because it will ensure you always close the
-file, even if an exception is raised.
+file, even if an exception is raised inside the ``with`` block.
Line Continuations
~~~~~~~~~~~~~~~~~~
When a logical line of code is longer than the accepted limit, you need to
-split it over multiple physical lines. Python interpreter will join consecutive
+split it over multiple physical lines. The Python interpreter will join consecutive
lines if the last character of the line is a backslash. This is helpful
-sometimes but is preferably avoided, because of its fragility: a white space
+in some cases, but should usually be avoided because of its fragility: a white space
added to the end of the line, after the backslash, will break the code and may
have unexpected results.
-A preferred solution is to use parentheses around your elements. Left with an
+A better solution is to use parentheses around your elements. Left with an
unclosed parenthesis on an end-of-line the Python interpreter will join the
next line until the parentheses are closed. The same behavior holds for curly
and square braces.
From 59eaef2f78e87d4667117bfae0deee600b3d3a65 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:27:44 -0600
Subject: [PATCH 006/805] Added pep-3132 style extended unpacking.
---
docs/writing/style.rst | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 9ca14896d..2814318f7 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -293,6 +293,16 @@ Nested unpacking works too:
a, (b, c) = 1, (2, 3)
+In Python 3, a new method of extended unpacking was introduced by
+:pep:`3132`:
+
+.. code-block:: python
+
+ a, *rest = [1, 2, 3]
+ # a = 1, rest = [2, 3]
+ a, *middle, c = [1, 2, 3, 4]
+ # a = 1, middle = [2, 3], c = 4
+
Create an ignored variable
~~~~~~~~~~~~~~~~~~~~~~~~~~
From c3b3e766f977cfc036a4ff410e6af1db16ed6f6d Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:41:00 -0600
Subject: [PATCH 007/805] Mostly line wraps, and a small grammar fix to
writing/documentation.
---
docs/writing/documentation.rst | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
index 125b7e79c..e5600c7df 100644
--- a/docs/writing/documentation.rst
+++ b/docs/writing/documentation.rst
@@ -8,22 +8,21 @@ both you and others a lot of time.
Project Documentation
---------------------
-A :file:`README` file at the root directory should give general
-information to the users and the maintainers. It should be raw text or
-written in some very easy to read markup, such as
-:ref:`reStructuredText-ref` and Markdown. It should contain a few
-lines explaining the purpose of the project or the library (without
-assuming the user knows anything about the project), the url of the
-main source for the software, and some basic credit information. This
-file is the main entry point for readers of the code.
+A :file:`README` file at the root directory should give general information
+to both users and maintainers of a project. It should be raw text or
+written in some very easy to read markup, such as :ref:`reStructuredText-ref`
+or Markdown. It should contain a few lines explaining the purpose of the
+project or library (without assuming the user knows anything about the
+project), the url of the main source for the software, and some basic credit
+information. This file is the main entry point for readers of the code.
An :file:`INSTALL` file is less necessary with Python. The installation
instructions are often reduced to one command, such as ``pip install
module`` or ``python setup.py install`` and added to the :file:`README`
file.
-A :file:`LICENSE` file should *always* be present and specify the license under which the
-software is made available to the public.
+A :file:`LICENSE` file should *always* be present and specify the license
+under which the software is made available to the public.
A :file:`TODO` file or a ``TODO`` section in :file:`README` should list the
planned development for the code.
@@ -158,7 +157,8 @@ Pycco_
.. _Docco: http://jashkenas.github.com/docco
Ronn_
- Ronn builds unix manuals. It converts human readable textfiles to roff for terminal display, and also to HTML for the web.
+ Ronn builds unix manuals. It converts human readable textfiles to roff
+ for terminal display, and also to HTML for the web.
.. _Ronn: https://github.com/rtomayko/ronn
From e7f0d1fa8f3600dae5666287b1607e6a005b4cf5 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:48:53 -0600
Subject: [PATCH 008/805] Minor fixes for writing/tests.
---
docs/writing/tests.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index 34add0d8e..f4ca54bc7 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -44,7 +44,7 @@ Some general rules of testing:
- The first step when you are debugging your code is to write a new test
pinpointing the bug. While it is not always possible to do, those bug
- catching test are among the most valuable pieces of code in your project.
+ catching tests are among the most valuable pieces of code in your project.
- Use long and descriptive names for testing functions. The style guide here
is slightly different than that of running code, where short names are
@@ -66,8 +66,8 @@ Some general rules of testing:
testing code is often the best they can do. They will or should discover the
hot spots, where most difficulties arise, and the corner cases. If they have
to add some functionality, the first step should be to add a test and, by this
- mean, ensure the new functionality is not already a working path that has not
- been plugged in the interface.
+ means, ensure the new functionality is not already a working path that has not
+ been plugged into the interface.
The Basics
::::::::::
From 93c4d9b49c480b17ca32aa38d9eda68354391d18 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:56:32 -0600
Subject: [PATCH 009/805] Two minor changes to writing/gotchas.
---
docs/writing/gotchas.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst
index 12e18619e..5ed5669c1 100644
--- a/docs/writing/gotchas.rst
+++ b/docs/writing/gotchas.rst
@@ -79,7 +79,7 @@ signal that no argument was provided (:py:data:`None` is often a good choice).
When the Gotcha Isn't a Gotcha
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Sometimes you specifically can "exploit" (read: use as intended) this behavior
+Sometimes you can specifically "exploit" (read: use as intended) this behavior
to maintain state between calls of a function. This is often done when writing
a caching function.
@@ -126,7 +126,7 @@ What Does Happen
8
8
-Five functions are created, but all of them just multiply ``x`` by 4.
+Five functions are created; instead all of them just multiply ``x`` by 4.
Python's closures are *late binding*.
This means that the values of variables used in closures are looked
From 9079873a51d834468af61b353389ef623fa0025b Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:59:22 -0600
Subject: [PATCH 010/805] A single wording change in writing/license.
---
docs/writing/license.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/writing/license.rst b/docs/writing/license.rst
index 006c045ce..4d82b39e4 100644
--- a/docs/writing/license.rst
+++ b/docs/writing/license.rst
@@ -4,8 +4,8 @@ Choosing a License
Your source publication *needs* a license. In the US, if no license is
specified, users have no legal right to download, modify, or
distribute. Furthermore, people can't contribute to your code unless
-you tell them what rules to play by. It's complicated, so here are
-some pointers:
+you tell them what rules to play by. Choosing a license is complicated, so
+here are some pointers:
Open source. There are plenty of `open source licenses
`_ available to choose
From e17fdcdd27dbbb7a254d02602a519fc0974f700a Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 13:11:11 -0600
Subject: [PATCH 011/805] Some grammar and wrapping changes to scenarios/web.
Also fixed a small typo.
---
docs/scenarios/web.rst | 27 ++++++++++++++++-----------
1 file changed, 16 insertions(+), 11 deletions(-)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index 4fcedf070..4d7551edc 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -24,7 +24,7 @@ WSGI is documented in :pep:`3333`.
Frameworks
::::::::::
-Broadly speaking, a web framework consist of a set of libraries and a main
+Broadly speaking, a web framework consists of a set of libraries and a main
handler within which you can build custom code to implement a web application
(i.e. an interactive web site). Most web frameworks include patterns and
utilities to accomplish at least the following:
@@ -280,7 +280,7 @@ and to the templates themselves.
- Template files should be passed only the dynamic
content that is needed for rendering the template. Avoid
- to be tempted to pass additional content "just in case":
+ the temptation to pass additional content "just in case":
it is easier to add some missing variable when needed than to remove
a likely unused variable later.
@@ -288,7 +288,7 @@ and to the templates themselves.
or assignments in the template itself, and many
allow some Python code to be evaluated in the
templates. This convenience can lead to uncontrolled
- increase in complexity, and often harder to find bugs.
+ increase in complexity, and often make it harder to find bugs.
- It is often necessary to mix JavaScript templates with
HTML templates. A sane approach to this design is to isolate
@@ -299,9 +299,12 @@ and to the templates themselves.
Jinja2
------
-`Jinja2 `_ is a template engine which is similar to the Django template system with some extra features. It is a text-based template
-language and thus can be used to generate any markup. It allows customization of filters, tags, tests and globals.
-Unlike the template system implemented in the Django Framework it allows to call functions. The Code is staying under the BSD license.
+`Jinja2 `_ is a template engine which is similar to
+the Django template system with some extra features. It is a text-based
+template language and thus can be used to generate any markup. It allows
+customization of filters, tags, tests and globals, and unlike the template
+system implemented in the Django Framework, also allows calling functions.
+Jinja2 is released under the BSD license.
Here some important html tags in Jinja2:
@@ -324,8 +327,8 @@ Here some important html tags in Jinja2:
-The next listings is an example of a web site in combination with the tornado web server. Tornado is not very complicate
-to use.
+The next listings is an example of a web site in combination with the tornado
+web server. Tornado is not very complicate to use.
.. code-block:: python
@@ -365,7 +368,8 @@ to use.
application.listen(PORT)
tornado.ioloop.IOLoop.instance().start()
-The :file:`base.html` file can be used as base for all site pages which are for example implemented in the content block.
+The :file:`base.html` file can be used as base for all site pages which are
+for example implemented in the content block.
.. code-block:: html
@@ -389,8 +393,9 @@ The :file:`base.html` file can be used as base for all site pages which are for
+ Hello, ${'world'}!
+
+
+
+ ${row.capitalize()} ${col}
+ |
+
+
+
+