realpython · kennethreitz · Jun 17, 2014 · Jun 17, 2014 · Jun 17, 2014 · Jun 17, 2014
diff --git 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

diff --git 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
 

diff --git 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

diff --git 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
 <http://opensource.org/licenses/alphabetical>`_ available to choose

diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
@@ -99,12 +99,12 @@ which is not the case. There is an
 `example <http://docs.python.org/tutorial/modules.html#packages>`_ 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**
 
@@ -161,11 +161,11 @@ advantage over a simpler ``import modu`` is only that it will save some typing.
     [...]
     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.
 
@@ -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

diff --git 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 <http://stackoverflow.com/questions/513882/python-list-vs-dict-for-look-up-table>`_ 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 <http://stackoverflow.com/questions/513882/python-list-vs-dict-for-look-up-table>`_
+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 <https://github.com/jcrocholl/pep8>`_,
+is a command-line program, `pep8 <https://github.com/jcrocholl/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.

diff --git 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
 ::::::::::