From d2d13d6dc6dd92b9f197dcac3f2a7f733c10ca08 Mon Sep 17 00:00:00 2001
From: anatoly techtonik
Date: Sat, 29 Mar 2014 09:08:00 +0300
Subject: [PATCH 001/863] gui/camelot: Replace ads with warnings
---
docs/scenarios/gui.rst | 13 ++++---------
1 file changed, 4 insertions(+), 9 deletions(-)
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index 2bde51920..966ee7a15 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -5,16 +5,11 @@ Alphabetical list of GUI Applications.
Camelot
-------
-`Camelot `_ provides components for building
-business applications on top of Python, SQLAlchemy and Qt. It is inspired by
-the Django admin interface.
-
-You can use Camelot to develop both simple and complex business applications
-at warp speed.
+.. note:: If your software does not fully comply with the GPL you will need a commercial license!
-The main resource for information is the website:
-http://www.python-camelot.com
-and the mailinglist https://groups.google.com/forum/#!forum/project-camelot
+`Camelot `_ provides components for building
+applications on top of Python, SQLAlchemy and Qt. It is inspired by the
+Django admin interface.
Cocoa
-----
From e9dbbb05db6e69dc3481464b223e7d7786e5cd1d Mon Sep 17 00:00:00 2001
From: anatoly techtonik
Date: Mon, 31 Mar 2014 17:36:29 +0300
Subject: [PATCH 002/863] Remove ads only
---
docs/scenarios/gui.rst | 14 ++++++++------
1 file changed, 8 insertions(+), 6 deletions(-)
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index 966ee7a15..f69dcb69b 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -5,12 +5,14 @@ Alphabetical list of GUI Applications.
Camelot
-------
-.. note:: If your software does not fully comply with the GPL you will need a commercial license!
-
-`Camelot `_ provides components for building
-applications on top of Python, SQLAlchemy and Qt. It is inspired by the
-Django admin interface.
-
+`Camelot `_ provides components for building
+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 mailinglist https://groups.google.com/forum/#!forum/project-camelot
+
Cocoa
-----
.. note:: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!
From 03a6d1e9e77f8be21f65d461cd95ac130d1d607d Mon Sep 17 00:00:00 2001
From: anatoly techtonik
Date: Mon, 31 Mar 2014 17:38:05 +0300
Subject: [PATCH 003/863] Missing whitespace
---
docs/scenarios/gui.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index f69dcb69b..db578b93e 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -12,7 +12,7 @@ the Django admin interface.
The main resource for information is the website:
http://www.python-camelot.com
and the mailinglist https://groups.google.com/forum/#!forum/project-camelot
-
+
Cocoa
-----
.. note:: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!
From b7f0d20511dd83dcb476edd622c6761ed91f8f45 Mon Sep 17 00:00:00 2001
From: Zearin
Date: Fri, 11 Apr 2014 14:32:40 -0400
Subject: [PATCH 004/863] =?UTF-8?q?scenarios/ci:=20Github=20=E2=96=B6?=
=?UTF-8?q?=EF=B8=8E=20GitHub?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/scenarios/ci.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst
index 7138893ec..19039deb7 100644
--- a/docs/scenarios/ci.rst
+++ b/docs/scenarios/ci.rst
@@ -55,9 +55,9 @@ Travis-CI
---------
`Travis-CI `_ is a distributed CI server which builds 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
+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 and easy way to get started with
+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 this
@@ -83,5 +83,5 @@ notifications, before and after steps and much more. The
thorough.
In order to activate testing for your project, go to `the travis-ci site `_
-and login with your Github account. Then activate your project in your profile settings and that's
-it. From now on, your project's tests will be run on every push to Github.
+and login with your GitHub account. Then activate your project in your profile settings and that's
+it. From now on, your project's tests will be run on every push to GitHub.
From 3a2850bc346e161f89a257c6383ebd7a85306ca0 Mon Sep 17 00:00:00 2001
From: Zearin
Date: Fri, 11 Apr 2014 14:35:30 -0400
Subject: [PATCH 005/863] =?UTF-8?q?Lets=20=E2=96=B6=EF=B8=8E=20Let's=20(wh?=
=?UTF-8?q?ere=20appropriate)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/scenarios/scrape.rst | 4 ++--
docs/scenarios/speed.rst | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst
index cb2764b0b..69c6e349f 100644
--- a/docs/scenarios/scrape.rst
+++ b/docs/scenarios/scrape.rst
@@ -24,7 +24,7 @@ module instead of the already built-in urlib2 due to improvements in speed and
readability. You can easily install both using ``pip install lxml`` and
``pip install requests``.
-Lets start with the imports:
+Let's start with the imports:
.. code-block:: python
@@ -71,7 +71,7 @@ Knowing this we can create the correct XPath query and use the lxml
#This will create a list of prices
prices = tree.xpath('//span[@class="item-price"]/text()')
-Lets see what we got exactly:
+Let's see what we got exactly:
.. code-block:: python
diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst
index 96065c200..61cf80b6c 100644
--- a/docs/scenarios/speed.rst
+++ b/docs/scenarios/speed.rst
@@ -153,7 +153,7 @@ in a similar way like in standard C. For example `cdef int n,k,i` in line 3. Th
allows the Cython compiler to generate more efficient C code from the second code. While standard Python code is saved in :file:`*.py` files,
Cython code is saved in :file:`*.pyx` files.
-And what is with the speed? So lets try it!
+And what is with the speed? So let's try it!
.. code-block:: python
From 64d756feb986c68a044c6b21ce93dacb50ca5e02 Mon Sep 17 00:00:00 2001
From: Zearin
Date: Fri, 11 Apr 2014 14:55:19 -0400
Subject: [PATCH 006/863] =?UTF-8?q?OSX=20=E2=96=B6=EF=B8=8E=20OS=C2=A0X?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Also removed “Mac”, as the official name was officially shortened to “OS X” a few releases ago.
---
docs/scenarios/gui.rst | 4 ++--
docs/shipping/freezing.rst | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index 2bde51920..989f67139 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -18,7 +18,7 @@ and the mailinglist https://groups.google.com/forum/#!forum/project-camelot
Cocoa
-----
-.. note:: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!
+.. note:: The Cocoa framework is only available on OS X. Don't pick this if you're writing a cross-platform application!
GTk
---
@@ -45,7 +45,7 @@ The main resource for information is the website: http://kivy.org
PyObjC
~~~~~~
-.. note:: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application.
+.. note:: Only available on OS X. Don't pick this if you're writing a cross-platform application.
PySide
~~~~~~
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index a54ea95b1..6859b739d 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -89,7 +89,7 @@ Prerequisite is to have installed :ref:`Python, Setuptools and pywin32 dependenc
- `Manual `_
-OSX
+OS X
---
From 01ec9563894351806f468920b3eb481e546fd135 Mon Sep 17 00:00:00 2001
From: Ben McGinnes
Date: Mon, 14 Apr 2014 08:40:20 +1000
Subject: [PATCH 007/863] Update conf.py
Updated the copyright year for the ePub output/metadata (epub_copyright).
---
docs/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/conf.py b/docs/conf.py
index 92534d93d..eba809892 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -231,7 +231,7 @@
epub_title = u'pythonguide'
epub_author = u'Kenneth Reitz'
epub_publisher = u'Kenneth Reitz'
-epub_copyright = u'2010, Kenneth Reitz'
+epub_copyright = u'2014, Kenneth Reitz'
# The language of the text. It defaults to the language option
# or en if the language is not set.
From cb94c3af229b9283fac221720ad76f408efa6924 Mon Sep 17 00:00:00 2001
From: Ben McGinnes
Date: Mon, 14 Apr 2014 11:24:05 +1000
Subject: [PATCH 008/863] Added search.html to epub_exclude_files
Added search.html to epub_exclude_files to avoid these errors:
Epubcheck Version 3.0
Validating against EPUB version 2.0
ERROR: pythonguide.epub/search.html(17,57): attribute "id" not allowed here; expected attribute "charset", "defer", "src" or "xml:space"
ERROR: pythonguide.epub/search.html(51,32): element "form" not allowed anywhere; expected the element end-tag, text or element "a", "abbr", "acronym", "address", "applet", "b", "bdo", "big", "blockquote", "br", "cite", "code", "del", "dfn", "div", "dl", "em", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "ol", "p", "pre", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "table", "tt", "ul" or "var" (with xmlns:ns="http://www.w3.org/2000/svg")
ERROR: pythonguide.epub/search.html(54,66): element "form" not allowed anywhere; expected the element end-tag, text or element "a", "abbr", "acronym", "address", "applet", "b", "bdo", "big", "blockquote", "br", "cite", "code", "del", "dfn", "div", "dl", "em", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "ol", "p", "pre", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "table", "tt", "ul" or "var" (with xmlns:ns="http://www.w3.org/2000/svg")
It should be noted that ePub does not use javascript for anything (or any scripting), so all those other pages with the quick search function do bad things to ePub files. I'll send through the rest of the errors in a separate issue.
---
docs/conf.py | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index 92534d93d..b4d183314 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -231,7 +231,7 @@
epub_title = u'pythonguide'
epub_author = u'Kenneth Reitz'
epub_publisher = u'Kenneth Reitz'
-epub_copyright = u'2010, Kenneth Reitz'
+epub_copyright = u'2014, Kenneth Reitz'
# The language of the text. It defaults to the language option
# or en if the language is not set.
@@ -256,7 +256,9 @@
#epub_post_files = []
# A list of files that should not be packed into the epub file.
-#epub_exclude_files = []
+epub_exclude_files = [
+ ('search.html', 'Search'),
+]
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
From 6c6e5f4c848257a493548fd5c68daf7690e046c1 Mon Sep 17 00:00:00 2001
From: Vishal Sodani
Date: Mon, 14 Apr 2014 11:03:58 +0530
Subject: [PATCH 009/863] Add book - Writing Idiomatic Python
---
docs/intro/learning.rst | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 9a1a3b411..790cbf787 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -222,3 +222,10 @@ core language, with descriptions of commonly used modules and toolkits. It cover
Python 3 and 2.6 versions.
`Python Pocket Reference `_
+
+Writing Idiomatic Python 2.7.3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+"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 to write some commonly used piece of code. It is followed by an explanation of why the idiom is important. It also contains two code samples: the "Harmful" way to write it and the "Idiomatic" way
+
+
From d8bc8512d1452dc6137e98ef4b7300710df246a7 Mon Sep 17 00:00:00 2001
From: Vishal Sodani
Date: Mon, 14 Apr 2014 11:08:06 +0530
Subject: [PATCH 010/863] Add book link
---
docs/intro/learning.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 790cbf787..7195c8e02 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -228,4 +228,6 @@ Writing Idiomatic Python 2.7.3
"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 to write some commonly used piece of code. It is followed by an explanation of why the idiom is important. It also contains two code samples: the "Harmful" way to write it and the "Idiomatic" way
+ `Writing Idiomatic Python 2.7.3 `_
+
From de1abb0727dfd40c654b7e41e6280e680af95f67 Mon Sep 17 00:00:00 2001
From: Natan L
Date: Sun, 13 Apr 2014 23:35:24 -0700
Subject: [PATCH 011/863] Fix typo: "Stye" --> "Style"
---
CONTRIBUTING.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 98580a3b8..481f3f63c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,6 +10,6 @@ http://docs.python-guide.org/en/latest/notes/contribute/
Style Guide
-----------
-For all contributions, please follow the `Guide Stye Guide`:
+For all contributions, please follow the `Guide Style Guide`:
-http://docs.python-guide.org/en/latest/notes/styleguide/
\ No newline at end of file
+http://docs.python-guide.org/en/latest/notes/styleguide/
From 4a3375e4db4c6a1a205e1ceadbbcf4e57048eb5e Mon Sep 17 00:00:00 2001
From: Vishal Sodani
Date: Mon, 14 Apr 2014 14:22:23 +0530
Subject: [PATCH 012/863] Wrap text
---
docs/intro/learning.rst | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 7195c8e02..6d66bdf1f 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -226,7 +226,11 @@ Python 3 and 2.6 versions.
Writing Idiomatic Python 2.7.3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"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 to write some commonly used piece of code. It is followed by an explanation of why the idiom is important. It also contains two code samples: the "Harmful" way to write it and the "Idiomatic" way
+"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 to write some commonly used piece of code.
+It is followed by an explanation of why the idiom is important. It also contains two
+code samples: the "Harmful" way to write it and the "Idiomatic" way
`Writing Idiomatic Python 2.7.3 `_
From 841fa9cf87b00250a4b75514819f749572be0d71 Mon Sep 17 00:00:00 2001
From: Tony
Date: Mon, 14 Apr 2014 08:02:32 -0400
Subject: [PATCH 013/863] =?UTF-8?q?freezing.rst:=20Fix=20heading=E2=80=99s?=
=?UTF-8?q?=20hyphen=20length?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/shipping/freezing.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 6859b739d..7b118fe1f 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -90,7 +90,7 @@ Prerequisite is to have installed :ref:`Python, Setuptools and pywin32 dependenc
OS X
----
+----
py2app
From ba34421d661ac5673b43daadf37ac7414048e39b Mon Sep 17 00:00:00 2001
From: Zearin
Date: Fri, 11 Apr 2014 11:32:33 -0400
Subject: [PATCH 014/863] Mark up command line options
---
docs/dev/env.rst | 4 ++--
docs/shipping/freezing.rst | 2 +-
docs/shipping/packaging.rst | 2 +-
3 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index aa63fee4e..e7ed001af 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -38,7 +38,7 @@ the syntax file included in VIM 6.1.
These plugins supply you with a basic environment for developing in Python.
To get the most out of Vim, you should continually check your code for syntax
errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you.
-If your VIM is compiled with `+python` you can also utilize some very handy
+If your VIM is compiled with :option:`+python` you can also utilize some very handy
plugins to do these checks from within the editor.
For PEP8 checking, install the vim-pep8_ plugin, and for pyflakes you can
@@ -241,7 +241,7 @@ case, it would be ``rm -rf venv``.)
Other Notes
^^^^^^^^^^^
-Running ``virtualenv`` with the option ``--no-site-packages`` will not
+Running ``virtualenv`` with the option :option:`--no-site-packages` will not
include the packages that are installed globally. This can be useful
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.]
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index a54ea95b1..d23f7471c 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -38,7 +38,7 @@ cx_Freeze yes yes yes yes PSF no yes yes
.. note::
All solutions need MS Visual C++ dll to be installed on target machine.
Only Pyinstaller makes self-executable exe that bundles the dll when
- passing ``--onefile`` to :file:`Configure.py`.
+ passing :option:`--onefile` to :file:`Configure.py`.
Windows
-------
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index 84ba67c3e..d9c91b319 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -67,7 +67,7 @@ pypiserver
`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
+features like an administrative command (:option:`-U`) which will update all its packages to their
latest versions found on PyPI.
From f2fc5d9c1cb5a2e32086ab23910a0f5e35468502 Mon Sep 17 00:00:00 2001
From: Zearin
Date: Fri, 11 Apr 2014 15:10:03 -0400
Subject: [PATCH 015/863] =?UTF-8?q?Mark=20up=20files=20(=E2=80=A6that=20I?=
=?UTF-8?q?=20missed=20earlier=E2=80=A6)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/_themes/README.rst | 2 +-
docs/dev/env.rst | 2 +-
docs/shipping/freezing.rst | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/_themes/README.rst b/docs/_themes/README.rst
index 2e875d46e..ac398041a 100644
--- a/docs/_themes/README.rst
+++ b/docs/_themes/README.rst
@@ -9,7 +9,7 @@ this guide:
1. put this folder as _themes into your docs folder. Alternatively
you can also use git submodules to check out the contents there.
-2. add this to your conf.py: ::
+2. add this to your :file:`conf.py`: ::
sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index aa63fee4e..eee0bfc04 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -280,7 +280,7 @@ virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
$ pip install virtualenvwrapper
-Put this into your ``~/.bash_profile`` (Linux/Mac) file:
+Put this into your :file:`~/.bash_profile` (Linux/Mac) file:
.. code-block:: console
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index a54ea95b1..46e57f169 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -57,7 +57,7 @@ Prerequisite is to install :ref:`Python on Windows `.
1. Download and install http://sourceforge.net/projects/py2exe/files/py2exe/
-2. Write setup.py (`List of configuration options `_)::
+2. Write :file:`setup.py` (`List of configuration options `_)::
.. code-block:: python
From b15f773f03d26cb7cba762f7a50dd3f9e2aaa81d Mon Sep 17 00:00:00 2001
From: Zearin
Date: Fri, 11 Apr 2014 11:30:35 -0400
Subject: [PATCH 016/863] Mark up environment variables
---
docs/starting/install/osx.rst | 4 ++--
docs/starting/install/win.rst | 6 +++---
2 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
index ea991e6af..b3722b136 100644
--- a/docs/starting/install/osx.rst
+++ b/docs/starting/install/osx.rst
@@ -46,7 +46,7 @@ simply run
The script will explain what changes it will make and prompt you before the
installation begins.
Once you've installed Homebrew, insert the Homebrew directory at the top
-of your ``PATH`` environment variable. You can do this by adding the following
+of your :envvar:`PATH` environment variable. You can do this by adding the following
line at the bottom of your :file:`~/.bashrc` file
.. code-block:: console
@@ -60,7 +60,7 @@ Now, we can install Python 2.7:
$ brew install python
This will take a minute or two. Once that's complete, you'll have to add the
-new Python scripts directory to your ``PATH``
+new Python scripts directory to your :envvar:`PATH`
.. code-block:: console
diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst
index 7f98b0bd9..e8fe0a2a9 100644
--- a/docs/starting/install/win.rst
+++ b/docs/starting/install/win.rst
@@ -17,13 +17,13 @@ e.g. Python version 2.7 will install at :file:`C:\Python27\`, so that you can
have multiple versions of Python on the
same system without conflicts. Of course, only one interpreter can be the
default application for Python file types. It also does not automatically
-modify the ``PATH`` environment variable, so that you always have control over
+modify the :envvar:`PATH` environment variable, so that you always have control over
which copy of Python is run.
Typing the full path name for a Python interpreter each time quickly gets
-tedious, so add the directories for your default Python version to the PATH.
+tedious, so add the directories for your default Python version to the :envvar:`PATH`.
Assuming that your Python installation is in :file:`C:\Python27\`, add this to your
-PATH:
+:envvar:`PATH`:
.. code-block:: console
From 7593abaaee908cdfecb681c51a13bb43506b4b68 Mon Sep 17 00:00:00 2001
From: Vishal Sodani
Date: Mon, 14 Apr 2014 22:08:33 +0530
Subject: [PATCH 017/863] Rename title, add links for 2.7.3 and 3.3
---
docs/intro/learning.rst | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 6d66bdf1f..b7eca0d4f 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -223,7 +223,7 @@ Python 3 and 2.6 versions.
`Python Pocket Reference `_
-Writing Idiomatic Python 2.7.3
+Writing Idiomatic Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"Writing Idiomatic Python", written by Jeff Knupp, contains the most common and
@@ -232,6 +232,8 @@ Each idiom is presented as a recommendation to write some commonly used piece of
It is followed by an explanation of why the idiom is important. It also contains two
code samples: the "Harmful" way to write it and the "Idiomatic" way
- `Writing Idiomatic Python 2.7.3 `_
+ `For Python 2.7.3+ `_
+
+ `For Python 3.3+ `_
From c2e59785e0f54ff26fefa65d5205817b01cd078e Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 12:56:28 -0700
Subject: [PATCH 018/863] Update links to Python documentation.
---
docs/intro/documentation.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst
index cd22c95fa..8f3e17001 100644
--- a/docs/intro/documentation.rst
+++ b/docs/intro/documentation.rst
@@ -6,8 +6,8 @@ Official Documentation
The official Python Language and Library documentation can be found here:
- - `Python 2.x `_
- - `Python 3.x `_
+ - `Python 2.x `_
+ - `Python 3.x `_
Read the Docs
From f99e5c55514ec2c982cabbdd6f54de59f88d9fc3 Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 13:21:54 -0700
Subject: [PATCH 019/863] Expanded on Read the Docs section
---
docs/intro/documentation.rst | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst
index 8f3e17001..ddd2e4582 100644
--- a/docs/intro/documentation.rst
+++ b/docs/intro/documentation.rst
@@ -13,9 +13,10 @@ The official Python Language and Library documentation can be found here:
Read the Docs
-------------
-Read the Docs is a popular community project, providing a single location for
-all documentation of popular and even more exotic Python modules.
+Read the Docs is a popular community project that hosts documentation
+for open source software. It holds documentation for many Python modules,
+both popular and exotic.
- `Read the Docs `_
+ `Read the Docs `_
From 1bb07d41a5df2fd3cc5bb772c5f8b8961123f049 Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 13:23:29 -0700
Subject: [PATCH 020/863] Added pydoc section
---
docs/intro/documentation.rst | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst
index ddd2e4582..bab0a9f75 100644
--- a/docs/intro/documentation.rst
+++ b/docs/intro/documentation.rst
@@ -20,3 +20,21 @@ both popular and exotic.
`Read the Docs `_
+pydoc
+-----
+
+:program:`pydoc` is a utlity 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
+
+ .. code-block:: bash
+
+ $ pydoc time
+
+The above command is essentially equivalent to opening the Python REPL
+and running
+
+ .. code-block:: python
+
+ >>> help(time)
From e7f23a931665f67d407a50b2aeed54a72852fec3 Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 13:28:59 -0700
Subject: [PATCH 021/863] Revised code-block types
---
docs/intro/documentation.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst
index bab0a9f75..dd5053ff7 100644
--- a/docs/intro/documentation.rst
+++ b/docs/intro/documentation.rst
@@ -28,13 +28,13 @@ 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
- .. code-block:: bash
+ .. code-block:: console
$ pydoc time
The above command is essentially equivalent to opening the Python REPL
and running
- .. code-block:: python
+ .. code-block:: pycon
>>> help(time)
From ef998acd2b2deb20e32c7ca2466ad540935c017c Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 13:42:03 -0700
Subject: [PATCH 022/863] Revised semantics in section 'mock'
---
docs/writing/tests.rst | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index e77160cff..9484cdc05 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -251,8 +251,9 @@ the need to change any other code.
mock
----
-``mock`` is a library for testing in Python. As of Python 3.3, it is
-available in the `standard library `_.
For older versions of Python:
From 00ebb59a19470f5a2e9f8631254394b9c2859928 Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 17:01:29 -0700
Subject: [PATCH 023/863] Use :mod: tag for modules
---
docs/writing/tests.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index 9484cdc05..f42d6394d 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -16,7 +16,7 @@ Some general rules of testing:
alone, and also within the test suite, regardless of the order they are called.
The implication of this rule is that each test must be loaded with a fresh
dataset and may have to do some cleanup afterwards. This is usually
- handled by ``setUp()`` and ``tearDown()`` methods.
+ handled by :meth:`setUp()` and :meth:`tearDown()` methods.
- Try hard to make tests that run fast. If one single test needs more than a
few millisecond to run, development will be slowed down or the tests will not
@@ -75,11 +75,11 @@ The Basics
Unittest
--------
-Unittest is the batteries-included test module in the Python standard library.
+:mod:`unittest` is the batteries-included test module in the Python standard library.
Its API will be familiar to anyone who has used any of the JUnit/nUnit/CppUnit
series of tools.
-Creating testcases is accomplished by subclassing a TestCase base class
+Creating testcases is accomplished by subclassing a :class:`TestCase` base class
.. code-block:: python
@@ -100,7 +100,7 @@ As of Python 2.7 unittest also includes its own test discovery mechanisms.
Doctest
-------
-The doctest module searches for pieces of text that look like interactive
+The :mod:`doctest` module searches for pieces of text that look like interactive
Python sessions in docstrings, and then executes those sessions to verify that
they work exactly as shown.
From 1800feb118408ea406e96712b4f9db20023d5813 Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 17:08:22 -0700
Subject: [PATCH 024/863] Wrap lines at 78 char as much as possible.
---
docs/writing/tests.rst | 59 +++++++++++++++++++++---------------------
1 file changed, 30 insertions(+), 29 deletions(-)
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index f42d6394d..d88877cd9 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -13,52 +13,53 @@ Some general rules of testing:
correct.
- Each test unit must be fully independent. Each of them must be able to run
- alone, and also within the test suite, regardless of the order they are called.
- The implication of this rule is that each test must be loaded with a fresh
- dataset and may have to do some cleanup afterwards. This is usually
- handled by :meth:`setUp()` and :meth:`tearDown()` methods.
+ alone, and also within the test suite, regardless of the order they are
+ called. The implication of this rule is that each test must be loaded with
+ a fresh dataset and may have to do some cleanup afterwards. This is
+ usually handled by :meth:`setUp()` and :meth:`tearDown()` methods.
- Try hard to make tests that run fast. If one single test needs more than a
- few millisecond to run, development will be slowed down or the tests will not
- be run as often as desirable. In some cases, tests can't be fast because they
- need a complex data structure to work on, and this data structure must be
- loaded every time the test runs. Keep these heavier tests in a separate test
- suite that is run by some scheduled task, and run all other tests as often
- as needed.
+ few millisecond to run, development will be slowed down or the tests will
+ not be run as often as desirable. In some cases, tests can't be fast because
+ they need a complex data structure to work on, and this data structure must
+ be loaded every time the test runs. Keep these heavier tests in a separate
+ test suite that is run by some scheduled task, and run all other tests as
+ often as needed.
- Learn your tools and learn how to run a single test or a test case. Then,
when developing a function inside a module, run this function's tests very
often, ideally automatically when you save the code.
- Always run the full test suite before a coding session, and run it again
- after. This will give you more confidence that you did not break anything in
- the rest of the code.
+ after. This will give you more confidence that you did not break anything
+ in the rest of the code.
-- It is a good idea to implement a hook that runs all tests before pushing code
- to a shared repository.
+- It is a good idea to implement a hook that runs all tests before pushing
+ code to a shared repository.
-- If you are in the middle of a development session and have to interrupt your work, it
- is a good idea to write a broken unit test about what you want to develop next.
- When coming back to work, you will have a pointer to where you were and get
- back on track faster.
+- If you are in the middle of a development session and have to interrupt
+ your work, it is a good idea to write a broken unit test about what you
+ want to develop next. When coming back to work, you will have a pointer
+ to where you were and get back on track faster.
- The first step when you are debugging your code is to write a new test
pinpointing the bug. While it is not always possible to do, those bug
catching test are among the most valuable pieces of code in your project.
-- Use long and descriptive names for testing functions. The style guide here is
- slightly different than that of running code, where short names are often
- preferred. The reason is testing functions are never called explicitly.
+- Use long and descriptive names for testing functions. The style guide here
+ is slightly different than that of running code, where short names are
+ often preferred. The reason is testing functions are never called explicitly.
``square()`` or even ``sqr()`` is ok in running code, but in testing code you
would have names such as ``test_square_of_number_2()``,
- ``test_square_negative_number()``. These function names are displayed when a
- test fail, and should be as descriptive as possible.
-
-- When something goes wrong or has to be changed, and if your code has a good
- set of tests, you or other maintainers will rely largely on the testing suite
- to fix the problem or modify a given behavior. Therefore the testing code will
- be read as much as or even more than the running code. A unit test whose
- purpose is unclear is not very helpful is this case.
+ ``test_square_negative_number()``. These function names are displayed when
+ a test fails, and should be as descriptive as possible.
+
+- When something goes wrong or has to be changed, and if your code has a
+ good set of tests, you or other maintainers will rely largely on the
+ testing suite to fix the problem or modify a given behavior. Therefore
+ the testing code will be read as much as or even more than the running
+ code. A unit test whose purpose is unclear is not very helpful is this
+ case.
- Another use of the testing code is as an introduction to new developers. When
someone will have to work on the code base, running and reading the related
From 2cff35ef3020a865cc92dcc0a1c9d741d2320dc0 Mon Sep 17 00:00:00 2001
From: kuyan
Date: Mon, 14 Apr 2014 17:32:11 -0700
Subject: [PATCH 025/863] Revise Unittest section description
---
docs/writing/tests.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index d88877cd9..ae99fd155 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -76,11 +76,11 @@ The Basics
Unittest
--------
-:mod:`unittest` is the batteries-included test module in the Python standard library.
-Its API will be familiar to anyone who has used any of the JUnit/nUnit/CppUnit
-series of tools.
+:mod:`unittest` is the batteries-included test module in the Python standard
+library. Its API will be familiar to anyone who has used any of the
+JUnit/nUnit/CppUnit series of tools.
-Creating testcases is accomplished by subclassing a :class:`TestCase` base class
+Creating test cases is accomplished by subclassing :class:`unittest.TestCase`.
.. code-block:: python
From 9a09be9cfa75714c3f0c1dfd932104eedb274631 Mon Sep 17 00:00:00 2001
From: Vishal Sodani
Date: Tue, 15 Apr 2014 08:29:50 +0530
Subject: [PATCH 026/863] Fix format
---
docs/intro/learning.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index b7eca0d4f..959859f94 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -224,7 +224,7 @@ Python 3 and 2.6 versions.
`Python Pocket Reference `_
Writing Idiomatic Python
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
"Writing Idiomatic Python", written by Jeff Knupp, contains the most common and
important Python idioms in a format that maximizes identification and understanding.
From d7e3519fc4ad828f3534864d8d38e9ccbc9aa2bd Mon Sep 17 00:00:00 2001
From: kuyan
Date: Wed, 16 Apr 2014 11:21:39 -0700
Subject: [PATCH 027/863] Update Heroku Python guide link
---
docs/scenarios/web.rst | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index 8a15ae9f1..db6a685e6 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -160,14 +160,14 @@ uWSGI
-----
`uWSGI `_ 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
+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
-either be run as a stand-alone web router, or be run behind a full web
+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. uWSGI's web server support allows for dynamically configuring
+protocol. uWSGI's web server support allows for dynamically configuring
Python, passing environment variables and further tuning. For full details,
see `uWSGI magic
variables `_.
@@ -221,9 +221,9 @@ start to charge you once you "scale" your application to run on more than one
Dyno (abstracted servers) at a time.
Heroku publishes `step-by-step instructions
-`_ on how to set up your first
-application for use in Heroku, and maintains a list of `example applications
-`_.
+`_ on
+how to set up your first application for use in Heroku, and maintains a
+list of `example applications `_.
DotCloud
From 5a8324f60d0d219fca73717bd3f2c6d1a51a2f83 Mon Sep 17 00:00:00 2001
From: kuyan
Date: Wed, 16 Apr 2014 11:28:13 -0700
Subject: [PATCH 028/863] Link rot - python.herokuapp.com no longer exists.
python.herokuapp.com 404s but python.heroku.com redirects to
Python documentation for Heroku.
---
docs/scenarios/web.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index db6a685e6..7962279d4 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -220,10 +220,10 @@ free of charge. Heroku is best described as a horizontal scaling platform. They
start to charge you once you "scale" your application to run on more than one
Dyno (abstracted servers) at a time.
-Heroku publishes `step-by-step instructions
+Heroku maintains `articles `_
+on using Python with Heroku as well as `step-by-step instructions
`_ on
-how to set up your first application for use in Heroku, and maintains a
-list of `example applications `_.
+how to set up your first application.
DotCloud
From 3ca7ebce5d115bd8a8e104cff79948bff73d9f92 Mon Sep 17 00:00:00 2001
From: Razzi
Date: Fri, 18 Apr 2014 23:26:25 -0400
Subject: [PATCH 029/863] update Gondor description
---
docs/scenarios/web.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index 7962279d4..4fcedf070 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -250,8 +250,8 @@ Gondor
~~~~~~
`Gondor `_ is a PaaS specialized for deploying Django
-and Pinax applications. Gondor supports Django versions 1.2 and 1.3 on
-Python version 2.7, and can automatically configure your Django site if you
+and Pinax applications. Gondor recommends Django version 1.6 and supports any WSGI application on
+Python version 2.7. Gondor can automatically configure your Django site if you
use :file:`local_settings.py` for site-specific configuration information.
Gondor has a guide on deploying `Django projects `_.
From dcc45981b1a895c20f834ce72cae5f17eeeda9f0 Mon Sep 17 00:00:00 2001
From: Grant Regimbal
Date: Thu, 24 Apr 2014 13:09:55 -0700
Subject: [PATCH 030/863] Added click a new cli to the cli page
---
docs/scenarios/cli.rst | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index cee4872d0..14663e069 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -11,6 +11,14 @@ filled with very useful tools for developing commandline applications.
It supports features such as; CLI Colors and Indents, Simple and Powerful
Column Printer, Iterator based progress bar and Implicit argument handling.
+Click
+-----
+
+`click `_ is a Python package for creating beautiful
+command line interfaces in a composable way with as little amount of code as
+necessary. It’s the “Command Line Interface Creation Kit”. It’s highly
+configurable but comes with good defaults out of the box.
+
docopt
------
From 480852fdc5454c27329c495cdbaab81438806b2f Mon Sep 17 00:00:00 2001
From: Grant Regimbal
Date: Sat, 26 Apr 2014 08:36:12 -0700
Subject: [PATCH 031/863] removing beautiful could be seen as biased
---
docs/scenarios/cli.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 14663e069..79519c03c 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -14,8 +14,8 @@ Column Printer, Iterator based progress bar and Implicit argument handling.
Click
-----
-`click `_ is a Python package for creating beautiful
-command line interfaces in a composable way with as little amount of code as
+`click `_ is a Python package for creating command
+line interfaces in a composable way with as little amount of code as
necessary. It’s the “Command Line Interface Creation Kit”. It’s highly
configurable but comes with good defaults out of the box.
From b20eb4c10cc0fa2ac2a50b91f3f258a8e9ac101e Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Wed, 30 Apr 2014 18:08:37 -0400
Subject: [PATCH 032/863] Update cli.rst
---
docs/scenarios/cli.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 79519c03c..215358002 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -14,7 +14,7 @@ Column Printer, Iterator based progress bar and Implicit argument handling.
Click
-----
-`click `_ is a Python package for creating command
+`click `_ is an upcoming Python package for creating command
line interfaces in a composable way with as little amount of code as
necessary. It’s the “Command Line Interface Creation Kit”. It’s highly
configurable but comes with good defaults out of the box.
From 68f2baa1fba1d278a5f5b3317f7a148717852f6e Mon Sep 17 00:00:00 2001
From: Grant Regimbal
Date: Thu, 1 May 2014 11:38:57 -0700
Subject: [PATCH 033/863] added ansible description and example
---
docs/scenarios/admin.rst | 41 +++++++++++++++++++++++++++++++++++++---
1 file changed, 38 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
index 85fd5b8f5..0dafa0be7 100644
--- a/docs/scenarios/admin.rst
+++ b/docs/scenarios/admin.rst
@@ -178,11 +178,46 @@ monitoring is `glance `_.
Ansible
-------
+`Ansible `_ is a open source system automation tool. The biggest advantage over Puppet or Chef is it does not require an agent on the client machine. Playbooks are Ansible’s configuration, deployment, and orchestration language and are written in in yaml with jinja2 for templating.
-.. todo:: Write about Ansible
+Ansible supports Python versions 2.6 and 2.7 and can be installed via pip:
- `Ansible Documentation
- `_
+.. code-block:: console
+
+ $ pip install ansible
+
+Ansible requires a inventory file that describes the hosts it has access to. Here is an example of a host and
+playbook that will ping all the hosts in the inventory file:
+
+Here is an example inventory file:
+hosts.yml
+
+.. code-block:: yaml
+
+ [server_name]
+ 127.0.0.1
+
+Here is an example playbook:
+ping.yml
+
+.. code-block:: yaml
+
+ ---
+ - hosts: all
+
+ tasks:
+ - name: ping
+ action: ping
+
+To run the playbook:
+
+.. code-block:: console
+
+ $ ansible-playbook ping.yml -i hosts.yml --ask-pass
+
+That Ansible playbook will ping all of the servers in the hosts.yml file. You can also select groups of servers using Ansible. For more information about Ansible read the docs.
+
+`Ansible Docs `_
Chef
From 8914b06556d2d9be10461de0c2e728838f5095b9 Mon Sep 17 00:00:00 2001
From: Moayad Mardini
Date: Mon, 5 May 2014 18:13:43 -0400
Subject: [PATCH 034/863] Added a note about `SuperTab` in VIM section
---
docs/dev/env.rst | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index 2b0c204bb..1d3068dd6 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -76,6 +76,11 @@ It has:
And more.
+SuperTab
+^^^^^^^^
+SuperTab_ is a small VIM plugin that makes code completion more convenient by
+using ```` key or any other customized keys.
+
.. _indent: http://www.vim.org/scripts/script.php?script_id=974
.. _syntax: http://www.vim.org/scripts/script.php?script_id=790
.. _Pyflakes: http://pypi.python.org/pypi/pyflakes/
@@ -84,8 +89,7 @@ And more.
.. _vim-pep8: https://github.com/nvie/vim-pep8
.. _syntastic: https://github.com/scrooloose/syntastic
.. _Python-mode: https://github.com/klen/python-mode
-
-.. todo:: add supertab notes
+.. _SuperTab: http://www.vim.org/scripts/script.php?script_id=1643
Emacs
-----
From f6735bcad750fd17f3ee3e73261bb7ef563f360c Mon Sep 17 00:00:00 2001
From: Shayne Hodge
Date: Thu, 8 May 2014 12:09:09 -0700
Subject: [PATCH 035/863] Add backticks to inline code
Single backticks were used in places, which doesn't seem to render as code (at least on Firefox). Line 137 has a code statement within ** ** that isn't rendering correctly, but I'm not sure how to fix it.
---
docs/writing/structure.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 358972093..d9d286278 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -134,7 +134,7 @@ compartmentalized**.
Using ``from modu import func`` is a way to pinpoint the function you want to
import and put it in the global namespace. While much less harmful than ``import
*`` because it shows explicitly what is imported in the global namespace, its
-advantage over a simpler `import modu` is only that it will save some typing.
+advantage over a simpler ``import modu`` is only that it will save some typing.
**Very bad**
@@ -181,8 +181,8 @@ different modules in the package are imported in a similar manner as plain
modules, but with a special behavior for the :file:`__init__.py` file, which is used to
gather all package-wide definitions.
-A file :file:`modu.py` in the directory :file:`pack/` is imported with the statement `import
-pack.modu`. This statement will look for an :file:`__init__.py` file in :file:`pack`, execute
+A file :file:`modu.py` in the directory :file:`pack/` is imported with the statement ``import
+pack.modu``. This statement will look for an :file:`__init__.py` file in :file:`pack`, execute
all of its top-level statements. Then it will look for a file :file:`pack/modu.py` and
execute all of its top-level statements. After these operations, any variable,
function, or class defined in :file:`modu.py` is available in the pack.modu namespace.
@@ -197,8 +197,8 @@ Leaving an :file:`__init__.py` file empty is considered normal and even a good p
if the package's modules and sub-packages do not need to share any code.
Lastly, a convenient syntax is available for importing deeply nested packages:
-`import very.deep.module as mod`. This allows you to use `mod` in place of the verbose
-repetition of `very.deep.module`.
+``import very.deep.module as mod``. This allows you to use `mod` in place of the verbose
+repetition of ``very.deep.module``.
Object-oriented programming
---------------------------
From caeb467f5b365033b1cd4b1b72dff969cd7aeefe Mon Sep 17 00:00:00 2001
From: Stephen DiCato
Date: Fri, 9 May 2014 16:35:27 -0400
Subject: [PATCH 036/863] Strip trailing whitespace.
---
docs/scenarios/cli.rst | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 215358002..9f2928abc 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -6,7 +6,7 @@ Command Line Applications
Clint
-----
-`clint `_ is a python module which is
+`clint `_ is a python module which is
filled with very useful tools for developing commandline applications.
It supports features such as; CLI Colors and Indents, Simple and Powerful
Column Printer, Iterator based progress bar and Implicit argument handling.
@@ -15,8 +15,8 @@ Click
-----
`click `_ is an upcoming Python package for creating command
-line interfaces in a composable way with as little amount of code as
-necessary. It’s the “Command Line Interface Creation Kit”. It’s highly
+line interfaces in a composable way with as little amount of code as
+necessary. It’s the “Command Line Interface Creation Kit”. It’s highly
configurable but comes with good defaults out of the box.
docopt
@@ -29,9 +29,9 @@ POSIX-style usage instructions.
Plac
------
-`Plac `_ is a python module that allows developing command line applications. In fact
-plac is a simple wrapper over the python standard library `argparse `_, it hides most of its
-complexity by using a declarative interface: the argument parser is inferred
+`Plac `_ is a python module that allows developing command line applications. In fact
+plac is a simple wrapper over the python standard library `argparse `_, it hides most of its
+complexity by using a declarative interface: the argument parser is inferred
rather than written down by imperatively. It is targetting especially unsophisticated
users, programmers, sys-admins, scientists and in general people writing throw-away
scripts for themselves, choosing the command-line interface because it is quick
@@ -40,7 +40,7 @@ and simple.
Cliff
------
-`Cliff `_ is a framework for building command line programs.
+`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 the main program handles
+is meant to be used to create multi-level commands such as subversion and git, where the main program handles
some basic argument parsing and then invokes a sub-command to do the work.
From 20e5aaba6923c2406ac4f8a16d125408b7d5089a Mon Sep 17 00:00:00 2001
From: Stephen DiCato
Date: Fri, 9 May 2014 16:36:24 -0400
Subject: [PATCH 037/863] Fix a few minor typos.
Standardize on "command line", not "command-line".
---
docs/scenarios/cli.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 9f2928abc..6a11a85af 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -7,7 +7,7 @@ Clint
-----
`clint `_ is a python module which is
-filled with very useful tools for developing commandline applications.
+filled with very useful tools for developing command line applications.
It supports features such as; CLI Colors and Indents, Simple and Powerful
Column Printer, Iterator based progress bar and Implicit argument handling.
@@ -34,7 +34,7 @@ plac is a simple wrapper over the python standard library `argparse
Date: Fri, 9 May 2014 17:47:38 -0400
Subject: [PATCH 038/863] backslashes escaping windows directories
---
docs/starting/install/win.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst
index e8fe0a2a9..469a729f0 100644
--- a/docs/starting/install/win.rst
+++ b/docs/starting/install/win.rst
@@ -13,7 +13,7 @@ double-click the file. The MSI package format allows Windows administrators to
automate installation with their standard tools.
By design, Python installs to a directory with the version number embedded,
-e.g. Python version 2.7 will install at :file:`C:\Python27\`, so that you can
+e.g. Python version 2.7 will install at :file:`C:\\Python27\\`, so that you can
have multiple versions of Python on the
same system without conflicts. Of course, only one interpreter can be the
default application for Python file types. It also does not automatically
@@ -22,7 +22,7 @@ which copy of Python is run.
Typing the full path name for a Python interpreter each time quickly gets
tedious, so add the directories for your default Python version to the :envvar:`PATH`.
-Assuming that your Python installation is in :file:`C:\Python27\`, add this to your
+Assuming that your Python installation is in :file:`C:\\Python27\\`, add this to your
:envvar:`PATH`:
.. code-block:: console
From f82061f7fc62128bac93cc643ead79179ffc96ed Mon Sep 17 00:00:00 2001
From: Shayne Hodge
Date: Fri, 9 May 2014 15:41:52 -0700
Subject: [PATCH 039/863] fix nested markup, literal doesn't work
Inline markup can't be nested, see http://docutils.sourceforge.net/docs/user/rst/quickref.html#inline-markup, last sentence.
---
docs/writing/structure.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 358972093..299fe19f9 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -128,7 +128,7 @@ unwanted effects, e.g. override an existing function with the same name.
It is possible to simulate the more standard behavior by using a special syntax
of the import statement: ``from modu import *``. This is generally considered bad
-practice. **Using ``import *`` makes code harder to read and makes dependencies less
+practice. **Using** ``import *`` **makes code harder to read and makes dependencies less
compartmentalized**.
Using ``from modu import func`` is a way to pinpoint the function you want to
From 68f9051e45fdaeb72daa23c1c39c61469ee754c4 Mon Sep 17 00:00:00 2001
From: Tal Einat
Date: Sat, 10 May 2014 18:26:58 +0300
Subject: [PATCH 040/863] minor grammar fix: "An useful" -> "A useful"
---
docs/starting/install/osx.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
index b3722b136..4d893d080 100644
--- a/docs/starting/install/osx.rst
+++ b/docs/starting/install/osx.rst
@@ -119,7 +119,7 @@ environment. Put your own code within a subdirectory of the environment,
however you wish. When you no longer need a particular environment, simply
copy your code out of it, and then delete the main directory for the environment.
-An useful set of extensions to virtualenv is available in virtualenvwrapper,
+A useful set of extensions to virtualenv is available in virtualenvwrapper,
`RTFD `_ to find out more.
--------------------------------
From 540e444925809108f33ac884592f88ced76be6be Mon Sep 17 00:00:00 2001
From: Stephen DiCato
Date: Mon, 12 May 2014 10:40:25 -0400
Subject: [PATCH 041/863] Rename "command line" to "command-line".
---
docs/scenarios/cli.rst | 20 ++++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 6a11a85af..7c87eb2a8 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -1,46 +1,46 @@
-Command Line Applications
+Command-line Applications
=========================
-.. todo:: Explain "Command Line Applications"
+.. todo:: Explain "Command-line Applications"
Clint
-----
`clint `_ is a python module which is
-filled with very useful tools for developing command line applications.
+filled with very useful tools for developing command-line applications.
It supports features such as; CLI Colors and Indents, Simple and Powerful
Column Printer, Iterator based progress bar and Implicit argument handling.
Click
-----
-`click `_ is an upcoming Python package for creating command
-line interfaces in a composable way with as little amount of code as
-necessary. It’s the “Command Line Interface Creation Kit”. It’s highly
+`click `_ is an upcoming Python package for creating
+command-line interfaces in a composable way with as little amount of code as
+necessary. It’s the “Command-line Interface Creation Kit”. It’s highly
configurable but comes with good defaults out of the box.
docopt
------
`docopt `_ is a lightweight, highly Pythonic package that
-allows creating command line interfaces easily and intuitively, by parsing
+allows creating command-line interfaces easily and intuitively, by parsing
POSIX-style usage instructions.
Plac
------
-`Plac `_ is a python module that allows developing command line applications. In fact
+`Plac `_ is a python module that allows developing command-line applications. In fact
plac is a simple wrapper over the python standard library `argparse `_, it hides most of its
complexity by using a declarative interface: the argument parser is inferred
rather than written down by imperatively. It is targetting especially unsophisticated
users, programmers, sys-admins, scientists and in general people writing throw-away
-scripts for themselves, choosing the command line interface because it is quick
+scripts for themselves, choosing the command-line interface because it is quick
and simple.
Cliff
------
-`Cliff `_ is a framework for building command line programs.
+`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 the main program handles
some basic argument parsing and then invokes a sub-command to do the work.
From 064562cb0a10aa81edaf2a0331d8c33fcb67bf79 Mon Sep 17 00:00:00 2001
From: Thomas Kluyver
Date: Tue, 13 May 2014 12:16:43 -0700
Subject: [PATCH 042/863] Update description of scientific Python distributions
- The business model of Anaconda has changed slightly: now it's a free product with 'add-ons' that cost money.
- Enthought has largely replaced EPD with Canopy.
- I've moved Anaconda before Canopy: this is obviously subjective, but Anaconda includes a lot more for free (Canopy Express excludes many open source packages). Workshops like Software Carpentry now tend to point new users to Anaconda for installation.
---
docs/scenarios/scientific.rst | 26 +++++++++++---------------
1 file changed, 11 insertions(+), 15 deletions(-)
diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst
index e95506517..7ad1b1fcd 100644
--- a/docs/scenarios/scientific.rst
+++ b/docs/scenarios/scientific.rst
@@ -124,24 +124,20 @@ 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. It might be a good idea to check it out if you're on Windows.
-Enthought Python Distribution (EPD)
------------------------------------
-
-Installing NumPy and SciPy can be a daunting task. Which is why the
-`Enthought Python distribution `_ was created. With
-Enthought, scientific python has never been easier (one click to install about
-100 scientific python packages). The Enthought Python Distribution comes in two
-variants: a free version `EPD Free `_
-and a paid version with various `pricing options.
-`_
-
Anaconda
--------
`Continuum Analytics `_ offers the `Anaconda
Python Distribution `_ which
includes all the common scientific python packages and additionally many
-packages related to data analytics and big data. Anaconda comes in two
-flavors, a paid for version and a completely free and open source community
-edition, Anaconda CE, which contains a slightly reduced feature set. Free
-licenses for the paid-for version are available for academics and researchers.
+packages related to data analytics and big data. Anaconda itself is free, and
+Continuum sells a number of proprietary add-ons. Free
+licenses for the add-ons are available for academics and researchers.
+
+Canopy
+------
+
+`Canopy is another scientific Python
+distribution, produced by `Enthought `. A limited
+'Canopy Express' variant is available for free, and Enthought charge for the
+full distribution. Free licenses are available for academics.
From 31be2b258563abf2aaace82f09cc90559d2765b9 Mon Sep 17 00:00:00 2001
From: Hasnain Lakhani
Date: Tue, 13 May 2014 22:18:32 -0700
Subject: [PATCH 043/863] Fix typo in scrape.rst
---
docs/scenarios/scrape.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst
index 69c6e349f..8533919d8 100644
--- a/docs/scenarios/scrape.rst
+++ b/docs/scenarios/scrape.rst
@@ -20,7 +20,7 @@ lxml and Requests
`lxml `_ is a pretty extensive library written for parsing
XML and HTML documents really fast. It even handles messed up tags. We will
also be using the `Requests `_
-module instead of the already built-in urlib2 due to improvements in speed and
+module instead of the already built-in urllib2 module due to improvements in speed and
readability. You can easily install both using ``pip install lxml`` and
``pip install requests``.
From aa76da294dd97bc03a4d68ddd2a21dce679ff234 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Brian=20Dre=CC=81au?=
Date: Sat, 17 May 2014 15:36:50 +0200
Subject: [PATCH 044/863] Fixed minor typos in writing/style
---
docs/writing/style.rst | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 165117f2c..85b601d0a 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -217,12 +217,12 @@ while privatising a public property might be a much harder operation.
Returning values
~~~~~~~~~~~~~~~~
-When a function grows in complexity is not uncommon to use multiple return statements
+When a function grows in complexity it is not uncommon to use multiple return statements
inside the function's body. However, in order to keep a clear intent and a sustainable
readability level, it is preferable to avoid returning meaningful values from many
output points in the body.
-There are two main cases for returning values in a function: The result of the function
+There are two main cases for returning values in a function: the result of the function
return when it has been processed normally, and the error cases that indicate a wrong
input parameter or any other reason for the function to not be able to complete its
computation or task.
@@ -261,7 +261,7 @@ is discussed amply at `c2 `_ and at `St
Idiomatic Python code is often referred to as being *Pythonic*.
-Although there usually is one-- and preferably only one --obvious way to do it;
+Although there usually is one --- and preferably only one --- obvious way to do it;
*the* way to write idiomatic Python code can be non-obvious to Python beginners. So,
good idioms must be consciously acquired.
@@ -503,7 +503,7 @@ Short Ways to Manipulate Lists
`List comprehensions
`_
-provide a powerful, concise way to work with lists. Also, the :py:func:`map`
+provide a powerful, concise way to work with lists. Also, the :py:func:`map` and
:py:func:`filter` functions can perform operations on lists using a different,
more concise syntax.
@@ -524,6 +524,7 @@ more concise syntax.
a = [3, 4, 5]
b = [i for i in a if i > 4]
+ # Or:
b = filter(lambda x: x > 4, a)
**Bad**:
From 5ec720a1329706fa8bdc4b37357b049d58a6f3c6 Mon Sep 17 00:00:00 2001
From: Ben McGinnes
Date: Sun, 18 May 2014 07:22:37 +1000
Subject: [PATCH 045/863] Grammar fixed as indicated in issue #429.
---
docs/writing/reading.rst | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/docs/writing/reading.rst b/docs/writing/reading.rst
index e53b30c87..738d851d0 100644
--- a/docs/writing/reading.rst
+++ b/docs/writing/reading.rst
@@ -8,11 +8,12 @@ one thing that Python programmers do is read code.
One of the secrets of becoming a great Python programmer is to read,
understand, and comprehend excellent code.
-Excellent code typically follows the guidelines outlined in :ref:`code_style`,
-and does its best to express a clear and concise intent to the reader.
+Excellent code typically follows the guidelines outlined in
+:ref:`code_style`, and does its best to express a clear and concise
+intent to the reader.
-Included below is a list of recommended Python projects for reading. Each of
-these projects are paragons of excellent Python code.
+Included below is a list of recommended Python projects for
+reading. Each one of these projects is a paragon of Python coding.
- `Howdoi `_
Howdoi is a code search tool, written in Python.
From e2b2a11ad0530a02794d7d4930df996a28263aa6 Mon Sep 17 00:00:00 2001
From: Cameron Goodale
Date: Thu, 22 May 2014 08:02:17 -0700
Subject: [PATCH 046/863] Remove un-needed export command
Dropped the 'export PATH=/usr/local/share/python:$PATH' command and explanation.
---
docs/starting/install/osx.rst | 7 +------
1 file changed, 1 insertion(+), 6 deletions(-)
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
index 4d893d080..85edc6088 100644
--- a/docs/starting/install/osx.rst
+++ b/docs/starting/install/osx.rst
@@ -59,12 +59,7 @@ Now, we can install Python 2.7:
$ brew install python
-This will take a minute or two. Once that's complete, you'll have to add the
-new Python scripts directory to your :envvar:`PATH`
-
-.. code-block:: console
-
- export PATH=/usr/local/share/python:$PATH
+This will take a minute or two.
Setuptools & Pip
From 7d8610410a338f8a789dbca9a68509a2b395ed2d Mon Sep 17 00:00:00 2001
From: niuzhist
Date: Sun, 25 May 2014 00:21:28 -0700
Subject: [PATCH 047/863] add RabbitMQ description
---
docs/scenarios/client.rst | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst
index 8a4fdde4b..06e986430 100644
--- a/docs/scenarios/client.rst
+++ b/docs/scenarios/client.rst
@@ -45,5 +45,10 @@ library is designed to have a familiar socket-style API.
RabbitMQ
--------
-.. todo:: Write about RabbitMQ
+RabbitMQ is open source message broker software that implements the Advanced Message Queuing Protocol (AMQP).
+The RabbitMQ server is written in the Erlang programming language and is built on the Open Telecom Platform
+framework for clustering and failover. Client libraries to interface with the broker are available
+for all major programming languages.
+- `Website `_
+- `GitHub `_
From 7bf154f5e402f2508708c7d033e9c4db3731d0b8 Mon Sep 17 00:00:00 2001
From: niuzhist
Date: Sun, 25 May 2014 00:26:17 -0700
Subject: [PATCH 048/863] change some content
---
docs/scenarios/client.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst
index 06e986430..b7494b080 100644
--- a/docs/scenarios/client.rst
+++ b/docs/scenarios/client.rst
@@ -45,10 +45,10 @@ library is designed to have a familiar socket-style API.
RabbitMQ
--------
-RabbitMQ is open source message broker software that implements the Advanced Message Queuing Protocol (AMQP).
+RabbitMQ is an open source message broker software that implements the Advanced Message Queuing Protocol (AMQP).
The RabbitMQ server is written in the Erlang programming language and is built on the Open Telecom Platform
framework for clustering and failover. Client libraries to interface with the broker are available
for all major programming languages.
-- `Website `_
-- `GitHub `_
+- `Homepage `_
+- `GitHub Organization `_
From 71187f4274b9047eec57b766efae30cd99856982 Mon Sep 17 00:00:00 2001
From: Simeon Visser
Date: Sun, 25 May 2014 20:58:19 +0200
Subject: [PATCH 049/863] Changed python into Python where needed
---
docs/scenarios/scientific.rst | 2 +-
docs/starting/install/win.rst | 4 ++--
docs/writing/documentation.rst | 4 ++--
docs/writing/license.rst | 2 +-
docs/writing/structure.rst | 6 +++---
docs/writing/style.rst | 2 +-
docs/writing/tests.rst | 2 +-
7 files changed, 11 insertions(+), 11 deletions(-)
diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst
index 7ad1b1fcd..05e751145 100644
--- a/docs/scenarios/scientific.rst
+++ b/docs/scenarios/scientific.rst
@@ -129,7 +129,7 @@ Anaconda
`Continuum Analytics `_ offers the `Anaconda
Python Distribution `_ which
-includes all the common scientific python packages and additionally many
+includes all the common scientific Python packages and additionally many
packages related to data analytics and big data. Anaconda itself is free, and
Continuum sells a number of proprietary add-ons. Free
licenses for the add-ons are available for academics and researchers.
diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst
index 469a729f0..033a213b4 100644
--- a/docs/starting/install/win.rst
+++ b/docs/starting/install/win.rst
@@ -53,7 +53,7 @@ download and install any compliant Python software product with a single
command. It also enables you to add this network installation capability to
your own Python software with very little work.
-To obtain the latest version of Setuptools for Windows, run the python script
+To obtain the latest version of Setuptools for Windows, run the Python script
available here: `ez_setup.py `_
@@ -62,7 +62,7 @@ considered by many to be deprecated, so we will install its replacement:
**pip**. Pip allows for uninstallation of packages, and is actively maintained,
unlike easy_install.
-To install pip, run the python script available here:
+To install pip, run the Python script available here:
`get-pip.py `_
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
index b52fca7c4..125b7e79c 100644
--- a/docs/writing/documentation.rst
+++ b/docs/writing/documentation.rst
@@ -17,7 +17,7 @@ assuming the user knows anything about the project), the url of the
main source for the software, and some basic credit information. This
file is the main entry point for readers of the code.
-An :file:`INSTALL` file is less necessary with python. The installation
+An :file:`INSTALL` file is less necessary with Python. The installation
instructions are often reduced to one command, such as ``pip install
module`` or ``python setup.py install`` and added to the :file:`README`
file.
@@ -56,7 +56,7 @@ of the following components:
Sphinx
~~~~~~
-Sphinx_ is far and away the most popular python documentation
+Sphinx_ is far and away the most popular Python documentation
tool. **Use it.** It converts :ref:`restructuredtext-ref` markup language
into a range of output formats including HTML, LaTeX (for printable
PDF versions), manual pages, and plain text.
diff --git a/docs/writing/license.rst b/docs/writing/license.rst
index 9dd7c86d2..006c045ce 100644
--- a/docs/writing/license.rst
+++ b/docs/writing/license.rst
@@ -31,7 +31,7 @@ To help you choose one for your project, there's a `license chooser `_ of how the
-dot notation should be used in the python docs.
+dot notation should be used in the Python docs.
If you'd like you could name it as :file:`my_spam.py` but even our friend the
underscore should not be seen often in module names.
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 85b601d0a..9ca14896d 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -360,7 +360,7 @@ Take the following code for example:
def lookup_list(l):
return 's' in l
-Even though both functions look identical, because *lookup_dict* is utilizing the fact that dictionaries in python are hashtables, the lookup performance between the two is very different.
+Even though both functions look identical, because *lookup_dict* is utilizing the fact that dictionaries in Python are hashtables, the lookup performance between the two is very different.
Python will have to go through each item in the list to find a matching case, which is time consuming. By analysing the hash of the dictionary, finding keys in the dict can be done very quickly.
For more information see this `StackOverflow `_ page.
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index ae99fd155..34add0d8e 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -242,7 +242,7 @@ to newer versions of the module easier in the future
class MyTest(unittest.TestCase):
...
-This way if you ever switch to a newer python version and no longer need the
+This way if you ever switch to a newer Python version and no longer need the
unittest2 module, you can simply change the import in your test module without
the need to change any other code.
From 7ac101e2e7ecdbcb6075382c9e063ef3c26e581b Mon Sep 17 00:00:00 2001
From: Cameron Goodale
Date: Mon, 26 May 2014 20:47:58 -0700
Subject: [PATCH 050/863] Add link to Python Magic Methods Guide * Resolves
#103
---
docs/intro/learning.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 959859f94..828efd2f6 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -154,6 +154,15 @@ development, version control, and optimization/profiling.
`Expert Python Programming `_
+A Guide to Python's Magic Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is a collection of blog posts by Rafe Kettler which explain 'magic methods'
+in Python. Magic methods are surrounded by double underscores (i.e. __init__) and
+can make classes and objects behave in different and magical ways.
+
+ `A Guide to Python's Magic Methods `_
+
+
For Engineers and Scientists
----------------------------
From 1b867b9c5b368d4a8f1facfbb18dd013f961fdd8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Omer=20Murat=20Y=C4=B1ld=C4=B1r=C4=B1m?=
Date: Tue, 27 May 2014 10:35:59 +0300
Subject: [PATCH 051/863] Update xml.rst
---
docs/scenarios/xml.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst
index 3e01b2fe6..e1f7b7084 100644
--- a/docs/scenarios/xml.rst
+++ b/docs/scenarios/xml.rst
@@ -57,7 +57,7 @@ can be loaded into a Python dict like this:
.. code-block:: python
import xmltodict
- obj = xmltodict.parse('path/to/file.xml')
+ obj = xmltodict.parse(open('path/to/file.xml'))
and then you can access elements, attributes and values like this:
From 49c4f2f1e8f2a332508b07bc158d7b398d0d5e98 Mon Sep 17 00:00:00 2001
From: Ian Cordasco
Date: Tue, 27 May 2014 08:28:20 -0500
Subject: [PATCH 052/863] Actually fix xmltodict usage
---
docs/scenarios/xml.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst
index e1f7b7084..7484413a9 100644
--- a/docs/scenarios/xml.rst
+++ b/docs/scenarios/xml.rst
@@ -57,7 +57,9 @@ can be loaded into a Python dict like this:
.. code-block:: python
import xmltodict
- obj = xmltodict.parse(open('path/to/file.xml'))
+
+ with open('path/to/file.xml') as fd:
+ obj = xmltodict.parse(fd.read())
and then you can access elements, attributes and values like this:
From 6c03f219d64fdc0dc290a3cb7886e52477ed9ffe Mon Sep 17 00:00:00 2001
From: Cameron Goodale
Date: Tue, 27 May 2014 07:04:59 -0700
Subject: [PATCH 053/863] Add new line as requested.
---
docs/intro/learning.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 828efd2f6..31641f7b2 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -156,6 +156,7 @@ development, version control, and optimization/profiling.
A Guide to Python's Magic Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
This is a collection of blog posts by Rafe Kettler which explain 'magic methods'
in Python. Magic methods are surrounded by double underscores (i.e. __init__) and
can make classes and objects behave in different and magical ways.
From 54aa0542dec9d11b81de87aecb867ccbdb3c6d73 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Paulie=20Pe=C3=B1a?=
Date: Wed, 28 May 2014 18:55:18 -0400
Subject: [PATCH 054/863] python is strongly-typed but not statically-typed
---
docs/writing/structure.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 98818cc05..7d3978e61 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -317,7 +317,7 @@ Dynamic typing
Python is said to be dynamically typed, which means that variables
do not have a fixed type. In fact, in Python, variables are very
different from what they are in many other languages, specifically
-strongly-typed languages. Variables are not a segment of the computer's
+statically-typed languages. Variables are not a segment of the computer's
memory where some value is written, they are 'tags' or 'names' pointing
to objects. It is therefore possible for the variable 'a' to be set to
the value 1, then to the value 'a string', then to a function.
From 8b3bd266aabef1e4d311a829357b9b3fc48a2b89 Mon Sep 17 00:00:00 2001
From: SUNNY
Date: Fri, 30 May 2014 13:20:40 +0530
Subject: [PATCH 055/863] Canopy description changed | added missing syntax.
---
docs/scenarios/scientific.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst
index 05e751145..a8dc59e70 100644
--- a/docs/scenarios/scientific.rst
+++ b/docs/scenarios/scientific.rst
@@ -137,7 +137,7 @@ licenses for the add-ons are available for academics and researchers.
Canopy
------
-`Canopy is another scientific Python
-distribution, produced by `Enthought `. A limited
+`Canopy '_ is another scientific Python
+distribution, produced by `Enthought `_. A limited
'Canopy Express' variant is available for free, and Enthought charge for the
full distribution. Free licenses are available for academics.
From 9a978b7f58c1f9aaafe97466904fd1dd8994ebc8 Mon Sep 17 00:00:00 2001
From: niuzhist
Date: Fri, 30 May 2014 08:53:02 -0700
Subject: [PATCH 056/863] change last few python to Python
---
docs/scenarios/cli.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 7c87eb2a8..461dda593 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -6,7 +6,7 @@ Command-line Applications
Clint
-----
-`clint `_ is a python module which is
+`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
Column Printer, Iterator based progress bar and Implicit argument handling.
@@ -29,8 +29,8 @@ POSIX-style usage instructions.
Plac
------
-`Plac `_ is a python module that allows developing command-line applications. In fact
-plac is a simple wrapper over the python standard library `argparse `_, it hides most of its
+`Plac `_ is a Python module that allows developing command-line applications. In fact
+plac is a simple wrapper over the Python standard library `argparse `_, it hides most of its
complexity by using a declarative interface: the argument parser is inferred
rather than written down by imperatively. It is targetting especially unsophisticated
users, programmers, sys-admins, scientists and in general people writing throw-away
From 3ad3421b5037cc8a98a33c44bf2e621538017614 Mon Sep 17 00:00:00 2001
From: niuzhist
Date: Fri, 30 May 2014 11:42:25 -0700
Subject: [PATCH 057/863] add Mule description
---
docs/scenarios/ci.rst | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst
index 19039deb7..4e4a80ece 100644
--- a/docs/scenarios/ci.rst
+++ b/docs/scenarios/ci.rst
@@ -30,10 +30,13 @@ Buildbot
automate the compile/test cycle to validate code changes.
-Mule?
+Mule
-----
-.. todo:: Write about Mule
+`Mule `_ is a lightweight integration platform that enables you to connect anything, anywhere.
+You can use Mule to intelligently manage message routing, data mapping, orchestration, reliability, security, and scalability between nodes.
+Plug other systems and applications into Mule and let it handle all the communication between systems, enabling you to track and monitor everything that happens.
+
Tox
---
From 0ce7c2d03533cb48efe304a279c7dbf546405a00 Mon Sep 17 00:00:00 2001
From: Cea Stapleton
Date: Fri, 6 Jun 2014 11:44:01 -0500
Subject: [PATCH 058/863] Improve Which Python section grammar
---
docs/starting/which-python.rst | 42 ++++++++++++++++------------------
1 file changed, 20 insertions(+), 22 deletions(-)
diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst
index cc79c362f..6d0eda5a7 100644
--- a/docs/starting/which-python.rst
+++ b/docs/starting/which-python.rst
@@ -20,38 +20,37 @@ The Future (Python 3)
`Further Reading `_
-Python 3, on the other hand, differs much more greatly from Python 2, so
-writing code that works both on Python 2 and Python 3 is a very complicated
+The difference between Python 3 and Python 2 is much greater, therefore
+writing code that works in both Python 2 and Python 3 is a very complicated
process.
-It is still possible to `write code that works on Python 2.6, 2.7 and 3.3
-`_. Depending on
-the kind of software you are writing, this might be either tricky or extremely
-hard, and if you're a beginner there are much more important things to worry
-about.
+It is possible to `write code that works on Python 2.6, 2.7 and 3.3
+`_. This
+ranges from tricky to extremely hard depending upon the kind of software
+you are writing; if you're a beginner there are far more important things to
+worry about.
Implementations
~~~~~~~~~~~~~~~
-There are several popular implementations of the Python programming language on
-different back-ends.
+When people speak of *Python* they often mean not just the language but also
+the CPython implementation. *Python* is actually a specification for a language
+that can be implemented in many different ways.
CPython
-------
`CPython `_ is the reference implementation of Python,
written in C. It compiles Python code to intermediate bytecode which is then
-interpreted by a virtual machine. When people speak of *Python* they often mean
-not just the language but also this implementation. It provides the highest
+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
-audience, targeting CPython is your best bet. If you need to use any packages
-that rely on C extensions for their functionality (e.g., numpy) then CPython
-is your only choice.
+audience, targeting CPython is best. To use packages which rely on C extensions
+to function, CPython is your only implementation option.
-Being the reference implementation, all versions of the Python language are
-available as CPython.
+All versions of the Python language are implemented in C because CPython is the
+reference implementation.
PyPy
----
@@ -63,19 +62,18 @@ features a just-in-time compiler and supports multiple back-ends (C, CLI, JVM).
PyPy aims for maximum compatibility with the reference CPython implementation
while improving performance.
-If you are looking to squeeze more performance out of your Python code, it's
+If you are looking to increase performance of your Python code, it's
worth giving PyPy a try. On a suite of benchmarks, it's currently `over 5 times
faster than CPython `_.
-Currently PyPy supports Python 2.7. PyPy3 which targets Python 3 was recently
-available as a beta release. [#pypy_ver]_
+PyPy supports Python 2.7. PyPy3 [#pypy_ver]_, released in beta, targets Python 3.
Jython
------
`Jython `_ is a Python implementation that compiles
-Python code to Java bytecode that is then executed in a JVM. It has the additional
-advantage of being able to import and use any Java class like a Python
+Python code to Java bytecode which is then executed by the JVM (Java Virtual Machine).
+Additionally, it is able to import and use any Java class like a Python
module.
If you need to interface with an existing Java codebase or have other reasons to
@@ -88,7 +86,7 @@ IronPython
`IronPython `_ is an implementation of Python for the .NET
framework. It can use both Python and .NET framework libraries, and can also
-expose Python code to other .NET languages.
+expose Python code to other languages in the .NET framework.
`Python Tools for Visual Studio `_ integrates
IronPython directly into the Visual Studio development environment, making it
From fb41621a56bc5964d5375926be777023e984028f Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 10:31:59 -0600
Subject: [PATCH 059/863] Two easily.
---
Readme.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Readme.rst b/Readme.rst
index 07106e2f0..bf7f1838b 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -26,7 +26,7 @@ Topics include:
- Server configurations & tools for various web frameworks
- Documentation: writing it
- Testing: Jenkins & tox guides
-- How to easily interface ``hg`` from ``git`` easily
+- How to easily interface ``hg`` from ``git``
If you aren't fond of reading reStructuredText, there is an
almost up-to-date `HTML version at docs.python-guide.org
From 951f210d022819403ce5884aeb1abb714cc34ac8 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 11:06:59 -0600
Subject: [PATCH 060/863] Some grammar fixes for writing/structure.
---
docs/writing/structure.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 7d3978e61..72a4798dd 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -99,12 +99,12 @@ which is not the case. There is an
`example `_ of how the
dot notation should be used in the Python docs.
-If you'd like you could name it as :file:`my_spam.py` but even our friend the
-underscore should not be seen often in module names.
+If you'd like you could name your module :file:`my_spam.py`, but even our
+friend the underscore should not be seen often in module names.
-Aside for some naming restrictions, nothing special is required for a Python file
-to be a module, but the import mechanism needs to be understood in order to use
-this concept properly and avoid some issues.
+Aside from some naming restrictions, nothing special is required for a Python
+file to be a module, but you need to understand the import mechanism in order
+to use this concept properly and avoid some issues.
Concretely, the ``import modu`` statement will look for the proper file, which is
:file:`modu.py` in the same directory as the caller if it exists. If it is not
@@ -134,7 +134,7 @@ compartmentalized**.
Using ``from modu import func`` is a way to pinpoint the function you want to
import and put it in the global namespace. While much less harmful than ``import
*`` because it shows explicitly what is imported in the global namespace, its
-advantage over a simpler ``import modu`` is only that it will save some typing.
+only advantage over a simpler ``import modu`` is that it will save a little typing.
**Very bad**
From 404c2581ee125b81fe17258fb126f79fecbfcaf5 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 11:07:49 -0600
Subject: [PATCH 061/863] More grammar and cross reference for #132.
---
docs/writing/structure.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 72a4798dd..8f14b8d3d 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -161,11 +161,11 @@ only advantage over a simpler ``import modu`` is that it will save a little typi
[...]
x = modu.sqrt(4) # sqrt is visibly part of modu's namespace
-As said in the section about style, readability is one of the main features of
-Python. Readability means to avoid useless boilerplate text and clutter,
-therefore some efforts are spent trying to achieve a certain level of brevity.
-But terseness and obscurity are the limits where brevity should stop. Being
-able to tell immediately where a class or function comes from, as in the
+As mentioned in the :ref:`code_style` section, readability is one of the main
+features of Python. Readability means to avoid useless boilerplate text and
+clutter, therefore some efforts are spent trying to achieve a certain level of
+brevity. But terseness and obscurity are the limits where brevity should stop.
+Being able to tell immediately where a class or function comes from, as in the
``modu.func`` idiom, greatly improves code readability and understandability in
all but the simplest single file projects.
From 707628d2af5fc8098502ba6c723353e6ffb4db88 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 11:50:47 -0600
Subject: [PATCH 062/863] More writing/structure changes.
---
docs/writing/structure.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 8f14b8d3d..37764c99b 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -183,13 +183,13 @@ gather all package-wide definitions.
A file :file:`modu.py` in the directory :file:`pack/` is imported with the statement ``import
pack.modu``. This statement will look for an :file:`__init__.py` file in :file:`pack`, execute
-all of its top-level statements. Then it will look for a file :file:`pack/modu.py` and
+all of its top-level statements. Then it will look for a file named :file:`pack/modu.py` and
execute all of its top-level statements. After these operations, any variable,
function, or class defined in :file:`modu.py` is available in the pack.modu namespace.
A commonly seen issue is to add too much code to :file:`__init__.py`
files. When the project complexity grows, there may be sub-packages and
-sub-sub-packages in a deep directory structure, and then, importing a single item
+sub-sub-packages in a deep directory structure. In this case, importing a single item
from a sub-sub-package will require executing all :file:`__init__.py` files met while
traversing the tree.
@@ -207,7 +207,7 @@ Python is sometimes described as an object-oriented programming language. This
can be somewhat misleading and needs to be clarified.
In Python, everything is an object, and can be handled as such. This is what is
-meant when we say that, for example, functions are first-class objects.
+meant when we say, for example, that functions are first-class objects.
Functions, classes, strings, and even types are objects in Python: like any
objects, they have a type, they can be passed as function arguments, they may
have methods and properties. In this understanding, Python is an
@@ -284,7 +284,7 @@ The Python language provides a simple yet powerful syntax called 'decorators'.
A decorator is a function or a class that wraps (or decorates) a function
or a method. The 'decorated' function or method will replace the original
'undecorated' function or method. Because functions are first-class objects
-in Python, it can be done 'manually', but using the @decorator syntax is
+in Python, this can be done 'manually', but using the @decorator syntax is
clearer and thus preferred.
.. code-block:: python
From 2e9ae2152f10862ce479cf14cc477e8b88c2d2b2 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:18:51 -0600
Subject: [PATCH 063/863] Grammar and a couple line wraps for writing/style.
---
docs/writing/style.rst | 46 +++++++++++++++++++++++-------------------
1 file changed, 25 insertions(+), 21 deletions(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 9ca14896d..d1e5ebf28 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -101,7 +101,7 @@ calls to ``send('Hello', 'World')`` and ``point(1, 2)``.
2. **Keyword arguments** are not mandatory and have default values. They are often
used for optional parameters sent to the function. When a function has more than
-two or three positional parameters, its signature will be more difficult to remember
+two or three positional parameters, its signature is more difficult to remember
and using keyword argument with default values is helpful. For instance, a more
complete ``send`` function could be defined as ``send(message, to, cc=None, bcc=None)``.
Here ``cc`` and ``bcc`` are optional, and evaluate to ``None`` when they are not
@@ -176,15 +176,15 @@ possible to do each of the following:
However, all these options have many drawbacks and it is always better to use
the most straightforward way to achieve your goal. The main drawback is that
-readability suffers deeply from them. Many code analysis tools, such as pylint
-or pyflakes, will be unable to parse this "magic" code.
+readability suffers greatly when using these constructs. Many code analysis
+tools, such as pylint or pyflakes, will be unable to parse this "magic" code.
We consider that a Python developer should know about these nearly infinite
-possibilities, because it grows the confidence that no hard-wall will be on the
-way. However, knowing how to use them and particularly when **not** to use
-them is the most important.
+possibilities, because it instills confidence that no impassable problem will
+be on the way. However, knowing how and particularly when **not** to use
+them is very important.
-Like a Kungfu master, a Pythonista knows how to kill with a single finger, and
+Like a kung fu master, a Pythonista knows how to kill with a single finger, and
never to actually do it.
We are all consenting adults
@@ -195,10 +195,10 @@ dangerous. A good example is that any client code can override an object's
properties and methods: there is no "private" keyword in Python. This
philosophy, very different from highly defensive languages like Java, which
give a lot of mechanisms to prevent any misuse, is expressed by the saying: "We
-are consenting adults".
+are all consenting adults".
This doesn't mean that, for example, no properties are considered private, and
-that no proper encapsulation is possible in Python. But, instead of relying on
+that no proper encapsulation is possible in Python. Rather, instead of relying on
concrete walls erected by the developers between their code and other's, the
Python community prefers to rely on a set of conventions indicating that these
elements should not be accessed directly.
@@ -210,8 +210,8 @@ the code is modified is the responsibility of the client code.
Using this convention generously is encouraged: any method or property that is
not intended to be used by client code should be prefixed with an underscore.
-This will guarantee a better separation of duties and easier modifications of
-existing code, and it will always be possible to publicize a private property,
+This will guarantee a better separation of duties and easier modification of
+existing code; it will always be possible to publicize a private property,
while privatising a public property might be a much harder operation.
Returning values
@@ -235,7 +235,7 @@ statement can assume the condition is met to further compute the function's main
Having multiple such return statements is often necessary.
However, when a function has multiple main exit points for its normal course, it becomes
-difficult to debug the returned result, and it may be preferable to keep a single exit
+difficult to debug the returned result, so it may be preferable to keep a single exit
point. This will also help factoring out some code paths, and the multiple exit points
are a probable indication that such a refactoring is needed.
@@ -281,7 +281,7 @@ a tuple of two elements for each item in list:
for index, item in enumerate(some_list):
# do something with index and item
-You can use this to swap variables, as well:
+You can use this to swap variables as well:
.. code-block:: python
@@ -360,9 +360,13 @@ Take the following code for example:
def lookup_list(l):
return 's' in l
-Even though both functions look identical, because *lookup_dict* is utilizing the fact that dictionaries in Python are hashtables, the lookup performance between the two is very different.
-Python will have to go through each item in the list to find a matching case, which is time consuming. By analysing the hash of the dictionary, finding keys in the dict can be done very quickly.
-For more information see this `StackOverflow `_ page.
+Even though both functions look identical, because *lookup_dict* is utilizing
+the fact that dictionaries in Python are hashtables, the lookup performance
+between the two is very different. Python will have to go through each item
+in the list to find a matching case, which is time consuming. By analysing
+the hash of the dictionary, finding keys in the dict can be done very quickly.
+For more information see this `StackOverflow `_
+page.
Zen of Python
-------------
@@ -406,7 +410,7 @@ PEP 8
Conforming your Python code to PEP 8 is generally a good idea and helps make
code more consistent when working on projects with other developers. There
-exists a command-line program, `pep8 `_,
+is a command-line program, `pep8 `_,
that can check your code for conformance. Install it by running the following
command in your Terminal:
@@ -584,19 +588,19 @@ files for you.
print line
The ``with`` statement is better because it will ensure you always close the
-file, even if an exception is raised.
+file, even if an exception is raised inside the ``with`` block.
Line Continuations
~~~~~~~~~~~~~~~~~~
When a logical line of code is longer than the accepted limit, you need to
-split it over multiple physical lines. Python interpreter will join consecutive
+split it over multiple physical lines. The Python interpreter will join consecutive
lines if the last character of the line is a backslash. This is helpful
-sometimes but is preferably avoided, because of its fragility: a white space
+in some cases, but should usually be avoided because of its fragility: a white space
added to the end of the line, after the backslash, will break the code and may
have unexpected results.
-A preferred solution is to use parentheses around your elements. Left with an
+A better solution is to use parentheses around your elements. Left with an
unclosed parenthesis on an end-of-line the Python interpreter will join the
next line until the parentheses are closed. The same behavior holds for curly
and square braces.
From 59eaef2f78e87d4667117bfae0deee600b3d3a65 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:27:44 -0600
Subject: [PATCH 064/863] Added pep-3132 style extended unpacking.
---
docs/writing/style.rst | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 9ca14896d..2814318f7 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -293,6 +293,16 @@ Nested unpacking works too:
a, (b, c) = 1, (2, 3)
+In Python 3, a new method of extended unpacking was introduced by
+:pep:`3132`:
+
+.. code-block:: python
+
+ a, *rest = [1, 2, 3]
+ # a = 1, rest = [2, 3]
+ a, *middle, c = [1, 2, 3, 4]
+ # a = 1, middle = [2, 3], c = 4
+
Create an ignored variable
~~~~~~~~~~~~~~~~~~~~~~~~~~
From c3b3e766f977cfc036a4ff410e6af1db16ed6f6d Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:41:00 -0600
Subject: [PATCH 065/863] Mostly line wraps, and a small grammar fix to
writing/documentation.
---
docs/writing/documentation.rst | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
index 125b7e79c..e5600c7df 100644
--- a/docs/writing/documentation.rst
+++ b/docs/writing/documentation.rst
@@ -8,22 +8,21 @@ both you and others a lot of time.
Project Documentation
---------------------
-A :file:`README` file at the root directory should give general
-information to the users and the maintainers. It should be raw text or
-written in some very easy to read markup, such as
-:ref:`reStructuredText-ref` and Markdown. It should contain a few
-lines explaining the purpose of the project or the library (without
-assuming the user knows anything about the project), the url of the
-main source for the software, and some basic credit information. This
-file is the main entry point for readers of the code.
+A :file:`README` file at the root directory should give general information
+to both users and maintainers of a project. It should be raw text or
+written in some very easy to read markup, such as :ref:`reStructuredText-ref`
+or Markdown. It should contain a few lines explaining the purpose of the
+project or library (without assuming the user knows anything about the
+project), the url of the main source for the software, and some basic credit
+information. This file is the main entry point for readers of the code.
An :file:`INSTALL` file is less necessary with Python. The installation
instructions are often reduced to one command, such as ``pip install
module`` or ``python setup.py install`` and added to the :file:`README`
file.
-A :file:`LICENSE` file should *always* be present and specify the license under which the
-software is made available to the public.
+A :file:`LICENSE` file should *always* be present and specify the license
+under which the software is made available to the public.
A :file:`TODO` file or a ``TODO`` section in :file:`README` should list the
planned development for the code.
@@ -158,7 +157,8 @@ Pycco_
.. _Docco: http://jashkenas.github.com/docco
Ronn_
- Ronn builds unix manuals. It converts human readable textfiles to roff for terminal display, and also to HTML for the web.
+ Ronn builds unix manuals. It converts human readable textfiles to roff
+ for terminal display, and also to HTML for the web.
.. _Ronn: https://github.com/rtomayko/ronn
From e7f0d1fa8f3600dae5666287b1607e6a005b4cf5 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:48:53 -0600
Subject: [PATCH 066/863] Minor fixes for writing/tests.
---
docs/writing/tests.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index 34add0d8e..f4ca54bc7 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -44,7 +44,7 @@ Some general rules of testing:
- The first step when you are debugging your code is to write a new test
pinpointing the bug. While it is not always possible to do, those bug
- catching test are among the most valuable pieces of code in your project.
+ catching tests are among the most valuable pieces of code in your project.
- Use long and descriptive names for testing functions. The style guide here
is slightly different than that of running code, where short names are
@@ -66,8 +66,8 @@ Some general rules of testing:
testing code is often the best they can do. They will or should discover the
hot spots, where most difficulties arise, and the corner cases. If they have
to add some functionality, the first step should be to add a test and, by this
- mean, ensure the new functionality is not already a working path that has not
- been plugged in the interface.
+ means, ensure the new functionality is not already a working path that has not
+ been plugged into the interface.
The Basics
::::::::::
From 93c4d9b49c480b17ca32aa38d9eda68354391d18 Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:56:32 -0600
Subject: [PATCH 067/863] Two minor changes to writing/gotchas.
---
docs/writing/gotchas.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst
index 12e18619e..5ed5669c1 100644
--- a/docs/writing/gotchas.rst
+++ b/docs/writing/gotchas.rst
@@ -79,7 +79,7 @@ signal that no argument was provided (:py:data:`None` is often a good choice).
When the Gotcha Isn't a Gotcha
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Sometimes you specifically can "exploit" (read: use as intended) this behavior
+Sometimes you can specifically "exploit" (read: use as intended) this behavior
to maintain state between calls of a function. This is often done when writing
a caching function.
@@ -126,7 +126,7 @@ What Does Happen
8
8
-Five functions are created, but all of them just multiply ``x`` by 4.
+Five functions are created; instead all of them just multiply ``x`` by 4.
Python's closures are *late binding*.
This means that the values of variables used in closures are looked
From 9079873a51d834468af61b353389ef623fa0025b Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 12:59:22 -0600
Subject: [PATCH 068/863] A single wording change in writing/license.
---
docs/writing/license.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/writing/license.rst b/docs/writing/license.rst
index 006c045ce..4d82b39e4 100644
--- a/docs/writing/license.rst
+++ b/docs/writing/license.rst
@@ -4,8 +4,8 @@ Choosing a License
Your source publication *needs* a license. In the US, if no license is
specified, users have no legal right to download, modify, or
distribute. Furthermore, people can't contribute to your code unless
-you tell them what rules to play by. It's complicated, so here are
-some pointers:
+you tell them what rules to play by. Choosing a license is complicated, so
+here are some pointers:
Open source. There are plenty of `open source licenses
`_ available to choose
From e17fdcdd27dbbb7a254d02602a519fc0974f700a Mon Sep 17 00:00:00 2001
From: george
Date: Tue, 17 Jun 2014 13:11:11 -0600
Subject: [PATCH 069/863] Some grammar and wrapping changes to scenarios/web.
Also fixed a small typo.
---
docs/scenarios/web.rst | 27 ++++++++++++++++-----------
1 file changed, 16 insertions(+), 11 deletions(-)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index 4fcedf070..4d7551edc 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -24,7 +24,7 @@ WSGI is documented in :pep:`3333`.
Frameworks
::::::::::
-Broadly speaking, a web framework consist of a set of libraries and a main
+Broadly speaking, a web framework consists of a set of libraries and a main
handler within which you can build custom code to implement a web application
(i.e. an interactive web site). Most web frameworks include patterns and
utilities to accomplish at least the following:
@@ -280,7 +280,7 @@ and to the templates themselves.
- Template files should be passed only the dynamic
content that is needed for rendering the template. Avoid
- to be tempted to pass additional content "just in case":
+ the temptation to pass additional content "just in case":
it is easier to add some missing variable when needed than to remove
a likely unused variable later.
@@ -288,7 +288,7 @@ and to the templates themselves.
or assignments in the template itself, and many
allow some Python code to be evaluated in the
templates. This convenience can lead to uncontrolled
- increase in complexity, and often harder to find bugs.
+ increase in complexity, and often make it harder to find bugs.
- It is often necessary to mix JavaScript templates with
HTML templates. A sane approach to this design is to isolate
@@ -299,9 +299,12 @@ and to the templates themselves.
Jinja2
------
-`Jinja2 `_ is a template engine which is similar to the Django template system with some extra features. It is a text-based template
-language and thus can be used to generate any markup. It allows customization of filters, tags, tests and globals.
-Unlike the template system implemented in the Django Framework it allows to call functions. The Code is staying under the BSD license.
+`Jinja2 `_ is a template engine which is similar to
+the Django template system with some extra features. It is a text-based
+template language and thus can be used to generate any markup. It allows
+customization of filters, tags, tests and globals, and unlike the template
+system implemented in the Django Framework, also allows calling functions.
+Jinja2 is released under the BSD license.
Here some important html tags in Jinja2:
@@ -324,8 +327,8 @@ Here some important html tags in Jinja2:
-The next listings is an example of a web site in combination with the tornado web server. Tornado is not very complicate
-to use.
+The next listings is an example of a web site in combination with the tornado
+web server. Tornado is not very complicate to use.
.. code-block:: python
@@ -365,7 +368,8 @@ to use.
application.listen(PORT)
tornado.ioloop.IOLoop.instance().start()
-The :file:`base.html` file can be used as base for all site pages which are for example implemented in the content block.
+The :file:`base.html` file can be used as base for all site pages which are
+for example implemented in the content block.
.. code-block:: html
@@ -389,8 +393,9 @@ The :file:`base.html` file can be used as base for all site pages which are for
+ Hello, ${'world'}!
+
+
+
+ ${row.capitalize()} ${col}
+ |
+
+
+
+