Merge pull request #955 from apjanke/typos2

More typo, grammar, and style fixes

CONTRIBUTING.md

@@ -17,7 +17,7 @@ pip install --user sphinx
 
 Then navigate to the directory of the Makefile and ```make build``` or ```make html```. Sphinx will then generate the HTML in a folder called `_build/html/`
 
-After navigating to this folder, you can then use Python's built in webserver to view your changes locally:
+After navigating to this folder, you can then use Python's built in web server to view your changes locally:
 
 ``` bash
 python3 -m http.server

docs/dev/env.rst

@@ -188,7 +188,7 @@ Spyder
 
 `Spyder <https://github.com/spyder-ide/spyder>`_ is an IDE specifically geared
 toward working with scientific Python libraries (namely
-`Scipy <http://www.scipy.org/>`_). It includes integration with pyflakes_,
+`SciPy <http://www.scipy.org/>`_). It includes integration with pyflakes_,
 `pylint <http://www.logilab.org/857>`_ and
 `rope <https://github.com/python-rope/rope>`_.
 

docs/intro/documentation.rst

@@ -35,14 +35,14 @@ pydoc
 :program:`pydoc` is a utility that is installed when you install Python.
 It allows you to quickly retrieve and search for documentation from your
 shell. For example, if you needed a quick refresher on the
-:mod:`time` module, pulling up documentation would be as simple as
+:mod:`time` module, pulling up documentation would be as simple as:
 
     .. code-block:: console
 
        $ pydoc time
 
 The above command is essentially equivalent to opening the Python REPL
-and running
+and running:
 
     .. code-block:: pycon
 

docs/intro/learning.rst

@@ -37,24 +37,26 @@ pythonbasics.org is an introductiory tutorial for beginners. The tutorial includ
 Python for Beginners
 ~~~~~~~~~~~~~~~~~~~~
 
-thepythonguru.com is a tutorial focuses on beginner programmers. It covers many python concepts
+thepythonguru.com is a tutorial focused on beginner programmers. It covers many Python concepts
-in depth. It also teaches you some advance constructs of python like lambda expression, regular expression.
+in depth. It also teaches you some advanced constructs of Python like lambda expressions and regular expressions.
-At last it finishes off with  tutorial "How to access MySQL db using python"
+And last it finishes off with the tutorial "How to access MySQL db using Python"
 
-
+   `Python for Beginners <http://thepythonguru.com/>`_
-   `Python for beginners <http://thepythonguru.com/>`_
 
 Learn Python Interactive Tutorial
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Learnpython.org is an easy non-intimidating way to get introduced to Python.
 The website takes the same approach used on the popular
-`Try Ruby <http://tryruby.org/>`_ website, it has an interactive Python
+`Try Ruby <http://tryruby.org/>`_ website. It has an interactive Python
 interpreter built into the site that allows you to go through the lessons
 without having to install Python locally.
 
     `Learn Python <http://www.learnpython.org/>`_
 
+Python for You and Me
+~~~~~~~~~~~~~~~~~~~~~
+
 If you want a more traditional book, *Python For You and Me* is an excellent
 resource for learning all aspects of the language.
 
@@ -71,7 +73,7 @@ Techbeamers.com provides step-by-step tutorials to teach Python. Each tutorial i
 Online Python Tutor
 ~~~~~~~~~~~~~~~~~~~
 
-Online Python Tutor gives you a visual step by step
+Online Python Tutor gives you a visual step-by-step
 representation of how your program runs. Python Tutor
 helps people overcome a fundamental barrier to learning
 programming by understanding what happens as the computer
@@ -133,7 +135,7 @@ Think Python: How to Think Like a Computer Scientist
 
 Think Python attempts to give an introduction to basic concepts in computer
 science through the use of the Python language. The focus was to create a book
-with plenty of exercises, minimal jargon and a section in each chapter devoted
+with plenty of exercises, minimal jargon, and a section in each chapter devoted
 to the subject of debugging.
 
 While exploring the various features available in the Python language the
@@ -141,7 +143,7 @@ author weaves in various design patterns and best practices.
 
 The book also includes several case studies which have the reader explore the
 topics discussed in the book in greater detail by applying those topics to
-real-world examples. Case studies include assignments in GUI and Markov
+real-world examples. Case studies include assignments in GUI programming and Markov
 Analysis.
 
     `Think Python <http://greenteapress.com/thinkpython/html/index.html>`_
@@ -191,7 +193,7 @@ Code the blocks
 *Code the blocks* provides free and interactive Python tutorials for
 beginners. It combines Python programming with a 3D environment where
 you "place blocks" and construct structures. The tutorials teach you
-how to use Python to create progressively elaborate 3D structures,
+how to use Python to create progressively more elaborate 3D structures,
 making the process of learning Python fun and engaging.
 
     `Code the blocks <https://codetheblocks.com/tutorials/introduction>`_
@@ -204,9 +206,9 @@ Intermediate
 Python Tricks: The Book
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Discover Python's best practices with simple examples and start writing even more beautiful + Pythonic code. "Python Tricks: The Book" shows you exactly how.
+Discover Python's best practices with simple examples and start writing even more beautiful + Pythonic code. *Python Tricks: The Book* shows you exactly how.
 
-You’ll master intermediate and advanced-level features in Python with practical examples and a clear narrative:
+You’ll master intermediate and advanced-level features in Python with practical examples and a clear narrative.
 
     `Python Tricks: The Book <https://realpython.com/products/python-tricks-book/>`_
 
@@ -214,7 +216,7 @@ Effective Python
 ~~~~~~~~~~~~~~~~
 
 This book contains 59 specific ways to improve writing Pythonic code. At 227
-pages, it is a very brief overview of some of the most commons adapations
+pages, it is a very brief overview of some of the most common adapations
 programmers need to make to become efficient intermediate level Python
 programmers.
 
@@ -241,13 +243,13 @@ Expert Python Programming deals with best practices in programming Python and
 is focused on the more advanced crowd.
 
 It starts with topics like decorators (with caching, proxy, and context manager
-case-studies), method resolution order, using super() and meta-programming, and
+case studies), method resolution order, using super() and meta-programming, and
 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 such as writing documentation, test-driven
-development, version control, optimization and profiling.
+development, version control, optimization, and profiling.
 
     `Expert Python Programming <http://www.packtpub.com/expert-python-programming/book>`_
 
@@ -261,7 +263,7 @@ and can make classes and objects behave in different and magical ways.
 
     `A Guide to Python's Magic Methods <http://www.rafekettler.com/magicmethods.html>`_
 
-.. note:: The Rafekettler.com is currently down, you can go to their Github version directly. Here you can find a PDF version:
+.. note:: Rafekettler.com is currently down; you can go to their GitHub version directly. Here you can find a PDF version:
     `A Guide to Python's Magic Methods (repo on GitHub) <https://github.com/RafeKettler/magicmethods/blob/master/magicmethods.pdf>`_
 
 
@@ -317,7 +319,7 @@ Transforming Code into Beautiful, Idiomatic Python
 
 Transforming Code into Beautiful, Idiomatic Python is a video by Raymond Hettinger.
 Learn to take better advantage of Python's best features and improve existing code
-through a series of code transformations, "When you see this, do that instead."
+through a series of code transformations: "When you see this, do that instead."
 
     `Transforming Code into Beautiful, Idiomatic Python <https://www.youtube.com/watch?v=OSGv2VnC0go>`_
 
@@ -328,7 +330,7 @@ Fullstack Python
 Fullstack Python offers a complete top-to-bottom resource for web development
 using Python.
 
-From setting up the webserver, to designing the front-end, choosing a database,
+From setting up the web server, to designing the front-end, choosing a database,
 optimizing/scaling, etc.
 
 As the name suggests, it covers everything you need to build and run a complete
@@ -353,7 +355,7 @@ Python in a Nutshell
 ~~~~~~~~~~~~~~~~~~~~
 
 Python in a Nutshell, written by Alex Martelli, covers most cross-platform
-Python's usage, from its syntax to built-in libraries to advanced topics such
+Python usage, from its syntax to built-in libraries to advanced topics such
 as writing C extensions.
 
     `Python in a Nutshell <http://shop.oreilly.com/product/9780596001889.do>`_
@@ -361,7 +363,7 @@ as writing C extensions.
 The Python Language Reference
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This is Python's reference manual, it covers the syntax and the core semantics
+This is Python's reference manual. It covers the syntax and the core semantics
 of the language.
 
     `The Python Language Reference <http://docs.python.org/reference/index.html>`_
@@ -388,7 +390,7 @@ Python Cookbook
 ~~~~~~~~~~~~~~~
 
 Python Cookbook, written by David Beazley and Brian K. Jones, is packed with
-practical recipes. This book covers the core python language as well as tasks
+practical recipes. This book covers the core Python language as well as tasks
 common to a wide variety of application domains.
 
     `Python Cookbook <http://shop.oreilly.com/product/0636920027072.do>`_
@@ -396,7 +398,7 @@ common to a wide variety of application domains.
 Writing Idiomatic Python
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-"Writing Idiomatic Python", written by Jeff Knupp, contains the most common and
+Writing Idiomatic Python, written by Jeff Knupp, contains the most common and
 important Python idioms in a format that maximizes identification and
 understanding.  Each idiom is presented as a recommendation of a way to write
 some commonly used piece of code, followed by an explanation of why the idiom

docs/intro/news.rst

@@ -87,7 +87,7 @@ Python News is the news section in the official Python web site
 Import Python Weekly
 ********************
 
-Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets
+Weekly Python Newsletter containing Python Articles, Projects, Videos, and Tweets
 delivered in your inbox.  Keep Your Python Programming Skills Updated.
 
     `Import Python Weekly Newsletter <http://www.importpython.com/newsletter/>`_
@@ -97,6 +97,6 @@ delivered in your inbox.  Keep Your Python Programming Skills Updated.
 Awesome Python Newsletter
 *************************
 
-A weekly overview of the most popular Python news, articles and packages.
+A weekly overview of the most popular Python news, articles, and packages.
 
     `Awesome Python Newsletter <https://python.libhunt.com/newsletter>`_

docs/notes/styleguide.rst

@@ -137,7 +137,7 @@ Python examples:
 Externally Linking
 ******************
 
-* Prefer labels for well known subjects (ex: proper nouns) when linking:
+* Prefer labels for well known subjects (e.g. proper nouns) when linking:
 
   .. code-block:: rest
 
@@ -152,7 +152,7 @@ Externally Linking
 
       Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
 
-* Avoid using labels such as "click here", "this", etc. preferring
+* Avoid using labels such as "click here", "this", etc., preferring
   descriptive labels (SEO worthy) instead.
 
 

docs/scenarios/admin.rst

@@ -23,7 +23,7 @@ Install Fabric:
 
 The following code will create two tasks that we can use: ``memory_usage`` and
 ``deploy``. The former will output the memory usage on each machine. The
-latter will ssh into each server, cd to our project directory, activate the
+latter will SSH into each server, cd to our project directory, activate the
 virtual environment, pull the newest codebase, and restart the application
 server.
 
@@ -101,7 +101,7 @@ The following command lists all available minion hosts, using the ping module.
 
     $ salt '*' test.ping
 
-The host filtering is accomplished by matching the minion id,
+The host filtering is accomplished by matching the minion id
 or using the grains system. The
 `grains <http://docs.saltstack.org/en/latest/topics/targeting/grains.html>`_
 system uses static host information like the operating system version or the
@@ -131,7 +131,7 @@ it will install and start the Apache server:
         - require:
           - pkg: apache
 
-State files can be written using YAML, the Jinja2 template system or pure Python.
+State files can be written using YAML, the Jinja2 template system, or pure Python.
 
     `Salt Documentation <http://docs.saltstack.com>`_
 
@@ -141,7 +141,7 @@ Psutil
 ******
 
 `Psutil <https://github.com/giampaolo/psutil/>`_ is an interface to different
-system information (e.g. CPU, memory, disks, network, users and processes).
+system information (e.g. CPU, memory, disks, network, users, and processes).
 
 Here is an example to be aware of some server overload. If any of the
 tests (net, CPU) fail, it will send an email.
@@ -263,9 +263,9 @@ configures itself and this distributed approach makes Chef a scalable automation
 
 Chef works by using custom recipes (configuration elements), implemented in cookbooks. Cookbooks, which are basically
 packages for infrastructure choices, are usually stored in your Chef server.
-Read the `Digital Ocean tutorial series
+Read the `DigitalOcean tutorial series
 <https://www.digitalocean.com/community/tutorials/how-to-install-a-chef-server-workstation-and-client-on-ubuntu-vps-instances>`_
-on chef to learn how to create a simple Chef Server.
+on Chef to learn how to create a simple Chef Server.
 
 To create a simple cookbook the `knife <https://docs.chef.io/knife.html>`_ command is used:
 
@@ -299,8 +299,8 @@ Puppet Agents are installed on nodes whose state needs to be monitored or
 changed.  A designated server known as the Puppet Master is responsible for
 orchestrating the agent nodes.
 
-Agent nodes send basic facts about the system such as to the operating system,
+Agent nodes send basic facts about the system such as the operating system,
-kernel, architecture, ip address, hostname etc. to the Puppet Master.
+kernel, architecture, IP address, hostname, etc. to the Puppet Master.
 The Puppet Master then compiles a catalog with information provided by the
 agents on how each node should be configured and sends it to the agent. The
 agent enforces the change as prescribed in the catalog and sends a report back
@@ -320,7 +320,7 @@ your Puppet modules.
     Ubuntu
 
 Writing Modules in Puppet is pretty straight forward. Puppet Manifests together
-form Puppet Modules. Puppet manifest end with an extension of ``.pp``.
+form Puppet Modules. Puppet manifests end with an extension of ``.pp``.
 Here is an example of 'Hello World' in Puppet.
 
 .. code-block:: puppet
@@ -334,7 +334,7 @@ Here is an example of 'Hello World' in Puppet.
 Here is another example with system based logic. Note how the operating system
 fact is being used as a variable prepended with the ``$`` sign. Similarly, this
 holds true for other facts such as hostname which can be referenced by
-``$hostname``
+``$hostname``.
 
 .. code-block:: puppet
 
@@ -346,10 +346,10 @@ holds true for other facts such as hostname which can be referenced by
     }
 
 There are several resource types for Puppet but the package-file-service
-paradigm is all you need for undertaking majority of the configuration
+paradigm is all you need for undertaking the majority of the configuration
 management. The following Puppet code makes sure that the OpenSSH-Server
 package is installed in a system and the sshd service is notified to restart
-everytime the sshd configuration file is changed.
+every time the sshd configuration file is changed.
 
 .. code-block:: puppet
 
@@ -407,6 +407,6 @@ monitoring framework written in Python. Its main goal is to give users a flexibl
 architecture for their monitoring system that is designed to scale to large
 environments.
 
-Shinken is backwards-compatible with the Nagios configuration standard, and
+Shinken is backwards-compatible with the Nagios configuration standard and
-plugins.It works on any operating system, and architecture that supports Python
+plugins. It works on any operating system and architecture that supports Python,
-which includes Windows, GNU/Linux, and FreeBSD.
+which includes Windows, Linux, and FreeBSD.

docs/scenarios/ci.rst

@@ -14,7 +14,7 @@ Why?
 ****
 
 Martin Fowler, who first wrote about `Continuous Integration <http://martinfowler.com/articles/continuousIntegration.html>`_
-(short: CI) together with Kent Beck, describes the CI as follows:
+(short: CI) together with Kent Beck, describes CI as follows:
 
     Continuous Integration is a software development practice where members of
     a team integrate their work frequently, usually each person integrates at
@@ -29,8 +29,7 @@ Martin Fowler, who first wrote about `Continuous Integration <http://martinfowle
 Jenkins
 *******
 
-`Jenkins CI <http://jenkins-ci.org>`_ is an extensible continuous integration
+`Jenkins CI <http://jenkins-ci.org>`_ is an extensible Continuous Integration engine. Use it.
-engine. Use it.
 
 
 ********
@@ -46,7 +45,7 @@ Tox
 ***
 
 `tox <https://tox.readthedocs.io/en/latest/>`_ is an automation tool providing
-packaging, testing and deployment of Python software right from the console or
+packaging, testing, and deployment of Python software right from the console or
 CI server. It is a generic virtualenv management and test command line tool
 which provides the following features:
 
@@ -55,7 +54,7 @@ which provides the following features:
 * Running tests in each of the environments, configuring your test tool of
   choice
 * Acting as a front-end to Continuous Integration servers, reducing boilerplate
-  and merging CI and shell-based testing.
+  and merging CI and shell-based testing
 
 
 *********
@@ -66,7 +65,7 @@ Travis-CI
 tests for open source projects for free. It provides multiple workers to run
 Python tests on and seamlessly integrates with GitHub. You can even have it
 comment on your Pull Requests whether this particular changeset breaks the
-build or not. So if you are hosting your code on GitHub, travis-ci is a great
+build or not. So if you are hosting your code on GitHub, Travis-CI is a great
 and easy way to get started with Continuous Integration.
 
 In order to get started, add a :file:`.travis.yml` file to your repository with
@@ -86,12 +85,12 @@ this example content::
 
 
 This will get your project tested on all the listed Python versions by
-running the given script, and will only build the master branch. There are a
+running the given script, and will only build the ``master`` branch. There are a
-lot more options you can enable, like notifications, before and after steps
+lot more options you can enable, like notifications, before and after steps,
-and much more. The `travis-ci docs <https://docs.travis-ci.com/user/languages/python/>`_
+and much more. The `Travis-CI docs <https://docs.travis-ci.com/user/languages/python/>`_
 explain all of these options, and are very thorough.
 
-In order to activate testing for your project, go to `the travis-ci site <https://travis-ci.org/>`_
+In order to activate testing for your project, go to `the Travis-CI site <https://travis-ci.org/>`_
 and login with your GitHub account. Then activate your project in your
 profile settings and you're ready to go. From now on, your project's tests
 will be run on every push to GitHub.

docs/scenarios/cli.rst

@@ -15,12 +15,12 @@ switches.
 
 Some popular command-line applications include:
 
-* `Grep <http://en.wikipedia.org/wiki/Grep>`_ - A plain-text data search utility
+* `grep <http://en.wikipedia.org/wiki/grep>`_ - A plain-text data search utility
 * `curl <http://curl.haxx.se/>`_ - A tool for data transfer with URL syntax
-* `httpie <https://github.com/jakubroztocil/httpie>`_ - A command line HTTP
+* `httpie <https://github.com/jakubroztocil/httpie>`_ - A command-line HTTP
   client, a user-friendly cURL replacement
-* `git <http://git-scm.com/>`_ - A distributed version control system
+* `Git <http://git-scm.com/>`_ - A distributed version control system
-* `mercurial <https://www.mercurial-scm.org/>`_ - A distributed version control
+* `Mercurial <https://www.mercurial-scm.org/>`_ - A distributed version control
   system primarily written in Python
 
 
@@ -30,8 +30,8 @@ Clint
 
 `clint <https://pypi.python.org/pypi/clint/>`_ is a Python module which is
 filled with very useful tools for developing command-line applications.
-It supports features such as; CLI colors and indents, simple and powerful
+It supports features such as: CLI colors and indents, simple and powerful
-column printer, iterator based progress bars and implicit argument handling.
+column printer, iterator based progress bars, and implicit argument handling.
 
 
 *****
@@ -40,7 +40,7 @@ Click
 
 `click <http://click.pocoo.org/>`_ is a Python package for creating
 command-line interfaces in a composable way with as little code as
-possible. This “Command-line Interface Creation Kit” is highly
+possible. This “Command-Line Interface Creation Kit” is highly
 configurable but comes with good defaults out of the box.
 
 
@@ -61,8 +61,8 @@ Plac
 over the Python standard library `argparse <http://docs.python.org/2/library/argparse.html>`_,
 which hides most of its complexity by using a declarative interface: the
 argument parser is inferred rather than written down by imperatively. This
-module targets especially unsophisticated users, programmers, sys-admins,
+module targets especially unsophisticated users, programmers, sysadmins,
-scientists and in general people writing throw-away scripts for themselves,
+scientists, and in general people writing throw-away scripts for themselves,
 who choose to create a command-line interface because it is quick and simple.
 
 
@@ -73,7 +73,7 @@ Cliff
 `Cliff <http://docs.openstack.org/developer/cliff/>`_  is a framework for
 building command-line programs. It uses setuptools entry points to provide
 subcommands, output formatters, and other extensions. The framework is meant
-to be used to create multi-level commands such as subversion and git, where
+to be used to create multi-level commands such as ``svn`` and ``git``, where
 the main program handles some basic argument parsing and then invokes a
 sub-command to do the work.
 
@@ -83,11 +83,11 @@ Cement
 ******
 
 `Cement <http://builtoncement.com/>`_ is an advanced CLI Application Framework.
-Its goal is to introduce a standard, and feature-full platform
+Its goal is to introduce a standard and feature-full platform
 for both simple and complex command line applications as well
 as support rapid development needs without sacrificing quality.
-Cement is flexible, and it's use cases span from the simplicity of a micro-framework
+Cement is flexible, and its use cases span from the simplicity of a micro-framework
-to the complexity of a meg-framework.
+to the complexity of a mega-framework.
 
 
 ***********
@@ -95,9 +95,8 @@ Python Fire
 ***********
 
 `Python Fire <https://github.com/google/python-fire/>`_ is a library for
-automatically generating command line interfaces from absolutely any Python
+automatically generating command-line interfaces from absolutely any Python
 object. It can help debug Python code more easily from the command line,
 create CLI interfaces to existing code, allow you to interactively explore
 code in a REPL, and simplify transitioning between Python and Bash (or any
 other shell).
-

docs/scenarios/clibs.rst

@@ -36,11 +36,11 @@ ABI Interaction
 ctypes
 ******
 
-`ctypes <https://docs.python.org/3/library/ctypes.html>`_ is the de facto
+`ctypes <https://docs.python.org/3/library/ctypes.html>`_ is the de facto standard
 library for interfacing with C/C++ from CPython, and it provides not only
 full access to the native C interface of most major operating systems (e.g.,
 kernel32 on Windows, or libc on \*nix), but also provides support for loading
-and interfacing with dynamic libraries, such as DLLs or shared objects at
+and interfacing with dynamic libraries, such as DLLs or shared objects, at
 runtime. It does bring along with it a whole host of types for interacting
 with system APIs, and allows you to rather easily define your own complex
 types, such as structs and unions, and allows you to modify things such as
@@ -82,7 +82,7 @@ large number of scripting languages), is a tool for generating bindings for
 interpreted languages from C/C++ header files. It is extremely simple to use:
 the consumer simply needs to define an interface file (detailed in the
 tutorial and documentations), include the requisite C/C++ headers, and run
-the build tool against them. While it does have some limits, (it currently
+the build tool against them. While it does have some limits (it currently
 seems to have issues with a small subset of newer C++ features, and getting
 template-heavy code to work can be a bit verbose), it provides a great deal
 of power and exposes lots of features to Python with little effort.
@@ -137,5 +137,5 @@ Boost.Python
 `Boost.Python <http://www.boost.org/doc/libs/1_59_0/libs/python/doc/>`_
 requires a bit more manual work to expose C++ object functionality, but
 it is capable of providing all the same features SWIG does and then some,
-to include providing wrappers to access PyObjects in C++, extracting SWIG-
+to include providing wrappers to access PyObjects in C++, extracting SWIG
 wrapper objects, and even embedding bits of Python into your C++ code.

docs/scenarios/crypto.rst

@@ -7,16 +7,16 @@ Cryptography
 
 
 ************
-Cryptography
+cryptography
 ************
 
-`Cryptography <https://cryptography.io/en/latest/>`_ is an actively developed
+`cryptography <https://cryptography.io/en/latest/>`_ is an actively developed
 library that provides cryptographic recipes and primitives. It supports
-Python 2.6-2.7, Python 3.3+ and PyPy.
+Python 2.6-2.7, Python 3.3+, and PyPy.
 
 
-Cryptography is divided into two layers of recipes and hazardous materials
+cryptography is divided into two layers of recipes and hazardous materials
-(hazmat).  The recipes layer provides simple API for proper symmetric
+(hazmat).  The recipes layer provides a simple API for proper symmetric
 encryption and the hazmat layer provides low-level cryptographic primitives.
 
 
@@ -46,9 +46,10 @@ Example code using high level symmetric encryption recipe:
 GPGME bindings
 **************
 
-The `GPGME Python bindings <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/>`_ provide pythonic access to `GPG Made Easy <https://dev.gnupg.org/source/gpgme/browse/master/>`_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4 and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries.
+The `GPGME Python bindings <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/>`_ provide Pythonic access to `GPG Made Easy <https://dev.gnupg.org/source/gpgme/browse/master/>`_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt, and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4, and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries.
 
-A more comprehensive `GPGME Python Bindings HOWTO <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/docs/GPGMEpythonHOWTOen.org>`_ is available with the source, and a HTML version is available `on http://files.au.adversary.org <http://files.au.adversary.org/crypto/GPGMEpythonHOWTOen.html>`_.  Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `on gnupg.org <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/examples/howto/>`_.
+
+A more comprehensive `GPGME Python Bindings HOWTO <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/docs/GPGMEpythonHOWTOen.org>`_ is available with the source, and an HTML version is available `at http://files.au.adversary.org <http://files.au.adversary.org/crypto/GPGMEpythonHOWTOen.html>`_.  Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `at gnupg.org <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/examples/howto/>`_.
 
 Available under the same terms as the rest of the GnuPG Project: GPLv2 and LGPLv2.1, both with the "or any later version" clause.
 

docs/scenarios/db.rst

@@ -12,7 +12,7 @@ DB-API
 
 The Python Database API (DB-API) defines a standard interface for Python
 database access modules. It's documented in :pep:`249`.
-Nearly all Python database modules such as `sqlite3`, `psycopg` and
+Nearly all Python database modules such as `sqlite3`, `psycopg`, and
 `mysql-python` conform to this interface.
 
 Tutorials that explain how to work with modules that conform to this interface can be found
@@ -39,7 +39,7 @@ Records
 
 `Records <https://github.com/kennethreitz/records>`_ is minimalist SQL library,
 designed for sending raw SQL queries to various databases. Data can be used
-programmatically, or exported to a number of useful data formats.
+programmatically or exported to a number of useful data formats.
 
 .. code-block:: console
 
@@ -73,11 +73,11 @@ peewee
 
 `peewee <http://docs.peewee-orm.com/en/latest/>`_ is another ORM with a focus
 on being lightweight with support for Python 2.6+ and 3.2+ which supports
-SQLite, MySQL and Postgres by default. The
+SQLite, MySQL, and PostgreSQL by default. The
 `model layer <https://peewee.readthedocs.io/en/latest/peewee/quickstart.html#model-definition>`_
 is similar to that of the Django ORM and it has
 `SQL-like methods <https://peewee.readthedocs.io/en/latest/peewee/quickstart.html#retrieving-data>`_
-to query data. While SQLite, MySQL and Postgres are supported out-of-the-box,
+to query data. While SQLite, MySQL, and PostgreSQL are supported out-of-the-box,
 there is a `collection of add-ons <https://peewee.readthedocs.io/en/latest/peewee/playhouse.html#playhouse>`_
 available.
 
@@ -88,9 +88,9 @@ PonyORM
 
 `PonyORM <http://ponyorm.com/>`_ is an ORM that takes a different approach to
 querying the database. Instead of writing an SQL-like language or boolean
-expressions, Python's generator syntax is used. There's also an graphical
+expressions, Python's generator syntax is used. There's also a graphical
 schema editor that can generate PonyORM entities for you. It supports Python
-2.6+ and Python 3.3+ and can connect to SQLite, MySQL, Postgres & Oracle
+2.6+ and Python 3.3+ and can connect to SQLite, MySQL, PostgreSQL, and Oracle.
 
 
 *********
@@ -98,8 +98,8 @@ SQLObject
 *********
 
 `SQLObject <http://www.sqlobject.org/>`_ is yet another ORM. It supports a wide
-variety of databases: Common database systems MySQL, Postgres and SQLite and
+variety of databases: common database systems like MySQL, PostgreSQL, and SQLite and
-more exotic systems like SAP DB, SyBase and MSSQL. It only supports Python 2
+more exotic systems like SAP DB, SyBase, and Microsoft SQL Server. It only supports Python 2
 from Python 2.6 upwards.
 
-.. There's no official information on this on their page, this information was gathered by looking at their source code
+.. There's no official information on this on their page; this information was gathered by looking at their source code.

docs/scenarios/gui.rst

@@ -14,12 +14,12 @@ Camelot
 *******
 
 `Camelot <http://www.python-camelot.com>`_ provides components for building
-applications on top of Python, SQLAlchemy and Qt.  It is inspired by
+applications on top of Python, SQLAlchemy, and Qt.  It is inspired by
 the Django admin interface.
 
 The main resource for information is the website:
 http://www.python-camelot.com
-and the mailing list https://groups.google.com/forum/#!forum/project-camelot
+and the mailing list https://groups.google.com/forum/#!forum/project-camelot.
 
 
 *****
@@ -44,7 +44,7 @@ applications be ported from PyGTK to PyGObject.
 PyGObject aka (PyGi)
 ********************
 
-`PyGObject <https://wiki.gnome.org/Projects/PyGObject>`_ provides Python bindings, which gives access to the entire GNOME software platform.
+`PyGObject <https://wiki.gnome.org/Projects/PyGObject>`_ provides Python bindings which gives access to the entire GNOME software platform.
 It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial <https://python-gtk-3-tutorial.readthedocs.io/en/latest/>`_.
 
 `API Reference <http://lazka.github.io/pgi-docs/>`_
@@ -59,8 +59,8 @@ enabled media rich applications. The aim is to allow for quick and easy
 interaction design and rapid prototyping, while making your code reusable
 and deployable.
 
-Kivy is written in Python, based on OpenGL and supports different input devices
+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
+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 is free to use. It operates
@@ -111,7 +111,7 @@ application source code to be executed as a standalone desktop application.
 
 `Python Wiki for PyjamasDesktop <http://wiki.python.org/moin/PyjamasDesktop>`_.
 
-The main website; `pyjs Desktop <http://pyjs.org/>`_.
+The main website: `pyjs Desktop <http://pyjs.org/>`_.
 
 
 **
@@ -127,13 +127,13 @@ non-GUI applications.
 PySimpleGUI
 ***********
 
-`PySimpleGUI <https://pysimplegui.readthedocs.io/>`_ is a  wrapper for Tkinter and Qt (others on the way).  The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using tkinter or Qt.  PySimpleGUI code can be "ported" between GUI frameworks by changing import statement.
+`PySimpleGUI <https://pysimplegui.readthedocs.io/>`_ is a  wrapper for Tkinter and Qt (others on the way).  The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using Tkinter or Qt.  PySimpleGUI code can be "ported" between GUI frameworks by changing import statements.
 
 .. code-block:: console
 
   $ pip install pysimplegui
 
-PySimpleGUI is contained in a single PySimpleGUI.py file.  Should pip installation be impossible, pasting the PySimpleGUI.py file into a project's folder is all that's required to import and begin using.
+PySimpleGUI is contained in a single PySimpleGUI.py file.  Should pip installation be impossible, copying the PySimpleGUI.py file into a project's folder is all that's required to import and begin using.
 
 
 ****
@@ -145,7 +145,7 @@ native, cross platform GUI toolkit. Toga consists of a library of base
 components with a shared interface to simplify platform-agnostic GUI
 development.
 
-Toga is available on Mac OS, Windows, Linux (GTK), and mobile platforms such
+Toga is available on mOS, Windows, Linux (GTK), and mobile platforms such
 as Android and iOS.
 
 

docs/scenarios/imaging.rst

@@ -6,7 +6,7 @@ Image Manipulation
 .. image:: /_static/photos/34575689432_3de8e9a348_k_d.jpg
 
 Most image processing and manipulation techniques can be carried out
-effectively using two libraries: Python Imaging Library (PIL)  and OpenSource
+effectively using two libraries: Python Imaging Library (PIL) and Open Source
 Computer Vision (OpenCV).
 
 A brief description of both is given below.
@@ -21,8 +21,8 @@ for short, is one of the core libraries for image manipulation in Python. Unfort
 its development has stagnated, with its last release in 2009.
 
 Luckily for you, there's an actively-developed fork of PIL called
-`Pillow <http://python-pillow.github.io/>`_ - it's easier to install, runs on
+`Pillow <http://python-pillow.github.io/>`_ -- it's easier to install, runs on
-all operating systems, and supports Python 3.
+all major operating systems, and supports Python 3.
 
 Installation
 ~~~~~~~~~~~~
@@ -65,11 +65,11 @@ There are more examples of the Pillow library in the
 `Pillow tutorial <https://pillow.readthedocs.io/en/3.0.x/handbook/tutorial.html>`_.
 
 
-**************************
+***************************
-OpenSource Computer Vision
+Open Source Computer Vision
-**************************
+***************************
 
-OpenSource Computer Vision, more commonly known as OpenCV, is a more advanced
+Open Source Computer Vision, more commonly known as OpenCV, is a more advanced
 image manipulation and processing software than PIL. It has been implemented
 in several languages and is widely used.
 

docs/scenarios/json.rst

@@ -52,7 +52,7 @@ You can also convert the following to JSON:
 simplejson
 **********
 
-The JSON library was added to Python in version 2.6.
+The json library was added to Python in version 2.6.
 If you're using an earlier version of Python, the
 `simplejson <https://simplejson.readthedocs.io/en/latest/>`_ library is
 available via PyPI.
@@ -68,5 +68,5 @@ importing simplejson under a different name:
 
     import simplejson as json
 
-After importing simplejson as json, the above examples will all work as if you
+After importing simplejson as `json`, the above examples will all work as if you
 were using the standard json library.

docs/scenarios/ml.rst

@@ -6,16 +6,16 @@ Machine Learning
 
 .. image:: /_static/photos/34018729885_002ced9b54_k_d.jpg
 
-Python has a vast number of libraries for data analysis, statistics and Machine Learning itself, making it a language of choice for many data scientists.
+Python has a vast number of libraries for data analysis, statistics, and Machine Learning itself, making it a language of choice for many data scientists.
 
-Some widely used packages for Machine Learning and other Data Science applications are enlisted below.
+Some widely used packages for Machine Learning and other data science applications are listed below.
 
 
 ***********
-Scipy Stack
+SciPy Stack
 ***********
 
-The Scipy stack consists of a bunch of core helper packages used in data science, for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications.
+The SciPy stack consists of a bunch of core helper packages used in data science for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications.
 
 The Stack consists of the following packages (link to documentation given):
 
@@ -41,9 +41,9 @@ For installing the full stack, or individual packages, you can refer to the inst
 scikit-learn
 ************
 
-Scikit is a free and open source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks etc. It also has a few sample datasets which can be directly used for training and testing.
+Scikit is a free and open source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks, etc. It also has a few sample datasets which can be directly used for training and testing.
 
-Because of its speed, robustness and easiness to use, it's one of the most widely-used libraries for many Machine Learning applications.
+Because of its speed, robustness, and ease of, it's one of the most widely-used libraries for many Machine Learning applications.
 
 Installation
 ~~~~~~~~~~~~
@@ -60,16 +60,16 @@ Through conda:
 
 	conda install scikit-learn
 
-scikit-learn also comes in shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link <http://scikit-learn.org/stable/install.html>`_.
+scikit-learn also comes shipped with Anaconda (mentioned above). For more installation instructions, refer to `this link <http://scikit-learn.org/stable/install.html>`_.
 
 Example
 ~~~~~~~
 
 For this example, we train a simple classifier on the `Iris dataset <http://en.wikipedia.org/wiki/Iris_flower_data_set>`_, which comes bundled in with scikit-learn.
 
-The dataset takes four features of flowers: sepal length, sepal width, petal length and petal width, and classifies them into three flower species (labels): setosa, versicolor or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor) and 2 (virginica).
+The dataset takes four features of flowers: sepal length, sepal width, petal length, and petal width, and classifies them into three flower species (labels): setosa, versicolor, or virginica. The labels have been represented as numbers in the dataset: 0 (setosa), 1 (versicolor), and 2 (virginica).
 
-We shuffle the Iris dataset, and divide it into separate training and testing sets: keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set, and predict on the testing set.
+We shuffle the Iris dataset and divide it into separate training and testing sets, keeping the last 10 data points for testing and rest for training. We then train the classifier on the training set and predict on the testing set.
 
 .. code-block:: python
 
@@ -120,6 +120,6 @@ Since we're splitting randomly and the classifier trains on every iteration, the
 	[0 1 1 1 0 2 0 2 2 2]
 	100.0
 
-The first line contains the labels (i.e flower species) of the testing data as predicted by our classifier, and the second line contains the actual flower species as given in the dataset. We thus get an accuracy of 100% this time.
+The first line contains the labels (i.e. flower species) of the testing data as predicted by our classifier, and the second line contains the actual flower species as given in the dataset. We thus get an accuracy of 100% this time.
 
 More on scikit-learn can be read in the `documentation <http://scikit-learn.org/stable/user_guide.html>`_.

docs/scenarios/network.rst

@@ -12,8 +12,8 @@ Twisted
 
 `Twisted <http://twistedmatrix.com/trac/>`_ is an event-driven networking
 engine. It can be used to build applications around many different networking
-protocols, including http servers and clients, applications using SMTP, POP3,
+protocols, including HTTP servers and clients, applications using SMTP, POP3,
-IMAP or SSH protocols, instant messaging
+IMAP, or SSH protocols, instant messaging,
 and `much more <http://twistedmatrix.com/trac/wiki/Documentation>`_.
 
 
@@ -30,8 +30,8 @@ message queuing without a message broker. The basic patterns for this are:
   remote procedure call and task distribution pattern.
 - publish-subscribe: connects a set of publishers to a set of subscribers.
   This is a data distribution pattern.
-- push-pull (or pipeline): connects nodes in a fan-out / fan-in pattern that
+- push-pull (or pipeline): connects nodes in a fan-out/fan-in pattern that
-  can have multiple steps, and loops. This is a parallel task distribution
+  can have multiple steps and loops. This is a parallel task distribution
   and collection pattern.
 
 For a quick start, read the `ZeroMQ guide <http://zguide.zeromq.org/page:all>`_.

docs/scenarios/scientific.rst

@@ -16,11 +16,11 @@ and performs well.
 
 Due to its high performance nature, scientific computing in Python often
 utilizes external libraries, typically written in faster languages (like C, or
-FORTRAN for matrix operations). The main libraries used are `NumPy`_, `SciPy`_
+Fortran for matrix operations). The main libraries used are `NumPy`_, `SciPy`_
 and `Matplotlib`_. Going into detail about these libraries is beyond the scope
 of the Python guide. However, a comprehensive introduction to the scientific
 Python ecosystem can be found in the `Python Scientific Lecture Notes
-<http://scipy-lectures.github.com/>`_
+<http://scipy-lectures.github.com/>`_.
 
 
 *****
@@ -35,7 +35,7 @@ which provides features of great interest to scientists. The `inline mode`
 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
+store chunks of Python code alongside the results and additional comments
 (HTML, LaTeX, Markdown). The notebook can then be shared and exported in various
 file formats.
 
@@ -48,7 +48,7 @@ NumPy
 -----
 
 `NumPy <http://numpy.scipy.org/>`_ is a low level library written in C (and
-FORTRAN) for high level mathematical functions. NumPy cleverly overcomes the
+Fortran) for high level mathematical functions. NumPy cleverly overcomes the
 problem of running slower algorithms on Python by using multidimensional arrays
 and functions that operate on arrays. Any algorithm can then be expressed as a
 function on arrays, allowing the algorithms to be run quickly.
@@ -57,7 +57,7 @@ NumPy is part of the SciPy project, and is released as a separate library so
 people who only need the basic requirements can use it without installing the
 rest of SciPy.
 
-NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+.
+NumPy is compatible with Python versions 2.4 through 2.7.2 and 3.1+.
 
 Numba
 -----
@@ -75,7 +75,7 @@ SciPy
 functions. SciPy uses NumPy arrays as the basic data structure, and comes
 with modules for various commonly used tasks in scientific programming,
 including linear algebra, integration (calculus), ordinary differential equation
-solving and signal processing.
+solving, and signal processing.
 
 Matplotlib
 ----------
@@ -84,7 +84,7 @@ Matplotlib
 library for creating interactive 2D and 3D plots that can also be saved as
 manuscript-quality figures. The API in many ways reflects that of `MATLAB
 <http://www.mathworks.com/products/matlab/>`_, easing transition of MATLAB
-users to Python. Many examples, along with the source code to re-create them,
+users to Python. Many examples, along with the source code to recreate them,
 are available in the `matplotlib gallery
 <http://matplotlib.sourceforge.net/gallery.html>`_.
 
@@ -92,10 +92,10 @@ Pandas
 ------
 
 `Pandas <http://pandas.pydata.org/>`_ is data manipulation library
-based on Numpy which provides many useful functions for accessing,
+based on NumPy which provides many useful functions for accessing,
-indexing, merging and grouping data easily. The main data structure (DataFrame)
+indexing, merging, and grouping data easily. The main data structure (DataFrame)
 is close to what could be found in the R statistical package; that is,
-heterogeneous data tables with name indexing, time series operations and
+heterogeneous data tables with name indexing, time series operations, and
 auto-alignment of data.
 
 Rpy2
@@ -112,7 +112,7 @@ PsychoPy
 
 `PsychoPy <http://www.psychopy.org/>`_ is a library for cognitive scientists
 allowing the creation of cognitive psychology and neuroscience experiments.
-The library handles presentation of stimuli, scripting of experimental design
+The library handles presentation of stimuli, scripting of experimental design,
 and data collection.
 
 
@@ -131,7 +131,7 @@ Unofficial Windows Binaries for Python Extension Packages
 
 Many people who do scientific computing are on Windows, yet many of the
 scientific computing packages are notoriously difficult to build and install on
-this platform. `Christoph Gohlke <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_
+this platform. `Christoph Gohlke <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_,
 however, has compiled a list of Windows binaries for many useful Python
 packages.  The list of packages has grown from a mainly scientific Python
 resource to a more general list. If you're on Windows, you may want to check it

docs/scenarios/scrape.rst

@@ -13,7 +13,7 @@ Web Scraping
 Web sites are written using HTML, which means that each web page is a
 structured document. Sometimes it would be great to obtain some data from
 them and preserve the structure while we're at it. Web sites don't always
-provide their data in comfortable formats such as ``csv`` or ``json``.
+provide their data in comfortable formats such as CSV or JSON.
 
 This is where web scraping comes in. Web scraping is the practice of using a
 computer program to sift through a web page and gather the data that you need
@@ -41,7 +41,7 @@ Let's start with the imports:
     import requests
 
 Next we will use ``requests.get`` to retrieve the web page with our data,
-parse it using the ``html`` module and save the results in ``tree``:
+parse it using the ``html`` module, and save the results in ``tree``:
 
 .. code-block:: python
 
@@ -62,10 +62,10 @@ HTML or XML documents. A good introduction to XPath is on
 There are also various tools for obtaining the XPath of elements such as
 FireBug for Firefox or the Chrome Inspector. If you're using Chrome, you
 can right click an element, choose 'Inspect element', highlight the code,
-right click again and choose 'Copy XPath'.
+right click again, and choose 'Copy XPath'.
 
 After a quick analysis, we see that in our page the data is contained in
-two elements - one is a div with title 'buyer-name' and the other is a
+two elements -- one is a div with title 'buyer-name' and the other is a
 span with class 'item-price':
 
 .. code-block:: html

docs/scenarios/serialization.rst

@@ -10,11 +10,11 @@ Data Serialization
 What is data serialization?
 ***************************
 
-Data serialization is the process of converting structured data into a format
+Data serialization is the process of converting structured data to a format
-that allows it to be shared or stored in such a way that its original
+that allows sharing or storage of the data in a form that allows recovery of its original
-structure should be recovered or reconstructed. In some cases, the secondary intention of data
+structure. In some cases, the secondary intention of data
-serialization is to minimize the size of the serialized data which then
+serialization is to minimize the data's size which then
-minimizes disk space or bandwidth requirements.
+reduces disk space or bandwidth requirements.
 
 ********************
 Flat vs. Nested data

docs/scenarios/speed.rst

@@ -200,8 +200,8 @@ These lines both need a remark:
 The `pyximport` module allows you to import :file:`*.pyx` files (e.g.,
 :file:`primesCy.pyx`) with the Cython-compiled version of the `primes`
 function. The `pyximport.install()` command allows the Python interpreter to
-start the Cython compiler directly to generate C-code, which is automatically
+start the Cython compiler directly to generate C code, which is automatically
-compiled to a :file:`*.so` C-library. Cython is then able to import this
+compiled to a :file:`*.so` C library. Cython is then able to import this
 library for you in your Python code, easily and efficiently. With the
 `time.time()` function you are able to compare the time between these 2
 different calls to find 500 prime numbers. On a standard notebook (dual core
@@ -214,7 +214,7 @@ AMD E-450 1.6 GHz), the measured values are:
     Python time: 0.0566 seconds
 
 
-And here the output of an embedded `ARM beaglebone <http://beagleboard.org/Products/BeagleBone>`_ machine:
+And here is the output of an embedded `ARM beaglebone <http://beagleboard.org/Products/BeagleBone>`_ machine:
 
 .. code-block:: console
 
@@ -253,7 +253,7 @@ available.
 
 The ProcessPoolExecutor works in the same way, except instead of using multiple
 threads for its workers, it will use multiple processes. This makes it possible
-to side-step the GIL, however because of the way things are passed to worker
+to side-step the GIL; however, because of the way things are passed to worker
 processes, only picklable objects can be executed and returned.
 
 Because of the way the GIL works, a good rule of thumb is to use a
@@ -264,7 +264,7 @@ executor when the task is computationally expensive.
 There are two main ways of executing things in parallel using the two
 Executors. One way is with the `map(func, iterables)` method. This works
 almost exactly like the builtin `map()` function, except it will execute
-everything in parallel. :
+everything in parallel.
 
 .. code-block:: python
 
@@ -304,7 +304,7 @@ result()
     the scheduled callable returns by default.
 exception()
     Return the exception raised by the call. If no exception was raised then
-    this returns `None`. Note that this will block just like `result()`.
+    this returns None. Note that this will block just like `result()`.
 add_done_callback(fn)
     Attach a callback function that will be executed (as `fn(future)`) when the
     scheduled callable returns.
@@ -357,14 +357,14 @@ futures provided have completed.
 For more information, on using the `concurrent.futures`_ module, consult the
 official documentation.
 
-Threading
+threading
 ---------
 
 The standard library comes with a `threading`_ module that allows a user to
 work with multiple threads manually.
 
 Running a function in another thread is as simple as passing a callable and
-it's arguments to `Thread`'s constructor and then calling `start()`:
+its arguments to `Thread`'s constructor and then calling `start()`:
 
 .. code-block:: python
 
@@ -399,7 +399,7 @@ there might be situations where two or more threads are trying to write to the
 same resource at the same time or where the output is dependent on the sequence
 or timing of certain events. This is called a `data race`_ or race condition.
 When this happens, the output will be garbled or you may encounter problems
-which are difficult to debug. A good example is this `stackoverflow post`_.
+which are difficult to debug. A good example is this `Stack Overflow post`_.
 
 The way this can be avoided is by using a `Lock`_ that each thread needs to
 acquire before writing to a shared resource. Locks can be acquired and released

docs/scenarios/web.rst

@@ -41,7 +41,7 @@ URL Routing
   be invoked
 
 Request and Response Objects
-  Encapsulate the information received from or sent to a user's browser
+  Encapsulates the information received from or sent to a user's browser
 
 Template Engine
   Allows for separating Python code implementing an application's logic from
@@ -105,14 +105,14 @@ It is a reliable, high-performance Python web framework for building large-scale
 app backends and microservices. Falcon encourages the REST architectural style of
 mapping URIs to resources, trying to do as little as possible while remaining highly effective.
 
-Falcon highlights four main focuses: speed, reliability, flexibility and debuggability.
+Falcon highlights four main focuses: speed, reliability, flexibility, and debuggability.
 It implements HTTP through "responders" such as ``on_get()``, ``on_put()``, etc.
 These responders receive intuitive request and response objects.
 
 Tornado
 --------
 
-`Tornado <http://www.tornadoweb.org/>`_ is an asyncronous web framework
+`Tornado <http://www.tornadoweb.org/>`_ is an asynchronous web framework
 for Python that has its own event loop. This allows it to natively support
 WebSockets, for example. Well-written Tornado applications are known to
 have excellent performance characteristics.
@@ -126,7 +126,7 @@ Pyramid
 focus on modularity. It comes with a small number of libraries ("batteries")
 built-in, and encourages users to extend its base functionality. A set of
 provided cookiecutter templates helps making new project decisions for users.
-It poweres one of the most important parts of python infrastucture
+It powers one of the most important parts of python infrastucture
 `PyPI <https://pypi.org/>`_.
 
 Pyramid does not have a large user base, unlike Django and Flask. It's a
@@ -140,7 +140,7 @@ Masonite
 
 The Masonite framework follows the MVC (Model-View-Controller) architecture pattern and is heavily inspired by frameworks such as Rails and Laravel, so if you are coming to Python from a Ruby or PHP background then you will feel right at home!
 
-Masonite comes with a lot of functionality out of the box including a powerful IOC container with auto resolving dependency injection, craft command line tools and the Orator active record style ORM.
+Masonite comes with a lot of functionality out of the box including a powerful IOC container with auto resolving dependency injection, craft command line tools, and the Orator active record style ORM.
 
 Masonite is perfect for beginners or experienced developers alike and works hard to be fast and easy from install through to deployment. Try it once and you’ll fall in love.
 
@@ -155,7 +155,7 @@ Nginx
 -----
 
 `Nginx <http://nginx.org/>`_ (pronounced "engine-x") is a web server and
-reverse-proxy for HTTP, SMTP and other protocols. It is known for its
+reverse-proxy for HTTP, SMTP, and other protocols. It is known for its
 high performance, relative simplicity, and compatibility with many
 application servers (like WSGI servers). It also includes handy features
 like load-balancing, basic authentication, streaming, and others. Designed
@@ -177,9 +177,9 @@ servers and provide top performance [1]_.
 Gunicorn
 --------
 
-`Gunicorn <https://gunicorn.org/>`_ (Green Unicorn) is a pure-python WSGI
+`Gunicorn <https://gunicorn.org/>`_ (Green Unicorn) is a pure-Python WSGI
 server used to serve Python applications. Unlike other Python web servers,
-it has a thoughtful user-interface, and is extremely easy to use and
+it has a thoughtful user interface, and is extremely easy to use and
 configure.
 
 Gunicorn has sane and reasonable defaults for configurations. However, some
@@ -192,7 +192,7 @@ Gunicorn is the recommended choice for new Python web applications today.
 Waitress
 --------
 
-`Waitress <https://waitress.readthedocs.io>`_ is a pure-python WSGI server
+`Waitress <https://waitress.readthedocs.io>`_ is a pure-Python WSGI server
 that claims "very acceptable performance". Its documentation is not very
 detailed, but it does offer some nice functionality that Gunicorn doesn't have
 (e.g. HTTP request buffering).
@@ -207,13 +207,13 @@ uWSGI
 `uWSGI <https://uwsgi-docs.readthedocs.io>`_ is a full stack for building
 hosting services.  In addition to process management, process monitoring,
 and other functionality, uWSGI acts as an application server for various
-programming languages and protocols - including Python and WSGI. uWSGI can
+programming languages and protocols -- including Python and WSGI. uWSGI can
 either be run as a stand-alone web router, or be run behind a full web
 server (such as Nginx or Apache).  In the latter case, a web server can
 configure uWSGI and an application's operation over the
 `uwsgi protocol <https://uwsgi-docs.readthedocs.io/en/latest/Protocol.html>`_.
 uWSGI's web server support allows for dynamically configuring
-Python, passing environment variables and further tuning.  For full details,
+Python, passing environment variables, and further tuning.  For full details,
 see `uWSGI magic
 variables <https://uwsgi-docs.readthedocs.io/en/latest/Vars.html>`_.
 
@@ -275,7 +275,7 @@ Templating
 **********
 
 Most WSGI applications are responding to HTTP requests to serve content in HTML
-or other markup languages. Instead of generating directly textual content from
+or other markup languages. Instead of directly generating textual content from
 Python, the concept of separation of concerns advises us to use templates. A
 template engine manages a suite of template files, with a system of hierarchy
 and inclusion to avoid unnecessary repetition, and is in charge of rendering
@@ -313,10 +313,10 @@ Jinja2
 `Jinja2 <http://jinja.pocoo.org/>`_ is a very well-regarded template engine.
 
 It uses a text-based template language and can thus be used to generate any
-type markup, not just HTML. It allows customization of filters, tags, tests
+type of markup, not just HTML. It allows customization of filters, tags, tests,
 and globals. It features many improvements over Django's templating system.
 
-Here some important html tags in Jinja2:
+Here some important HTML tags in Jinja2:
 
 .. code-block:: html
 
@@ -336,7 +336,7 @@ Here some important html tags in Jinja2:
     {% endfor %}
 
 
-The next listings is an example of a web site in combination with the Tornado
+The next listings are an example of a web site in combination with the Tornado
 web server. Tornado is not very complicated to use.
 
 .. code-block:: python
@@ -434,12 +434,12 @@ engine implementation of the `Template Attribute Language (TAL) <https://en.wiki
 `TAL Expression Syntax (TALES) <https://chameleon.readthedocs.io/en/latest/reference.html#expressions-tales>`_,
 and `Macro Expansion TAL (Metal) <https://chameleon.readthedocs.io/en/latest/reference.html#macros-metal>`_ syntaxes.
 
-Chameleon is available for Python 2.5 and up (including 3.x and pypy), and
+Chameleon is available for Python 2.5 and up (including 3.x and PyPy), and
 is commonly used by the `Pyramid Framework <https://trypyramid.com/>`_.
 
 Page Templates add within your document structure special element attributes
 and text markup. Using a set of simple language constructs, you control the
-document flow, element repetition, text replacement and translation. Because
+document flow, element repetition, text replacement, and translation. Because
 of the attribute-based syntax, unrendered page templates are valid HTML and can
 be viewed in a browser and even edited in WYSIWYG editors. This can make
 round-trip collaboration with designers and prototyping with static files in a
@@ -493,7 +493,7 @@ Mako
 ----
 
 `Mako <http://www.makotemplates.org/>`_ is a template language that compiles to Python
-for maximum performance. Its syntax and api is borrowed from the best parts of other
+for maximum performance. Its syntax and API are borrowed from the best parts of other
 templating languages like Django and Jinja2 templates. It is the default template
 language included with the `Pylons and Pyramid <http://www.pylonsproject.org/>`_ web
 frameworks.

docs/scenarios/xml.rst

@@ -30,13 +30,13 @@ can be loaded like this:
     import untangle
     obj = untangle.parse('path/to/file.xml')
 
-and then you can get the child elements name like this:
+and then you can get the child element's name attribute like this:
 
 .. code-block:: python
 
     obj.root.child['name']
 
-untangle also supports loading XML from a string or an URL.
+untangle also supports loading XML from a string or a URL.
 
 
 *********
@@ -69,7 +69,7 @@ can be loaded into a Python dict like this:
     with open('path/to/file.xml') as fd:
         doc = xmltodict.parse(fd.read())
 
-and then you can access elements, attributes and values like this:
+and then you can access elements, attributes, and values like this:
 
 .. code-block:: python
 
@@ -79,5 +79,5 @@ and then you can access elements, attributes and values like this:
     doc['mydocument']['plus']['#text'] # == u'element as well'
 
 xmltodict also lets you roundtrip back to XML with the unparse function,
-has a streaming mode suitable for handling files that don't fit in memory
+has a streaming mode suitable for handling files that don't fit in memory,
-and supports namespaces.
+and supports XML namespaces.

docs/shipping/freezing.rst

@@ -23,7 +23,7 @@ Besides, end-user software should always be in an executable format. Files
 ending in ``.py`` are for software engineers and system administrators.
 
 One disadvantage of freezing is that it will increase the size of your
-distribution by about 2–12MB. Also, you will be responsible for shipping
+distribution by about 2–12 MB. Also, you will be responsible for shipping
 updated versions of your application when security vulnerabilities to
 Python are patched.
 
@@ -60,12 +60,12 @@ py2app      no      no    yes  yes      MIT     no            yes            yes
 
 .. note::
     Freezing Python code on Linux into a Windows executable was only once
-    supported in PyInstaller `and later dropped.
+    supported in PyInstaller `and later dropped
     <http://stackoverflow.com/questions/2950971/cross-compiling-a-python-script-on-linux-into-a-windows-executable#comment11890276_2951046>`_.
 
 .. note::
-    All solutions need MS Visual C++ dll to be installed on target machine, except py2app.
+    All solutions need a Microsoft Visual C++ to be installed on the target machine, except py2app.
-    Only Pyinstaller makes self-executable exe that bundles the dll when
+    Only PyInstaller makes a self-executable exe that bundles the appropriate DLL when
     passing ``--onefile`` to :file:`Configure.py`.
 
 
@@ -97,7 +97,7 @@ Prerequisite is to install :ref:`Python, Setuptools and pywin32 dependency on Wi
 .. note::
 
     This will work for the most basic one file scripts. For more advanced freezing you will have to provide
-    include and exclude paths like so
+    include and exclude paths like so:
 
     .. code-block:: python
 
@@ -109,8 +109,8 @@ Prerequisite is to install :ref:`Python, Setuptools and pywin32 dependency on Wi
 
     freezer.setIcon('my_awesome_icon.ico')
 
-4. Provide the Microsoft Visual C runtime DLL for the freezer. It might be possible to append your :code:`sys.path`
+4. Provide the Microsoft Visual C++ runtime DLL for the freezer. It might be possible to append your :code:`sys.path`
-with Microsoft Visual Studio path but I find it easier to drop :file:`msvcp90.dll` in the same folder where your script
+with the Microsoft Visual Studio path but I find it easier to drop :file:`msvcp90.dll` in the same folder where your script
 resides.
 
 5. Freeze!
@@ -122,7 +122,7 @@ resides.
 py2exe
 ~~~~~~
 
-Prerequisite is to install :ref:`Python on Windows <install-windows>`. The last release of py2exe is from the year 2014. There is not active development. 
+Prerequisite is to install :ref:`Python on Windows <install-windows>`. The last release of py2exe is from the year 2014. There is not active development.
 
 1. Download and install http://sourceforge.net/projects/py2exe/files/py2exe/
 
@@ -147,7 +147,7 @@ Prerequisite is to install :ref:`Python on Windows <install-windows>`. The last
 
    $ python setup.py py2exe
 
-6. Provide the Microsoft Visual C runtime DLL. Two options: `globally install dll on target machine <https://www.microsoft.com/en-us/download/details.aspx?id=29>`_ or `distribute dll alongside with .exe <http://www.py2exe.org/index.cgi/Tutorial#Step52>`_.
+6. Provide the Microsoft Visual C++ runtime DLL. Two options: `globally install dll on target machine <https://www.microsoft.com/en-us/download/details.aspx?id=29>`_ or `distribute dll alongside with .exe <http://www.py2exe.org/index.cgi/Tutorial#Step52>`_.
 
 PyInstaller
 ~~~~~~~~~~~
@@ -183,19 +183,19 @@ To create a standard Unix executable, from say :code:`script.py`, use:
 
  $ pyinstaller script.py
 
-This creates,
+This creates:
 
 - a :code:`script.spec` file, analogous to a :code:`make` file
 - a :code:`build` folder, that holds some log files
-- a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries,
+- a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries
 
 all in the same folder as :code:`script.py`. PyInstaller puts all the Python libraries used in :code:`script.py` into the :code:`dist` folder, so when distributing the executable, distribute the whole :code:`dist` folder.
 
-The :code:`script.spec` file can be edited to `customise the build <http://pythonhosted.org/PyInstaller/#spec-file-operation>`_, with options such as
+The :code:`script.spec` file can be edited to `customise the build <http://pythonhosted.org/PyInstaller/#spec-file-operation>`_, with options such as:
 
 - bundling data files with the executable
 - including run-time libraries (:code:`.dll` or :code:`.so` files) that PyInstaller can't infer automatically
-- adding Python run-time options to the executable,
+- adding Python run-time options to the executable
 
 Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :code:`script.py` again):
 
@@ -203,7 +203,7 @@ Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :c
 
   $ pyinstaller script.spec
 
-To create a standalone windowed OS X application, use the :code:`--windowed` option
+To create a standalone windowed OS X application, use the :code:`--windowed` option:
 
 .. code-block:: console
 

docs/shipping/packaging.rst

@@ -7,7 +7,7 @@ Packaging Your Code
 
 .. image:: /_static/photos/36137234682_be6898bf57_k_d.jpg
 
-Package your code to share it with other developers. For example
+Package your code to share it with other developers. For example,
 to share a library for other developers to use in their application,
 or for development tools like 'py.test'.
 
@@ -18,7 +18,7 @@ large, professional systems.
 
 It is a well-established convention for Python code to be shared this way.
 If your code isn't packaged on PyPI, then it will be harder
-for other developers to find it, and to use it as part of their existing
+for other developers to find it and to use it as part of their existing
 process. They will regard such projects with substantial suspicion of being
 either badly managed or abandoned.
 
@@ -57,14 +57,14 @@ Pip vs. easy_install
 --------------------
 
 Use `pip <http://pypi.python.org/pypi/pip>`_.  More details
-`here <http://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install>`_
+`here <http://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install>`_.
 
 
 Personal PyPI
 -------------
 
-If you want to install packages from a source other than 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
+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.
 
@@ -85,9 +85,9 @@ Go to your command prompt and type:
    $ cd archive
    $ python -m SimpleHTTPServer 9000
 
-This runs a simple http server running on port 9000 and will list all packages
+This runs a simple HTTP server running on port 9000 and will list all packages
 (like **MyPackage**). Now you can install **MyPackage** using any Python
-package installer. Using Pip, you would do it like:
+package installer. Using pip, you would do it like:
 
 .. code-block:: console
 
@@ -95,7 +95,7 @@ package installer. Using Pip, you would do it like:
 
 Having a folder with the same name as the package name is **crucial** here.
 I got fooled by that, one time. But if you feel that creating a folder called
-:file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that, is
+:file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that is
 *redundant*, you can still install MyPackage using:
 
 .. code-block:: console
@@ -105,7 +105,7 @@ I got fooled by that, one time. But if you feel that creating a folder called
 pypiserver
 ++++++++++
 
-`Pypiserver <https://pypi.python.org/pypi/pypiserver>`_ is a minimal PyPI
+`pypiserver <https://pypi.python.org/pypi/pypiserver>`_ is a minimal PyPI
 compatible server.  It can be used to serve a set of packages to easy_install
 or pip.  It includes helpful features like an administrative command
 (``-U``) which will update all its packages to their latest versions
@@ -115,7 +115,7 @@ found on PyPI.
 S3-Hosted PyPi
 ++++++++++++++
 
-One simple option for a personal PyPi server is to use Amazon S3. A
+One simple option for a personal PyPI server is to use Amazon S3. A
 prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
 
 1. **Install all your requirements from PyPi or another source**
@@ -130,8 +130,8 @@ prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
 
 4. **Upload the new files**
 
-* Use a client like Cyberduck to sync the entire :file:`packages` folder to your s3 bucket
+* Use a client like Cyberduck to sync the entire :file:`packages` folder to your s3 bucket.
-* Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories
+* Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories.
 
 5. **Fix new file permissions**
 
@@ -141,7 +141,7 @@ prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
 
 6. **All done**
 
-* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage`
+* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage`.
 
 .. _packaging-for-linux-distributions-ref:
 
@@ -154,7 +154,7 @@ Creating a Linux distro package is arguably the "right way" to distribute code
 on Linux.
 
 Because a distribution package doesn't include the Python interpreter, it
-makes the download and install about 2MB smaller than
+makes the download and install about 2-12 MB smaller than
 :ref:`freezing your application <freezing-your-code-ref>`.
 
 Also, if a distribution releases a new security update for Python, then your
@@ -165,7 +165,7 @@ for use by distributions like Red Hat or SuSE trivially easy.
 
 However, creating and maintaining the different configurations required for
 each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red
-Hat/Fedora, etc) is a fair amount of work. If your code is an application that
+Hat/Fedora, etc.) is a fair amount of work. If your code is an application that
 you plan to distribute on other platforms, then you'll also have to create and
 maintain the separate config required to freeze your application for Windows
 and OS X. It would be much less work to simply create and maintain a single