From cb94c3af229b9283fac221720ad76f408efa6924 Mon Sep 17 00:00:00 2001
From: Ben McGinnes
Date: Mon, 14 Apr 2014 11:24:05 +1000
Subject: [PATCH 001/836] 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 3ca7ebce5d115bd8a8e104cff79948bff73d9f92 Mon Sep 17 00:00:00 2001
From: Razzi
Date: Fri, 18 Apr 2014 23:26:25 -0400
Subject: [PATCH 002/836] 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 003/836] 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 004/836] 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 005/836] 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 006/836] 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 007/836] 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 008/836] 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 009/836] 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 010/836] 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 011/836] 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 012/836] 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 013/836] 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 014/836] 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 015/836] 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 016/836] 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 017/836] 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 018/836] 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 019/836] 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 020/836] 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 021/836] 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 022/836] 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 023/836] 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 024/836] 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 025/836] 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 026/836] 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 027/836] 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 028/836] 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 029/836] 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 030/836] 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 031/836] 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 032/836] 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 033/836] 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 034/836] 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 035/836] 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 036/836] 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 037/836] 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 038/836] 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 039/836] 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 040/836] 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 041/836] 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 042/836] 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}
+ |
+
+
+
+