Merge pull request realpython#504 from mbren/dev

sigmavirus24 · sigmavirus24 · commit 85faaee29c72 · 2014-12-07T07:45:36.000-06:00
copy edits
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
@@ -149,7 +149,7 @@ PyCharm / IntelliJ IDEA
 known for IntelliJ IDEA. Both share the same code base and most of PyCharm's
 features can be brought to IntelliJ with the free `Python Plug-In <http://plugins.intellij.net/plugin/?id=631>`_.
 There are two versions of PyCharm: Professional Edition (Free 30-day trial)
-and Community Edition(Apache 2.0 License) with less features.
+and Community Edition(Apache 2.0 License) with fewer features.
 
 
 Eclipse
@@ -210,7 +210,7 @@ offering sourcecode autocompletion, syntax highlighting, support for version
 control systems, python 3 support, integrated web browser, python shell,
 integrated debugger and a flexible plug-in system. Written in python, it is
 based on the Qt gui toolkit, integrating the Scintilla editor control. Eric
-is an open-source software (GPLv3 licence) with more than ten years of active
+is an open-source software project (GPLv3 licence) with more than ten years of active
 development.
 
 
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
@@ -148,8 +148,8 @@ general :pep:`8` best practices.
 
 It has a detailed, multi-chapter case study on writing and releasing a package
 and eventually an application, including a chapter on using zc.buildout.  Later
-chapters detail best practices with writing documentation, test-driven
-development, version control, and optimization/profiling.
+chapters detail best practices such as writing documentation, test-driven
+development, version control, optimization and profiling.
 
     `Expert Python Programming <http://www.packtpub.com/expert-python-programming/book>`_
 
@@ -171,15 +171,15 @@ A Primer on Scientific Programming with Python
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A Primer on Scientific Programming with Python, written by Hans Petter Langtangen,
-mainly covers Python's usage in scientific field. In the book, examples are
+mainly covers Python's usage in the scientific field. In the book, examples are
 chosen from mathematics and the natural sciences.
 
     `A Primer on Scientific Programming with Python <http://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-30292-3>`_
 
 Numerical Methods in Engineering with Python
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, attempts to
+Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, puts the  
 emphasis on numerical methods and how to implement them in Python.
 
     `Numerical Methods in Engineering with Python <http://www.cambridge.org/us/academic/subjects/engineering/engineering-mathematics-and-programming/numerical-methods-engineering-python-2nd-edition>`_
diff --git a/docs/intro/news.rst b/docs/intro/news.rst
@@ -35,7 +35,7 @@ new releases, jobs, etc. related to Python.
 Python News
 ~~~~~~~~~~~~~
 
-News section in the official Python web site (www.python.org). It briefly
-highlights the news from Python community.
+Python News is the news section in the official Python web site (www.python.org). It briefly
+highlights the news from the Python community.
 
     `Python News <http://www.python.org/news/>`_
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
@@ -240,13 +240,13 @@ Chef
 Puppet
 ------
 
-`Puppet <http://puppetlabs.com>`_ is an IT Automation and configuration management
+`Puppet <http://puppetlabs.com>`_ is IT Automation and configuration management
 software from Puppet Labs that allows System Administrators to define the state of
 their IT Infrastructure, thereby providing an elegant way to manage their fleet of
 physical and virtual machines.
 
 Puppet is available both as an Open Source and an Enterprise variant. Modules are
-small,shareable units of code written to automate or define the state of a system.
+small, shareable units of code written to automate or define the state of a system.
 `Puppet Forge <https://forge.puppetlabs.com/>`_ is a repository for modules written
 by the community for Open Source and Enterprise Puppet.
 
@@ -261,7 +261,7 @@ how each node should be configured and sends it to the agent. The agent enforces
 change as prescribed in the catalog and sends a report back to the Puppet Master.
 
 Facter is an interesting tool that ships with Puppet that pulls basic facts about
-the System. These facts can be referenced as a variable while writing your
+the system. These facts can be referenced as a variable while writing your
 Puppet modules.
 
 .. code-block:: console
@@ -328,7 +328,7 @@ everytime the sshd configuration file is changed.
         hasrestart=> true,
     }
 
-For more information checkout `Puppet Labs Documentation <http://docs.puppetlabs.com>`_
+For more information, refer to the `Puppet Labs Documentation <http://docs.puppetlabs.com>`_
 
 Blueprint
 ---------
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
@@ -35,7 +35,7 @@ and deployable.
 Kivy is written in Python, based on OpenGL and supports different input devices
 such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on.
 
-Kivy is actively being developed by a community and free to use. It operates
+Kivy is actively being developed by a community and is free to use. It operates
 on all major platforms (Linux, OSX, Windows, Android).
 
 The main resource for information is the website: http://kivy.org
diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst
@@ -26,7 +26,7 @@ IPython
 
 `IPython <http://ipython.org/>`_ is an enhanced version of Python interpreter,
 which provides features of great interest to scientists. The `inline mode`
-allow graphics and plots to be displayed in the terminal (Qt based version).
+allows graphics and plots to be displayed in the terminal (Qt based version).
 Moreover, the `notebook` mode supports literate programming and reproducible
 science generating a web-based Python notebook. This notebook allows you to
 store chunks of Python code along side the results and additional comments
@@ -55,9 +55,9 @@ NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+.
 Numba
 -----
 
-`Numba <http://numba.pydata.org>`_ is an Numpy aware Python compiler
+`Numba <http://numba.pydata.org>`_ is a NumPy aware Python compiler
 (just-in-time (JIT) specializing compiler) which compiles annotated Python (and
-Numpy) code to LLVM (Low Level Virtual Machine) through special decorators.
+NumPy) code to LLVM (Low Level Virtual Machine) through special decorators.
 Briefly, Numba uses a system that compiles Python code with LLVM to code which
 can be natively executed at runtime.
 
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
@@ -3,7 +3,7 @@ Web Applications
 ================
 
 As a powerful scripting language adapted to both fast prototyping
-and bigger projects, Python is widely used in Web applications
+and bigger projects, Python is widely used in web application
 development.
 
 Context
@@ -84,8 +84,8 @@ Werkzeug
 `Werkzeug <http://werkzeug.pocoo.org/>`_ is not actually a real framework, but
 rather a very powerful set of tools for building web applications. It provides
 URL routing utilities, request and response objects and a basic development
-server. It is mostly used where users need bigger flexibility for their
-application that is not commonly found in other web frameworks.
+server. It is mostly used where users need more flexibility for their
+application than is commonly found in other web frameworks.
 
 Support can be found on its `mailing list <http://werkzeug.pocoo.org/community/#mailinglist>`_.
 
@@ -179,7 +179,7 @@ variables <https://uwsgi-docs.readthedocs.org/en/latest/Vars.html>`_.
 Server Best Practices
 :::::::::::::::::::::
 
-The majority of self hosted Python applications today are hosted with a WSGI
+The majority of self-hosted Python applications today are hosted with a WSGI
 server such as :ref:`Gunicorn <gunicorn-ref>`, either directly or behind a
 lightweight web server such as :ref:`nginx <nginx-ref>`.
 
@@ -195,7 +195,7 @@ Platform-as-a-Service
 
 Platform-as-a-Service (PaaS) is a type of cloud computing infrastructure
 which abstracts and manages infrastructure, routing, and scaling of web
-applications. When using PaaS, application developers can focus on writing
+applications. When using a PaaS, application developers can focus on writing
 application code rather than needing to be concerned with deployment
 details.
 
@@ -327,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 complicated to use.
 
 .. code-block:: python
 
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
@@ -24,13 +24,13 @@ Use `pip <http://pypi.python.org/pypi/pip>`_.  More details `here <http://stacko
 Personal PyPI
 -------------
 
-If you want to install packages from a source different from PyPI, (say, if
+If you want to install packages from a source other than PyPI, (say, if
 your packages are *proprietary*), you can do it by hosting a simple http server,
 running from the directory which holds those packages which need to be installed.
 
 **Showing an example is always beneficial**
 
-Say if you are after installing a package called :file:`MyPackage.tar.gz`,  and
+For example, if you want to install a package called :file:`MyPackage.tar.gz`,  and
 assuming this is your directory structure:
 
 
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
@@ -11,7 +11,7 @@ described in the next section before you start building Python applications
 for real-world use. In particular, you should always install Setuptools, as it
 makes it much easier for you to use other third-party Python libraries.
 
-The version of Python that ships with OS X is great for learning. Yet, it's not
+The version of Python that ships with OS X is great for learning but it's not
 good for development. The version shipped with OS X may be out of date from the
 `official current Python release <https://www.python.org/downloads/mac-osx/>`_,
 which is considered the stable production version.
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
@@ -266,10 +266,10 @@ logic (called pure functions) allow the following benefits:
 - Pure functions are easier to test with unit-tests: There is less
   need for complex context setup and data cleaning afterwards.
 
-- Pure functions are easier to manipulate, decorate, and pass-around.
+- Pure functions are easier to manipulate, decorate, and pass around.
 
-In summary, pure functions, without any context or side-effects, are more
-efficient building blocks than classes and objects for some architectures.
+In summary, pure functions are more efficient building blocks than classes
+and objects for some architectures because they have no context or side-effects.
 
 Obviously, object-orientation is useful and even necessary in many cases, for
 example when developing graphical desktop applications or games, where the
@@ -314,7 +314,7 @@ of the function logic.
 Dynamic typing
 --------------
 
-Python is said to be dynamically typed, which means that variables
+Python is dynamically typed, which means that variables
 do not have a fixed type. In fact, in Python, variables are very
 different from what they are in many other languages, specifically
 statically-typed languages. Variables are not a segment of the computer's
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
@@ -88,7 +88,7 @@ Arguments can be passed to functions in four different ways.
 
 1. **Positional arguments** are mandatory and have no default values. They are the
 simplest form of arguments and they can be used for the few function arguments
-that are fully part of the functions meaning and their order is natural. For
+that are fully part of the function's meaning and their order is natural. For
 instance, in ``send(message, recipient)`` or ``point(x, y)`` the user of the
 function has no difficulty remembering that those two functions require two
 arguments, and in which order.
@@ -102,7 +102,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 is more difficult to remember
-and using keyword argument with default values is helpful. For instance, a more
+and using keyword arguments 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
 passed another value.
@@ -165,7 +165,7 @@ Avoid the magical wand
 ~~~~~~~~~~~~~~~~~~~~~~
 
 A powerful tool for hackers, Python comes with a very rich set of hooks and
-tools allowing to do almost any kind of tricky tricks. For instance, it is
+tools allowing you to do almost any kind of tricky tricks. For instance, it is
 possible to do each of the following:
 
 * change how objects are created and instantiated
@@ -212,7 +212,7 @@ 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 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.
+but making a public property private might be a much harder operation.
 
 Returning values
 ~~~~~~~~~~~~~~~~
@@ -374,7 +374,7 @@ 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.
+the hash of the dictionary, finding keys in the dictionary 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.
 
@@ -422,7 +422,7 @@ 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
 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:
+command in your terminal:
 
 
 .. code-block:: console
@@ -639,6 +639,6 @@ and square braces.
     from some.deep.module.inside.a.module import (
         a_nice_function, another_nice_function, yet_another_nice_function)
 
-However, more often than not having to split long logical line is a sign that
+However, more often than not, having to split a long logical line is a sign that
 you are trying to do too many things at the same time, which may hinder
 readability.
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
@@ -19,8 +19,8 @@ Some general rules of testing:
   usually handled by :meth:`setUp()` and :meth:`tearDown()` methods.
 
 - Try hard to make tests that run fast. If one single test needs more than a
-  few millisecond to run, development will be slowed down or the tests will
-  not be run as often as desirable. In some cases, tests can't be fast because
+  few milliseconds to run, development will be slowed down or the tests will
+  not be run as often as is desirable. In some cases, tests can't be fast because
   they need a complex data structure to work on, and this data structure must
   be loaded every time the test runs. Keep these heavier tests in a separate
   test suite that is run by some scheduled task, and run all other tests as
