Merge pull request realpython#952 from apjanke/typos

Typo and grammar fixes

Author: mpoulin

docs/contents.rst.inc

@@ -33,7 +33,7 @@ New to Python? Let's properly setup up your Python environment:
 Python Development Environments
 -------------------------------
 
-This part of the guide focus on the Python development environment,
+This part of the guide focuses on the Python development environment,
 and the best-practice tools that are available for writing Python code.
 
 .. toctree::
@@ -110,7 +110,7 @@ Additional Notes
 ----------------
 
 This part of the guide, which is mostly prose, begins with some
-background information about Python, then focuses on next steps.
+background information about Python, and then focuses on next steps.
 
 .. toctree::
    :maxdepth: 2
@@ -137,8 +137,3 @@ Contribution notes and legal information (for those interested).
    notes/contribute
    notes/license
    notes/styleguide
-
-
-
-
-

docs/dev/env.rst

@@ -7,7 +7,7 @@ Your Development Environment
 Text Editors
 ::::::::::::
 
-Just about anything that can edit plain text will work for writing Python code,
+Just about anything that can edit plain text will work for writing Python code;
 however, using a more powerful editor may make your life a bit easier.
 
 
@@ -97,7 +97,7 @@ using ``<Tab>`` key or any other customized keys.
 Emacs
 -----
 
-Emacs is another powerful text editor. It is fully programmable (lisp), but
+Emacs is another powerful text editor. It is fully programmable (Lisp), but
 it can be some work to wire up correctly. A good start if you're already an
 Emacs user is `Python Programming in Emacs`_ at EmacsWiki.
 
@@ -117,8 +117,8 @@ Sublime Text
 ------------
 
     `Sublime Text <http://www.sublimetext.com/>`_ is a sophisticated text
-    editor for code, markup and prose. You'll love the slick user interface,
-    extraordinary features and amazing performance.
+    editor for code, markup, and prose. You'll love the slick user interface,
+    extraordinary features, and amazing performance.
 
 Sublime Text has excellent support for editing Python code and uses Python for
 its plugin API. It also has a diverse variety of plugins,
@@ -133,7 +133,7 @@ Atom
     editors.
 
 Atom is web native (HTML, CSS, JS), focusing on modular design and easy plugin
-development. It comes with native package control and plethora of packages.
+development. It comes with native package control and a plethora of packages.
 Recommended for Python development is
 `Linter <https://github.com/AtomLinter/Linter>`_ combined with
 `linter-flake8 <https://github.com/AtomLinter/linter-flake8>`_.
@@ -156,7 +156,7 @@ Python (on Visual Studio Code)
 ------------------------------
 
 `Python for Visual Studio <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`_ is an extension for the `Visual Studio Code IDE <https://code.visualstudio.com>`_.
-This is a free, light weight, open source IDE, with support for Mac, Windows, and Linux.
+This is a free, lightweight, open source IDE, with support for Mac, Windows, and Linux.
 Built using open source technologies such as Node.js and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like.
 
 MIT licensed.
@@ -192,15 +192,15 @@ toward working with scientific Python libraries (namely
 `pylint <http://www.logilab.org/857>`_ and
 `rope <https://github.com/python-rope/rope>`_.
 
-Spyder is open-source (free), offers code completion, syntax highlighting,
+Spyder is open source (free), offers code completion, syntax highlighting,
 a class and function browser, and object inspection.
 
 
 WingIDE
 -------
 
 `WingIDE <http://wingware.com/>`_ is a Python specific IDE. It runs on Linux,
-Windows and Mac (as an X11 application, which frustrates some Mac users).
+Windows, and Mac (as an X11 application, which frustrates some Mac users).
 
 WingIDE offers code completion, syntax highlighting, source browser, graphical
 debugger and support for version control systems.
@@ -211,11 +211,11 @@ NINJA-IDE
 
 `NINJA-IDE <http://www.ninja-ide.org/>`_ (from the recursive acronym: "Ninja-IDE
 Is Not Just Another IDE") is a cross-platform IDE, specially designed to build
-Python applications, and runs on Linux/X11, Mac OS X and Windows desktop
+Python applications, and runs on Linux/X11, Mac OS X, and Windows desktop
 operating systems. Installers for these platforms can be downloaded from the
 website.
 
-NINJA-IDE is open-source software (GPLv3 licence) and is developed
+NINJA-IDE is open source software (GPLv3 licence) and is developed
 in Python and Qt. The source files can be downloaded from
 `GitHub <https://github.com/ninja-ide>`_.
 
@@ -224,11 +224,11 @@ Eric (The Eric Python IDE)
 --------------------------
 
 `Eric <http://eric-ide.python-projects.org/>`_ is a full featured Python IDE
-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 project (GPLv3 licence) with more than ten years of
+offering source code 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 project (GPLv3 licence) with more than ten years of
 active development.
 
 
@@ -253,8 +253,8 @@ of the Python interpreter to be installed at the same time.  This solves the
 problem of having different projects requiring different versions of Python.
 For example, it becomes very easy to install Python 2.7 for compatibility in
 one project, whilst still using Python 3.4 as the default interpreter.
-pyenv isn't just limited to the CPython versions - it will also install PyPy,
-anaconda, miniconda, stackless, jython, and ironpython interpreters.
+pyenv isn't just limited to the CPython versions – it will also install PyPy,
+Anaconda, miniconda, stackless, Jython, and IronPython interpreters.
 
 pyenv works by filling a ``shims`` directory with fake versions of the Python
 interpreter (plus other tools like ``pip`` and ``2to3``).  When the system
@@ -276,7 +276,7 @@ IDLE
 ----
 
 :ref:`IDLE <python:idle>` is an integrated development environment that is
-part of Python standard library. It is completely written in Python and uses
+part of the Python standard distribution. It is completely written in Python and uses
 the Tkinter GUI toolkit. Though IDLE is not suited for full-blown development
 using Python, it is quite helpful to try out small Python snippets and
 experiment with different features in Python.
@@ -294,18 +294,18 @@ IPython
 `IPython <http://ipython.org/>`_ provides a rich toolkit to help you make the
 most out of using Python interactively. Its main components are:
 
-* Powerful Python shells (terminal- and Qt-based).
+* Powerful Python shells (terminal- and Qt-based)
 * A web-based notebook with the same core features but support for rich media,
-  text, code, mathematical expressions and inline plots.
-* Support for interactive data visualization and use of GUI toolkits.
-* Flexible, embeddable interpreters to load into your own projects.
-* Tools for high level and interactive parallel computing.
+  text, code, mathematical expressions and inline plots
+* Support for interactive data visualization and use of GUI toolkits
+* Flexible, embeddable interpreters to load into your own projects
+* Tools for high level and interactive parallel computing
 
 .. code-block:: console
 
     $ pip install ipython
 
-To download and install IPython with all it's optional dependencies for the notebook, qtconsole, tests, and other functionalities
+To download and install IPython with all its optional dependencies for the notebook, qtconsole, tests, and other functionalities:
 
 .. code-block:: console
 
@@ -318,14 +318,14 @@ BPython
 Python interpreter for Unix-like operating systems. It has the following
 features:
 
-* In-line syntax highlighting.
-* Readline-like autocomplete with suggestions displayed as you type.
-* Expected parameter list for any Python function.
-* "Rewind" function to pop the last line of code from memory and re-evaluate.
-* Send entered code off to a pastebin.
-* Save entered code to a file.
-* Auto-indentation.
-* Python 3 support.
+* In-line syntax highlighting
+* Readline-like autocomplete with suggestions displayed as you type
+* Expected parameter list for any Python function
+* "Rewind" function to pop the last line of code from memory and re-evaluate
+* Send entered code off to a pastebin
+* Save entered code to a file
+* Auto-indentation
+* Python 3 support
 
 .. code-block:: console
 
@@ -341,12 +341,12 @@ library. It is considered to be an alternative to BPython_. Features include:
 * Syntax highlighting
 * Autocompletion
 * Multiline editing
-* Emacs and VIM Mode
+* Emacs and Vim Modes
 * Embedding REPL inside of your code
-* Syntax Validation
+* Syntax validation
 * Tab pages
 * Support for integrating with IPython_'s shell, by installing IPython
-  ``pip install ipython`` and running ``ptipython``.
+  (``pip install ipython``) and running ``ptipython``.
 
 .. code-block:: console
 

docs/dev/pip-virtualenv.rst

@@ -1,6 +1,6 @@
 .. _pip-virtualenv:
 
-Further Configuration of Pip and Virtualenv
+Further Configuration of pip and Virtualenv
 ===========================================
 
 .. image:: /_static/photos/34018732105_f0e6758859_k_d.jpg

docs/dev/virtualenvs.rst

@@ -212,7 +212,7 @@ Install virtualenv via pip:
 
   $ pip install virtualenv
 
-Test your installation
+Test your installation:
 
 .. code-block:: console
 
@@ -281,7 +281,7 @@ To delete a virtual environment, just delete its folder. (In this case,
 it would be ``rm -rf my_project``.)
 
 After a while, though, you might end up with a lot of virtual environments
-littered across your system, and its possible you'll forget their names or
+littered across your system, and it's possible you'll forget their names or
 where they were placed.
 
 Other Notes
@@ -293,7 +293,7 @@ for keeping the package list clean in case it needs to be accessed later.
 [This is the default behavior for ``virtualenv`` 1.7 and later.]
 
 In order to keep your environment consistent, it's a good idea to "freeze"
-the current state of the environment packages. To do this, run
+the current state of the environment packages. To do this, run:
 
 .. code-block:: console
 
@@ -302,7 +302,7 @@ the current state of the environment packages. To do this, run
 This will create a :file:`requirements.txt` file, which contains a simple
 list of all the packages in the current environment, and their respective
 versions. You can see the list of installed packages without the requirements
-format using "pip list". Later it will be easier for a different developer
+format using ``pip list``. Later it will be easier for a different developer
 (or you, if you need to re-create the environment) to install the same packages
 using the same versions:
 
@@ -343,7 +343,7 @@ To install (make sure **virtualenv** is already installed):
 
   $ pip install virtualenvwrapper-win
 
-In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs
+In Windows, the default path for WORKON_HOME is %USERPROFILE%\\Envs
 
 Basic Usage
 ~~~~~~~~~~~
@@ -363,7 +363,7 @@ This creates the :file:`my_project` folder inside :file:`~/Envs`.
    $ workon my_project
 
 Alternatively, you can make a project, which creates the virtual environment,
-and also a project directory inside ``$WORKON_HOME``, which is ``cd`` -ed into
+and also a project directory inside ``$WORKON_HOME``, which is ``cd``-ed into
 when you ``workon myproject``.
 
 .. code-block:: console

docs/scenarios/ml.rst

@@ -41,7 +41,7 @@ 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.
 

docs/starting/which-python.rst

@@ -88,7 +88,7 @@ written in C. It compiles Python code to intermediate bytecode which is then
 interpreted by a virtual machine. CPython provides the highest
 level of compatibility with Python packages and C extension modules.
 
-If you are writing open-source Python code and want to reach the widest possible
+If you are writing open source Python code and want to reach the widest possible
 audience, targeting CPython is best. To use packages which rely on C extensions
 to function, CPython is your only implementation option.
 

docs/writing/documentation.rst

@@ -25,7 +25,7 @@ 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`
+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
@@ -75,7 +75,7 @@ your source repository so that rebuilding your documentation will
 happen automatically.
 
 When run, Sphinx_ will import your code and using Python's introspection
-features it will extract all function, method and class signatures. It will
+features it will extract all function, method, and class signatures. It will
 also extract the accompanying docstrings, and compile it all into well
 structured and easily readable documentation for your project.
 
@@ -215,7 +215,7 @@ more information about a function, what it does, any exceptions it may raise,
 what it returns, or relevant details about the parameters.
 
 For more detailed documentation of code a popular style is the one used for the
-Numpy project, often called `Numpy style`_ docstrings. While it can take up more
+NumPy project, often called `NumPy style`_ docstrings. While it can take up more
 lines than the previous example, it allows the developer to include a lot
 more information about a method, function, or class. ::
 
@@ -245,8 +245,8 @@ docstrings, making it easy to incorporate NumPy style docstrings into your
 project.
 
 At the end of the day, it doesn't really matter what style is used for writing
-docstrings, their purpose is to serve as documentation for anyone who may need
-to read or make changes to your code. As long as it is correct, understandable
+docstrings; their purpose is to serve as documentation for anyone who may need
+to read or make changes to your code. As long as it is correct, understandable,
 and gets the relevant points across then it has done the job it was designed to
 do.
 

docs/writing/gotchas.rst

@@ -205,7 +205,7 @@ will automatically write a bytecode version of that file to disk, e.g.
 
 These ``.pyc`` files should not be checked into your source code repositories.
 
-Theoretically, this behavior is on by default, for performance reasons.
+Theoretically, this behavior is on by default for performance reasons.
 Without these bytecode files present, Python would re-generate the bytecode
 every time the file is loaded.
 

docs/writing/license.rst

@@ -19,18 +19,18 @@ In general, these licenses tend to fall into one of two categories:
 
 1. licenses that focus more on the user's freedom to do with the
    software as they please (these are the more permissive open
-   source licenses such as the MIT, BSD, & Apache).
+   source licenses such as the MIT, BSD, and Apache)
 
 2. licenses that focus more on making sure that the code itself —
    including any changes made to it and distributed along with it —
    always remains free (these are the less permissive free software
-   licenses such as the GPL and LGPL).
+   licenses such as the GPL and LGPL)
 
 The latter are less permissive in the sense that they don't permit
 someone to add code to the software and distribute it without also
 including the source code for their changes.
 
-To help you choose one for your project, there's a `license chooser <http://choosealicense.com/>`_,
+To help you choose one for your project, there's a `license chooser <http://choosealicense.com/>`_;
 **use it**.
 
 **More Permissive**

docs/writing/logging.rst

@@ -58,7 +58,7 @@ hierarchy of loggers using dot notation, so using ``__name__`` ensures
 no name collisions.
 
 Here is an example of best practice from the `requests source`_ -- place
-this in your ``__init__.py``
+this in your ``__init__.py``:
 
 .. code-block:: python
 
@@ -83,7 +83,7 @@ There are at least three ways to configure a logger:
 - Using an INI-formatted file:
     - **Pro**: possible to update configuration while running using the
       function :func:`logging.config.listen` to listen on a socket.
-    - **Con**: less control (*e.g.* custom subclassed filters or loggers)
+    - **Con**: less control (e.g. custom subclassed filters or loggers)
       than possible when configuring a logger in code.
 - Using a dictionary or a JSON-formatted file:
     - **Pro**: in addition to updating while running, it is possible to load

docs/writing/reading.rst

@@ -25,7 +25,7 @@ reading. Each one of these projects is a paragon of Python coding.
   best intentions in mind.
 
 - `Diamond <https://github.com/python-diamond/Diamond>`_
-  Diamond is a python daemon that collects metrics
+  Diamond is a Python daemon that collects metrics
   and publishes them to Graphite or other backends.
   It is capable of collecting CPU, memory, network, I/O, load, and disk metrics.
   Additionally, it features an API for implementing custom collectors
@@ -36,7 +36,7 @@ reading. Each one of these projects is a paragon of Python coding.
   applications and has become one of the most advanced WSGI utility modules.
   It includes a powerful debugger, full-featured request and response objects,
   HTTP utilities to handle entity tags, cache control headers, HTTP dates,
-  cookie handling, file uploads, a powerful URL routing system and a bunch
+  cookie handling, file uploads, a powerful URL routing system, and a bunch
   of community-contributed addon modules.
 
 - `Requests <https://github.com/kennethreitz/requests>`_
@@ -49,4 +49,4 @@ reading. Each one of these projects is a paragon of Python coding.
 
 .. todo:: Include code examples of exemplary code from each of the projects listed. Explain why it is excellent code. Use complex examples.
 
-.. todo:: Explain techniques to rapidly identify data structures, algorithms and determine what the code is doing.
+.. todo:: Explain techniques to rapidly identify data structures and algorithms and determine what the code is doing.