From f372dc111d1ddc019808b0849bf7e9888fc38626 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:54:04 -0400 Subject: [PATCH 01/33] notes/styleguide.rst: Fix code-block language `python` is for pure Python, but `pylon` is for Python console sessions --- docs/notes/styleguide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 366c1ae6c..54c0ae0df 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -99,7 +99,7 @@ Python interpreter examples: Label the example:: - .. code-block:: python + .. code-block:: pycon >>> import this From 18710633d6ac33efb4454d2afd69f150d32c6298 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:06:19 -0400 Subject: [PATCH 02/33] starting/pip-virtualenv.rst: Fix code-block languages --- docs/starting/pip-virtualenv.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/starting/pip-virtualenv.rst b/docs/starting/pip-virtualenv.rst index a910ae75f..451d3df88 100644 --- a/docs/starting/pip-virtualenv.rst +++ b/docs/starting/pip-virtualenv.rst @@ -55,14 +55,14 @@ create a new file with the correct name for your operating system. If you already have a configuration file, just add the following line under the ``[global]`` settings to require an active virtual environment: -.. code-block:: console +.. code-block:: ini require-virtualenv = true If you did not have a configuration file, you will need to create a new one and add the following lines to this new file: -.. code-block:: console +.. code-block:: ini [global] require-virtualenv = true @@ -72,7 +72,7 @@ You will of course need to install some packages globally (usually ones that you use across different projects consistenly) and this can be accomplished by adding the following to your ``~/.bashrc`` file: -.. code-block:: console +.. code-block:: shell gpip() { PIP_REQUIRE_VIRTUALENV="" pip "$@" From 1416f99510cfdb211fc7e568de1410dcc66b89f5 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:57:19 -0400 Subject: [PATCH 03/33] Oxford commas are your friend --- docs/scenarios/admin.rst | 2 +- docs/scenarios/gui.rst | 4 ++-- docs/scenarios/network.rst | 2 +- docs/scenarios/xml.rst | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 26dc5e6a4..d24431fa4 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -119,7 +119,7 @@ and start the Apache server: - require: - pkg: apache -State files can be written using YAML, the Jinja2 template system or pure Python. +State files can be written using YAML, the Jinja2 template system, or pure Python. `Salt Documentation `_ diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 2bde51920..5a22a53ef 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -6,7 +6,7 @@ Alphabetical list of GUI Applications. Camelot ------- `Camelot `_ provides components for building -business applications on top of Python, SQLAlchemy and Qt. It is inspired by +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 @@ -36,7 +36,7 @@ interaction design and rapid prototyping, while making your code reusable and deployable. Kivy is written in Python, based on OpenGL and supports different input devices -such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on. +such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products, and so on. Kivy is actively being developed by a community and free to use. It operates on all major platforms (Linux, OSX, Windows, Android). diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst index 56031aa9d..144b5a4e1 100644 --- a/docs/scenarios/network.rst +++ b/docs/scenarios/network.rst @@ -7,7 +7,7 @@ Twisted `Twisted `_ is an event-driven networking engine. It can be used to build applications around many different networking protocols, including http servers and clients, applications using SMTP, POP3, -IMAP or SSH protocols, instant messaging and `much more `_. +IMAP or SSH protocols, instant messaging, and `much more `_. PyZMQ ----- diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index 3e01b2fe6..de0b564c4 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -59,7 +59,7 @@ can be loaded into a Python dict like this: import xmltodict obj = xmltodict.parse('path/to/file.xml') -and then you can access elements, attributes and values like this: +and then you can access elements, attributes, and values, like this: .. code-block:: python From d8f1a0674e661a95fa97b16f5745463dc4f4f207 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:59:49 -0400 Subject: [PATCH 04/33] =?UTF-8?q?=E2=80=9CLet=E2=80=99s=E2=80=9D=20use=20c?= =?UTF-8?q?orrect=20punctuation=20:)?= 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 bee6769df..8451f3a62 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 `*.py` files, Cython code is saved in `*.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 5dc3982b23fc548e66b99df22968ed0c2131488f Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:07:56 -0400 Subject: [PATCH 05/33] writing/license.rst: Avoid ampersands in body text --- docs/writing/license.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/license.rst b/docs/writing/license.rst index 9dd7c86d2..526a8ef10 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -15,7 +15,7 @@ In general, these licenses tend to fall into one of two categories: 1. licenses that focus more on the user's freedom to do with the software as they please (these are the more permissive open - source licenses such as the MIT, BSD, & Apache). + source licenses such as the MIT, BSD, and Apache). 2. licenses that focus more on making sure that the code itself — including any changes made to it and distributed along with it — From d1f03c9b494c5eb05343831ed8a9598b8ae938d5 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:09:11 -0400 Subject: [PATCH 06/33] Capitalize Python (where appropriate) --- docs/writing/license.rst | 2 +- docs/writing/structure.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/writing/license.rst b/docs/writing/license.rst index 526a8ef10..a50023f22 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 `my_spam.py` but even our friend the underscore should not be seen often in module names. From 66c9825c40145101a8b2a9c948194817792a236b Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:05:01 -0400 Subject: [PATCH 07/33] scenarios/*.rst: Whitespace --- docs/scenarios/network.rst | 23 +++++++++++++++-------- docs/scenarios/speed.rst | 12 +++++++----- docs/scenarios/web.rst | 21 ++++++++++----------- 3 files changed, 32 insertions(+), 24 deletions(-) diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst index 144b5a4e1..86a22e5fe 100644 --- a/docs/scenarios/network.rst +++ b/docs/scenarios/network.rst @@ -14,14 +14,21 @@ PyZMQ `PyZMQ `_ is the Python binding for `ZeroMQ `_, which is a high-performance asynchronous messaging library. One great advantage is that ZeroMQ -can be used for message queuing without a message broker. The basic patterns for this are: - -- request-reply: connects a set of clients to a set of services. This is a remote procedure call - and task distribution pattern. -- publish-subscribe: connects a set of publishers to a set of subscribers. This is a data - distribution pattern. -- push-pull (or pipeline): connects nodes in a fan-out / fan-in pattern that can have multiple - steps, and loops. This is a parallel task distribution and collection pattern. +can be used for message queuing without a message broker. + +The basic patterns for this are: + +request-reply + connects a set of clients to a set of services. This is a remote procedure call + and task distribution pattern. + +publish-subscribe + connects a set of publishers to a set of subscribers. + This is a data distribution pattern. + +push-pull (or pipeline) + connects nodes in a fan-out / fan-in pattern that can have multiple steps, and loops. + This is a parallel task distribution and collection pattern. For a quick start, read the `ZeroMQ guide `_. diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 8451f3a62..6bf71ab58 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -1,8 +1,8 @@ Speed ===== -CPython, the most commonly used implementation of Python, is slow for CPU bound -tasks. `PyPy`_ is fast. +:program:`CPython`, the most commonly used implementation of Python, is +slow for CPU bound tasks. `PyPy`_ is fast. Using a slightly modified version of `David Beazleys`_ CPU bound test code (added loop for multiple tests), you can see the difference between CPython @@ -100,7 +100,8 @@ Here's an example of strong typing with Cython: return result -This implementation of an algorithm to find prime numbers has some additional keywords instead of the next one, which is implemented in pure Python: +This implementation of an algorithm to find prime numbers has some additional +keywords instead of the next one, which is implemented in pure Python: .. code-block:: python @@ -125,8 +126,8 @@ This implementation of an algorithm to find prime numbers has some additional ke n = n + 1 return result -Notice that in the Cython version you declare integers and integer arrays for -to be compiled into C types while also creating a Python list: +Notice that, in the Cython version, you declare integers and integer arrays +to be compiled into C types, while also creating a Python list: .. code-block:: cython @@ -202,6 +203,7 @@ On a standard notebook (dual core AMD E-450 1.6 GHz), the measured values are: And here the output of an embedded `ARM beaglebone `_ machine: + .. code-block:: console Cython time: 0.0196 seconds diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 2d2ab5171..114e89680 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -30,19 +30,19 @@ handler within which you can build custom code to implement a web application utilities to accomplish at least the following: URL Routing - Matches an incoming HTTP request to a particular piece of Python code to - be invoked + Matches an incoming HTTP request to a particular piece of Python code to + be invoked Request and Response Objects - Encapsulate the information received from or sent to a user's browser + Encapsulate the information received from or sent to a user's browser Template Engine - Allows for separating Python code implementing an application's logic from - the HTML (or other) output that it produces + Allows for separating Python code implementing an application's logic from + the HTML (or other) output that it produces Development Web Server - Runs an HTTP server on development machines to enable rapid development; - often automatically reloads server-side code when files are updated + Runs an HTTP server on development machines to enable rapid development; + often automatically reloads server-side code when files are updated Django @@ -270,8 +270,7 @@ avoid unnecessary repetition, and is in charge of rendering of the templates with the dynamic content generated by the application. -As template files are -sometimes written by designers or front-end developers, +As template files are sometimes written by designers or front-end developers, it can be difficult to handle increasing complexity. Some general good practices apply to the part of the @@ -324,8 +323,8 @@ Here some important html tags in Jinja2: -The next listings is an example of a web site in combination with the tornado web server. Tornado is not very complicate -to use. +The next listings is an example of a web site in combination with the tornado web server. +Tornado is not very complicated to use. .. code-block:: python From d53ebd7df2c0957124ab605693a4fa5e2a4fc003 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:25:20 -0400 Subject: [PATCH 08/33] Add `:file:` markup --- docs/dev/env.rst | 14 +++++++------ docs/dev/virtualenvs.rst | 6 +++--- docs/scenarios/admin.rst | 2 +- docs/scenarios/ci.rst | 6 ++++-- docs/scenarios/speed.rst | 23 ++++++++++++-------- docs/scenarios/web.rst | 8 +++---- docs/shipping/freezing.rst | 2 +- docs/shipping/packaging.rst | 4 ++-- docs/starting/install/osx.rst | 2 +- docs/starting/install/win.rst | 12 +++++------ docs/starting/pip-virtualenv.rst | 28 ++++++++++++------------- docs/writing/documentation.rst | 12 +++++------ docs/writing/structure.rst | 36 ++++++++++++++++---------------- 13 files changed, 82 insertions(+), 73 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 3610307aa..d0636f970 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -16,8 +16,10 @@ Vim is a text editor which uses keyboard shortcuts for editing instead of menus or icons. There exist a couple of plugins and settings for the VIM editor to aid Python development. If you only develop in Python, a good start is to set the default settings for indentation and line-wrapping to values compliant with -:pep:`8`. In your home directory, open a file called ``.vimrc`` and add the -following lines:: +:pep:`8`. In your home directory, open a file called :file:`.vimrc` and add the +following lines: + +.. code-block:: set textwidth=79 " lines longer than 79 columns will be broken set shiftwidth=4 " operation >> indents 4 columns; << unindents 4 columns @@ -46,7 +48,7 @@ install vim-pyflakes_. Now you can map the functions ``Pep8()`` or ``Pyflakes()` to any hotkey or action you want in Vim. Both plugins will display errors at the bottom of the screen, and provide an easy way to jump to the corresponding line. It's very handy to call these functions whenever you save a file. In -order to do this, add the following lines to your ``.vimrc``:: +order to do this, add the following lines to your :file:`.vimrc`: autocmd BufWritePost *.py call Pyflakes() autocmd BufWritePost *.py call Pep8() @@ -253,7 +255,7 @@ the current state of the environment packages. To do this, run $ pip freeze > requirements.txt -This will create a ``requirements.txt`` file, which contains a simple +This will create a :file:`requirements.txt` file, which contains a simple list of all the packages in the current environment, and their respective versions. Later, when a different developer (or you, if you need to re- create the environment) can install the same packages, with the same @@ -280,13 +282,13 @@ 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 $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages' -This will prevent your virtualenvs from relying on your (global) site packages +This will prevent your virtualenvs from relying on your (global) :file:`site-packages` directory, so that they are completely separate.. [note: This is the default behavior for ``virtualenv`` 1.7 and later] diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index cf2b285b9..34e6c8b3f 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -30,7 +30,7 @@ Basic Usage $ virtualenv venv This creates a copy of Python in whichever directory you ran the command in, -placing it in a folder named ``venv``. +placing it in a folder named :file:`venv`. 2. To begin using the virtual environment, it needs to be activated: @@ -94,7 +94,7 @@ Basic Usage $ mkvirtualenv venv -This creates the ``venv`` folder inside ``~/Envs``. +This creates the :file:`venv` folder inside :file:`~/Envs`. 2. Work on a virtual environment: @@ -140,7 +140,7 @@ Other useful commands autoenv ------- -When you ``cd`` into a directory containing a ``.env``, `autoenv `_ +When you :command:`cd` into a directory containing :file:`.env`, `autoenv `_ automagically activates the environment. Install it on Mac OS X using ``brew``: diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index d24431fa4..1d98bc02b 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -38,7 +38,7 @@ server. run('git pull') run('touch app.wsgi') -With the previous code saved in a file named fabfile.py, we can check memory +With the previous code saved in a file named :file:`fabfile.py`, we can check memory usage with: .. code-block:: console diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 962c6c866..63376d08a 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -60,8 +60,10 @@ Requests whether this particular changeset breaks the build or not. So if you ar 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 ``.travis.yml`` file to your repository with this -example content:: +In order to get started, add a :file:`.travis.yml` file to your repository with this +example content. + +.. code-block:: yaml language: python python: diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 6bf71ab58..736eb884d 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -149,10 +149,11 @@ to be compiled into C types, while also creating a Python list: p= range(1000) result = [] -What is the difference? In the upper Cython version you can see the declaration of the variable types and the integer array -in a similar way like in standard C. For example `cdef int n,k,i` in line 3. This additional type declaration (e.g. integer) -allows the Cython compiler to generate more efficient C code from the second code. While standard Python code is saved in `*.py` files, -Cython code is saved in `*.pyx` files. +What is the difference? In the upper Cython version you can see the declaration of the variable types +and the integer array in a similar way like in standard C. For example ``cdef int n,k,i`` in line 3. +This additional type declaration (e.g. integer) 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 let's try it! @@ -188,11 +189,15 @@ These both lines need a remark: pyximport.install() -The `pyximport` module allows you to import `pyx` files (e.g., `primesCy.pyx`) with the Cython-compiled version of the `primes` function. -The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code, -which is automatically compiled to a `*.so` C-library. Cython is able to import this library for you in your Python-code. -Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers. -On a standard notebook (dual core AMD E-450 1.6 GHz), the measured values are: +The :module:`pyximport` module allows you to import :file:`*.pyx` files (e.g., +:file:`primesCy.pyx`) with the Cython-compiled version of the +:py:func:`primes` function. The :py:func:`pyximport.install()` command allows +the Python interpreter to start the Cython compiler directly to generate +C-code, which is automatically compiled to a :file:`*.so` C-library. Cython is +able to import this library for you in your Python-code. Very easy and very +efficient. With the :py:func:`time.time()` function you are able to compare +the time between this 2 different calls to find 500 prime numbers. On a +standard notebook (dual core AMD E-450 1.6 GHz), the measured values are: .. code-block:: console diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 114e89680..d60f80dd6 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -252,7 +252,7 @@ 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 -use ``local_settings.py`` for site-specific configuration information. +use :file:`local_settings.py` for site-specific configuration information. Gondor has a guide on deploying `Django projects `_. @@ -364,7 +364,7 @@ Tornado is not very complicated to use. application.listen(PORT) tornado.ioloop.IOLoop.instance().start() -The `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 @@ -388,8 +388,8 @@ The `base.html` file can be used as base for all site pages which are for exampl -The next listing is our site page (`site.html`) loaded in the Python app which extends `base.html`. The content block is -automatically set into the corresponding block in the base.html page. +The next listing is our site page (:file:`site.html`) loaded in the Python app which extends :file:`base.html`. +The content block is automatically set into the corresponding block in the :file:`base.html` page. .. code-block:: html diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index d114d741d..7fd199f74 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 diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index d2757f049..c31459448 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -30,7 +30,7 @@ running from the directory which holds those packages which need to be installed **Showing an example is always beneficial** -Say if you are after installing a package called MyPackage.tar.gz, and +Say if you are after installing a package called :file:`MyPackage.tar.gz`, and assuming this is your directory structure: @@ -55,8 +55,8 @@ package installer. Using Pip, you would do it like: Having a folder with the same name as the package name is **crucial** here. I got fooled by that, one time. But if you feel that creating a folder called -**MyPackage** and keeping **MyPackage.tar.gz** inside that, is *redundant*, you can still install MyPackage using: +:file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that, is *redundant*, .. code-block:: console diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index cdd8b3259..ea991e6af 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -47,7 +47,7 @@ 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 -line at the bottom of your ``~/.bashrc`` file +line at the bottom of your :file:`~/.bashrc` file .. code-block:: console diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index d84084f77..a7bae8491 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 ``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,8 +22,8 @@ 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. -Assuming that your Python installation is in ``C:\Python27\``, add this to your PATH: +Assuming that your Python installation is in :file:`C:\Python27\`, add this to your .. code-block:: console @@ -35,7 +35,7 @@ You can do this easily by running the following in ``powershell``: [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27\;C:\Python27\Scripts\", "User") -The second (``Scripts``) directory receives command files when certain +The second directory (:file:`Scripts`) receives command files when certain packages are installed, so it is a very useful addition. You do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries @@ -92,14 +92,14 @@ project's directory > virtualenv venv -To use an environment, run the ``activate.bat`` batch file in the ``Scripts`` +To use an environment, run the :file:`activate.bat` batch file in the :file:`Scripts` subdirectory of that environment. Your command prompt will change to show the active environment. Once you have finished working in the current virtual -environment, run the ``deactivate.bat`` batch file to restore your settings to +environment, run the :file:`deactivate.bat` batch file to restore your settings to normal. Each new environment automatically includes a copy of ``pip`` in the -``Scripts`` subdirectory, so that you can setup the third-party libraries and +:file:`Scripts` subdirectory, so that you can setup the third-party libraries and tools that you want to use in that 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 diff --git a/docs/starting/pip-virtualenv.rst b/docs/starting/pip-virtualenv.rst index 451d3df88..3f432a673 100644 --- a/docs/starting/pip-virtualenv.rst +++ b/docs/starting/pip-virtualenv.rst @@ -18,13 +18,13 @@ project. Over time this can result in a messy global package list. In order to make sure that you install packages to your active virtual environment when you use ``pip install``, consider adding the following two lines to your -``~/.bashrc`` file: +:file:`~/.bashrc` file: .. code-block:: console export PIP_REQUIRE_VIRTUALENV=true -After saving this change and sourcing the ``~/.bashrc`` file with ``source ~/.bashrc``, +After saving this change and sourcing the :file:`~/.bashrc` file with ``source ~/.bashrc``, pip will no longer let you install packages if you are not in a virtual environment. If you try to use ``pip install`` outside of a virtual environment pip will gently remind you that an activated virtual environment is needed to install packages. @@ -34,22 +34,22 @@ remind you that an activated virtual environment is needed to install packages. $ pip install requests Could not find an activated virtualenv (required). -You can also do this configuration by editing your ``pip.conf`` or ``pip.ini`` -file. ``pip.conf`` is used by Unix and Mac OS X operating systems and it can be +You can also do this configuration by editing your :file:`pip.conf` or :file:`pip.ini` +file. :file:`pip.conf` is used by Unix and Mac OS X operating systems and it can be found at: .. code-block:: console $HOME/.pip/pip.conf -Similarly, the ``pip.ini`` file is used by Windows operating systems and it can +Similarly, the :file:`pip.ini` file is used by Windows operating systems and it can be found at: .. code-block:: console %HOME%\pip\pip.ini -If you don't have a ``pip.conf`` or ``pip.ini`` file at these locations, you can +If you don't have a :file:`pip.conf` or :file:`pip.ini` file at these locations, you can create a new file with the correct name for your operating system. If you already have a configuration file, just add the following line under the @@ -70,7 +70,7 @@ add the following lines to this new file: You will of course need to install some packages globally (usually ones that you use across different projects consistenly) and this can be accomplished by adding -the following to your ``~/.bashrc`` file: +the following to your :file:`~/.bashrc` file: .. code-block:: shell @@ -78,7 +78,7 @@ the following to your ``~/.bashrc`` file: PIP_REQUIRE_VIRTUALENV="" pip "$@" } -After saving the changes and sourcing your ``~/.bashrc`` file you can now install +After saving the changes and sourcing your :file:`~/.bashrc` file you can now install packages globally by running ``gpip install``. You can change the name of the function to anything you like, just keep in mind that you will have to use that name when trying to install packages globally with pip. @@ -96,7 +96,7 @@ start working on a new project (and in a new virtual environmen as a result). Fortunately, you can configure pip in such a way that it tries to reuse already installed packages. -On UNIX systems, you can add the following line to your ``.bashrc`` or ``.bash_profile`` +On UNIX systems, you can add the following line to your :file:`.bashrc` or :file:`.bash_profile` file. .. code-block:: console @@ -104,25 +104,25 @@ file. export PIP_DOWNLOAD_CACHE=$HOME/.pip/cache You can set the path to anywhere you like (as long as you have write -access). After adding this line, ``source`` your ``.bashrc`` (or ``.bash_profile``) +access). After adding this line, :command:`source` your :file:`.bashrc` (or :file:`.bash_profile`) file and you will be all set. -Another way of doing the same configuration is via the ``pip.conf`` or ``pip.ini`` +Another way of doing the same configuration is via the :file:`pip.conf` or :file:`pip.ini` files, depending on your system. If you are on Windows, you can add the following -line to your ``pip.ini`` file under ``[global]`` settings: +line to your :file:`pip.ini` file under ``[global]`` settings: .. code-block:: console download-cache = %HOME%\pip\cache Similarly, on UNIX systems you should simply add the following line to your -``pip.conf`` file under ``[global]`` settings: +:file:`pip.conf` file under ``[global]`` settings: .. code-block:: console download-cache = $HOME/.pip/cache Even though you can use any path you like to store your cache, it is recommended -that you create a new folder *in* the folder where your ``pip.conf`` or ``pip.ini`` +that you create a new folder *in* the folder where your :file:`pip.conf` or :file:`pip.ini` file lives. If you don't trust yourself with all of this path voodoo, just use the values provided here and you will be fine. diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 29de3e40c..c005d1e4e 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -8,7 +8,7 @@ both you and others a lot of time. Project Documentation --------------------- -A ``README`` file at the root directory should give general +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 @@ -17,18 +17,18 @@ 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 ``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 ``README`` +module`` or ``python setup.py install`` and added to the :file:`README` file. -A ``LICENSE`` file should *always* be present and specify the license under which the +A :file:`LICENSE` file should *always* be present and specify the license under which the software is made available to the public. -A ``TODO`` file or a ``TODO`` section in ``README`` should list the +A :file:`TODO` file or a :file:`TODO` section in :file:`README` should list the planned development for the code. -A ``CHANGELOG`` file or section in ``README`` should compile a short +A :file:`CHANGELOG` file or section in :file:`README` should compile a short overview of the changes in the code base for the latest versions. Project Publication diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 2f209f119..114e38ad5 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -34,10 +34,10 @@ to do it poorly. Some signs of a poorly structured project include: - Multiple and messy circular dependencies: if your classes - Table and Chair in furn.py need to import Carpenter from workers.py to answer a question such as ``table.isdoneby()``, and if conversely the class Carpenter needs to import Table and Chair, to answer the question ``carpenter.whatdo()``, then you + :py:class:`Table` and :py:class:`Chair` in :file:`furn.py` need to import :py:class:`Carpenter` from :file:`workers.py` have a circular dependency. In this case you will have to resort to fragile hacks such as using import statements inside methods or functions. @@ -90,16 +90,16 @@ modules such as `os` and `sys`, third-party modules you have installed in your environment, or your project's internal modules. To keep in line with the style guide, keep module names short, lowercase, and -be sure to avoid using special symbols like the dot (.) or question mark (?). -So a file name like `my.spam.py` is one you should avoid! Naming this way -will interfere with the way python looks for modules. +be sure to avoid using special symbols like the dot (``.``) or question mark (``?``). +So a file name like :file:`my.spam.py` is one you should avoid! Naming this way +will interfere with the way Python looks for modules. -In the case of `my.spam.py` python expects to find a "spam.py" file in a folder named "my" -which is not the case. There is an +In the case of :file:`my.spam.py` python expects to find a :file:`spam.py` file in a +folder named :file:`my` 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 `my_spam.py` but even our friend the +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. Aside for some naming restrictions, nothing special is required for a Python file @@ -107,9 +107,9 @@ to be a module, but the import mechanism needs to be understood in order to use this concept properly and avoid some issues. Concretely, the ``import modu`` statement will look for the proper file, which is -`modu.py` in the same directory as the caller if it exists. If it is not -found, the Python interpreter will search for `modu.py` in the "path" recursively and raise an ImportError exception if it is not found. +:file:`modu.py` in the same directory as the caller if it exists. If it is not +found, the Python interpreter will search for :file:`modu.py` in the ``path`` Once `modu.py` is found, the Python interpreter will execute the module in an isolated scope. Any top-level statement in `modu.py` will be executed, @@ -176,24 +176,24 @@ Packages Python provides a very straightforward packaging system, which is simply an extension of the module mechanism to a directory. -Any directory with an __init__.py file is considered a Python package. The +Any directory with an :file:`__init__.py` file is considered a Python package. The different modules in the package are imported in a similar manner as plain -modules, but with a special behavior for the __init__.py file, which is used to +modules, but with a special behavior for the :file:`__init__.py` file, which is used to gather all package-wide definitions. -A file modu.py in the directory pack/ is imported with the statement `import -pack.modu`. This statement will look for an __init__.py file in `pack`, execute -all of its top-level statements. Then it will look for a file `pack/modu.py` and +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 modu.py is available in the pack.modu namespace. +function, or class defined in :file:`modu.py` is available in the :module:`pack.modu` namespace. -A commonly seen issue is to add too much code to __init__.py +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 -from a sub-sub-package will require executing all __init__.py files met while +from a sub-sub-package will require executing all :file:`__init__.py` files met while traversing the tree. -Leaving an __init__.py file empty is considered normal and even a good practice, +Leaving an :file:`__init__.py` file empty is considered normal and even a good practice, 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: From 632118ac45149e4c2d8edd9e3de092360608c973 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:27:31 -0400 Subject: [PATCH 09/33] Add `:envvar:` markup --- docs/starting/install/osx.rst | 4 ++-- docs/starting/install/win.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index ea991e6af..454928812 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 a7bae8491..6acbd017e 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. -PATH: Assuming that your Python installation is in :file:`C:\Python27\`, add this to your +:envvar:`PATH`: .. code-block:: console From 9a4cfe0a0283de1892c9d93914e7f5a452d00d9d Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:39:32 -0400 Subject: [PATCH 10/33] Add `:module:` markup --- docs/intro/learning.rst | 2 +- docs/scenarios/admin.rst | 2 +- docs/scenarios/client.rst | 4 ++-- docs/scenarios/db.rst | 12 +++++------- docs/scenarios/gui.rst | 2 +- docs/scenarios/scrape.rst | 8 ++++---- docs/scenarios/xml.rst | 4 ++-- docs/shipping/packaging.rst | 4 ++-- docs/starting/pip-virtualenv.rst | 2 +- docs/starting/which-python.rst | 2 +- docs/writing/structure.rst | 4 ++-- docs/writing/tests.rst | 20 ++++++++++---------- 12 files changed, 32 insertions(+), 34 deletions(-) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 4b2dd8b5b..2e807765e 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -147,7 +147,7 @@ case-studies), method resolution order, using super() and meta-programming, and general :pep:`8` best practices. It has a detailed, multi-chapter case study on writing and releasing a package -and eventually an application, including a chapter on using zc.buildout. Later +and eventually an application, including a chapter on using :module:`zc.buildout`. Later chapters detail best practices with writing documentation, test-driven development, version control, and optimization/profiling. diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 1d98bc02b..4f3b15ac1 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -86,7 +86,7 @@ Salt supports Python versions 2.6 and 2.7 and can be installed via pip: After configuring a master server and any number of minion hosts, we can run arbitrary shell commands or use pre-built modules of complex commands on our minions. -The following command lists all available minion hosts, using the ping module. +The following command lists all available minion hosts, using the :module:`ping` module. .. code-block:: console diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst index 8a4fdde4b..629afe3b5 100644 --- a/docs/scenarios/client.rst +++ b/docs/scenarios/client.rst @@ -13,7 +13,7 @@ foundation of data communication for the World Wide Web. Requests -------- -Python’s standard urllib2 module provides most of the HTTP capabilities you +Python’s standard :module:`urllib2` module provides most of the HTTP capabilities you need, but the API is thoroughly broken. It was built for a different time — and a different web. It requires an enormous amount of work (even method overrides) to perform the simplest of tasks. @@ -21,7 +21,7 @@ overrides) to perform the simplest of tasks. Requests takes all of the work out of Python HTTP — making your integration with web services seamless. There’s no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection -pooling are 100% automatic, powered by urllib3, which is embedded within +pooling are 100% automatic, powered by :module:`urllib3`, which is embedded within Requests. - `Documentation `_ diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index 252d9d7b1..bceb4f6ec 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -6,8 +6,8 @@ DB-API The Python Database API (DB-API) defines a standard interface for Python database access modules. It's documented in :pep:`249`. -Nearly all Python database modules such as `sqlite3`, `psycopg` and -`mysql-python` conform to this interface. +Nearly all Python database modules (such as :module:`sqlite3`, +:module:`psycopg`, and :module:`mysql-python`) conform to this interface. Tutorials that explain how to work with modules that conform to this interface can be found `here `__ and @@ -30,14 +30,12 @@ Django ORM The Django ORM is the interface used by `Django `_ to provide database access. -It's based on the idea of `models `_, an abstraction that makes it easier to -manipulate data in Python. +It's based on the idea of `models `_, +an abstraction that makes it easier to manipulate data in Python. The basics: -- Each model is a Python class that subclasses django.db.models.Model. +- Each model is a Python class that subclasses :module:`django.db.models.Model`. - Each attribute of the model represents a database field. - Django gives you an automatically-generated database-access API; see `Making queries `__. to provide database access. - - diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 5a22a53ef..86551079e 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -77,7 +77,7 @@ software with a GUI but can also be used for non-GUI applications. Tk -- -Tkinter is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage +:module:`Tkinter` is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage of being included with the Python standard library, making it the most convenient and compatible toolkit to program with.** diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index 69c6e349f..7a2173972 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 :module:`urlib2` due to improvements in speed and readability. You can easily install both using ``pip install lxml`` and ``pip install requests``. @@ -32,7 +32,7 @@ Let's start with the imports: import requests Next we will use ``requests.get`` to retrieve the web page with our data -and parse it using the ``html`` module and save the results in ``tree``: +and parse it using the :module:`html` module and save the results in ``tree``: .. code-block:: python @@ -61,7 +61,7 @@ span with class 'item-price':
Carson Busses
$29.95 -Knowing this we can create the correct XPath query and use the lxml +Knowing this we can create the correct XPath query and use the :module:`lxml` ``xpath`` function like this: .. code-block:: python @@ -92,7 +92,7 @@ Let's see what we got exactly: '$15.00', '$114.07', '$10.09'] Congratulations! We have successfully scraped all the data we wanted from -a web page using lxml and Requests. We have it stored in memory as two +a web page using :module:`lxml` and Requests. We have it stored in memory as two lists. Now we can do all sorts of cool stuff with it: we can analyze it using Python or we can save it to a file and share it with the world. diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index de0b564c4..8a605290a 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -68,6 +68,6 @@ and then you can access elements, attributes, and values, like this: doc['mydocument']['plus']['@a'] # == u'complex' doc['mydocument']['plus']['#text'] # == u'element as well' -xmltodict also lets you roundtrip back to XML with the unparse function, -has a streaming mode suitable for handling files that don't fit in memory +:module:`xmltodict` also lets you roundtrip back to XML with the :py:func:`unparse` function, +has a streaming mode suitable for handling files that don't fit in memory, and supports namespaces. diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index c31459448..24352cac1 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -46,8 +46,8 @@ Go to your command prompt and type: $ python -m SimpleHTTPServer 9000 This runs a simple http server running on port 9000 and will list all packages -(like **MyPackage**). Now you can install **MyPackage** using any Python package installer. Using Pip, you would do it like: +(like :module:`MyPackage`). Now you can install :module:`MyPackage` using any Python .. code-block:: console @@ -55,8 +55,8 @@ package installer. Using Pip, you would do it like: Having a folder with the same name as the package name is **crucial** here. I got fooled by that, one time. But if you feel that creating a folder called -you can still install MyPackage using: :file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that, is *redundant*, +you can still install :module:`MyPackage` using: .. code-block:: console diff --git a/docs/starting/pip-virtualenv.rst b/docs/starting/pip-virtualenv.rst index 3f432a673..0db949493 100644 --- a/docs/starting/pip-virtualenv.rst +++ b/docs/starting/pip-virtualenv.rst @@ -88,7 +88,7 @@ Caching packages for future use Every developer has preferred libraries and when you are working on a lot of different projects, you are bound to have some overlap between the libraries that -you use. For example, you may be using the ``requests`` library in a lot of different +you use. For example, you may be using the :module:`requests` library in a lot of different projects. It is surely unnecessary to re-download the same packages/libraries each time you diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index cc79c362f..66dca2d57 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -47,7 +47,7 @@ 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 +that rely on C extensions for their functionality (e.g., :module:`numpy`) then CPython is your only choice. Being the reference implementation, all versions of the Python language are diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 114e38ad5..a75800d01 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -86,7 +86,7 @@ the interface file needs to import the low-level file. This is done with the ``import`` and ``from ... import`` statements. As soon as you use `import` statements you use modules. These can be either built-in -modules such as `os` and `sys`, third-party modules you have installed in your +modules such as :module:`os` and :module:`sys`, third-party modules you have installed in your environment, or your project's internal modules. To keep in line with the style guide, keep module names short, lowercase, and @@ -198,7 +198,7 @@ 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`. +repetition of :module:`very.deep.module`. Object-oriented programming --------------------------- diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index e77160cff..1b754ca82 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -75,7 +75,7 @@ The Basics Unittest -------- -Unittest is the batteries-included test module in the Python standard library. +:module:`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. @@ -92,7 +92,7 @@ Creating testcases is accomplished by subclassing a TestCase base class def test(self): self.assertEqual(fun(3), 4) -As of Python 2.7 unittest also includes its own test discovery mechanisms. +As of Python 2.7 :module:`unittest` also includes its own test discovery mechanisms. `unittest in the standard library documentation `_ @@ -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 :module:`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. @@ -140,7 +140,7 @@ Tools py.test ------- -py.test is a no-boilerplate alternative to Python's standard unittest module. +:program:`py.test` is a no-boilerplate alternative to Python's standard :module:`unittest` module. .. code-block:: console @@ -182,7 +182,7 @@ and then running the `py.test` command ========================= 1 failed in 0.02 seconds ========================= is far less work than would be required for the equivalent functionality with -the unittest module! +the :module:`unittest` module! `py.test `_ @@ -190,14 +190,14 @@ the unittest module! Nose ---- -nose extends unittest to make testing easier. +:module:`nose` extends :module:`unittest` to make testing easier. .. code-block:: console $ pip install nose -nose provides automatic test discovery to save you the hassle of manually +:module:`nose` provides automatic test discovery to save you the hassle of manually creating test suites. It also provides numerous plugins for features such as xUnit-compatible test output, coverage reporting, and test selection. @@ -222,7 +222,7 @@ simple ini-style configuration file. Unittest2 --------- -unittest2 is a backport of Python 2.7's unittest module which has an improved +:module:`unittest2` is a backport of Python 2.7's :module:`unittest` module which has an improved API and better assertions over the one available in previous versions of Python. If you're using Python 2.6 or below, you can install it with pip @@ -242,7 +242,7 @@ to newer versions of the module easier in the future ... 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 +:module:`unittest2` module, you can simply change the ``import`` in your test module without the need to change any other code. `unittest2 `_ @@ -251,7 +251,7 @@ the need to change any other code. mock ---- -``mock`` is a library for testing in Python. As of Python 3.3, it is +:module:`mock` is a library for testing in Python. As of Python 3.3, it is available in the `standard library Date: Sat, 5 Apr 2014 09:48:50 -0400 Subject: [PATCH 11/33] =?UTF-8?q?Add=20`:py:=C2=ABclassifier=C2=BB`=20mark?= =?UTF-8?q?up?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/scenarios/scrape.rst | 2 +- docs/scenarios/xml.rst | 2 +- docs/writing/gotchas.rst | 8 ++++---- docs/writing/structure.rst | 42 +++++++++++++++++++------------------- docs/writing/style.rst | 16 ++++++++------- docs/writing/tests.rst | 12 +++++------ 6 files changed, 42 insertions(+), 40 deletions(-) diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index 7a2173972..b19dc1388 100644 --- a/docs/scenarios/scrape.rst +++ b/docs/scenarios/scrape.rst @@ -31,7 +31,7 @@ Let's start with the imports: from lxml import html import requests -Next we will use ``requests.get`` to retrieve the web page with our data +Next we will use :py:func:`requests.get` to retrieve the web page with our data and parse it using the :module:`html` module and save the results in ``tree``: .. code-block:: python diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index 8a605290a..96cfc1521 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -52,7 +52,7 @@ An XML file like this: -can be loaded into a Python dict like this: +can be loaded into a Python :py:class:`dict` like this: .. code-block:: python diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 12e18619e..e2643c29d 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -65,7 +65,7 @@ What You Should Do Instead ~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a new object each time the function is called, by using a default arg to -signal that no argument was provided (:py:data:`None` is often a good choice). +signal that no argument was provided (:py:const:`None` is often a good choice). .. code-block:: python @@ -138,8 +138,8 @@ completed and ``i`` is left with its final value of 4. What's particularly nasty about this gotcha is the seemingly prevalent misinformation that this has something to do with :ref:`lambdas ` -in Python. Functions created with a ``lambda`` expression are in no way special, -and in fact the same exact behavior is exhibited by just using an ordinary ``def``: +in Python. Functions created with a :py:keyword:`lambda` expression are in no way special, +and in fact the same exact behavior is exhibited by just using an ordinary :py:keyword:`def`: .. code-block:: python @@ -166,7 +166,7 @@ its arguments by using a default arg like so: def create_multipliers(): return [lambda x, i=i : i * x for i in range(5)] -Alternatively, you can use the functools.partial function: +Alternatively, you can use the :py:func:`functools.partial` function: .. code-block:: python diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index a75800d01..5a117e641 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -34,23 +34,23 @@ to do it poorly. Some signs of a poorly structured project include: - Multiple and messy circular dependencies: if your classes - to answer a question such as ``table.isdoneby()``, - and if conversely the class Carpenter needs to import Table and Chair, - to answer the question ``carpenter.whatdo()``, then you :py:class:`Table` and :py:class:`Chair` in :file:`furn.py` need to import :py:class:`Carpenter` from :file:`workers.py` + to answer a question such as :py:func:`table.isdoneby()`, + and if conversely the class :py:class:`Carpenter` needs to import :py:class:`Table` and :py:class:`Chair`, + to answer the question :py:func:`carpenter.whatdo()`, then you have a circular dependency. In this case you will have to resort to - fragile hacks such as using import statements inside + fragile hacks such as using :py:keyword:`import` statements inside methods or functions. -- Hidden coupling: each and every change in Table's implementation - breaks 20 tests in unrelated test cases because it breaks Carpenter's code, +- Hidden coupling: each and every change in :py:class:`Table`'s implementation + breaks 20 tests in unrelated test cases because it breaks :py:class:`Carpenter`'s code, which requires very careful surgery to adapt the change. This means - you have too many assumptions about Table in Carpenter's code or the + you have too many assumptions about :py:class:`Table` in :py:class:`Carpenter`'s code or the reverse. - Heavy usage of global state or context: instead of explicitly passing ``(height, width, type, wood)`` to each other, Table - and Carpenter rely on global variables that can be modified + and :py:class:`Carpenter` rely on global variables that can be modified and are modified on the fly by different agents. You need to scrutinize all access to these global variables to understand why a rectangular table became a square, and discover that remote @@ -67,7 +67,7 @@ include: - Ravioli code is more likely in Python: it consists of hundreds of similar little pieces of logic, often classes or objects, without proper structure. If you never can remember if you have to use - FurnitureTable, AssetTable or Table, or even TableNew for your + :py:class:`FurnitureTable`, :py:class:`AssetTable` or :py:class:`Table`, or even :py:class:`TableNew` for your task at hand, you might be swimming in ravioli code. @@ -85,7 +85,7 @@ in one file, and all low-level operations in another file. In this case, the interface file needs to import the low-level file. This is done with the ``import`` and ``from ... import`` statements. -As soon as you use `import` statements you use modules. These can be either built-in +As soon as you use :py:keyword:`import` statements you use modules. These can be either built-in modules such as :module:`os` and :module:`sys`, third-party modules you have installed in your environment, or your project's internal modules. @@ -107,9 +107,9 @@ to be a module, but the import mechanism needs to be understood in order to use this concept properly and avoid some issues. Concretely, the ``import modu`` statement will look for the proper file, which is -recursively and raise an ImportError exception if it is not found. :file:`modu.py` in the same directory as the caller if it exists. If it is not found, the Python interpreter will search for :file:`modu.py` in the ``path`` +recursively and raise an :py:exc:`ImportError` exception if it is not found. Once `modu.py` is found, the Python interpreter will execute the module in an isolated scope. Any top-level statement in `modu.py` will be executed, @@ -166,7 +166,7 @@ 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 +:py:func:`modu.func` idiom, greatly improves code readability and understandability in all but the simplest single file projects. @@ -236,7 +236,7 @@ processes are spawned to respond to external requests that can happen at the same time. In this case, holding some state into instantiated objects, which means keeping some static information about the world, is prone to concurrency problems or race-conditions. Sometimes, between the initialization of -the state of an object (usually done with the ``__init__()`` method) and the actual use +the state of an object (usually done with the :py:func:`__init__()` method) and the actual use of the object state through one of its methods, the world may have changed, and the retained state may be outdated. For example, a request may load an item in memory and mark it as read by a user. If another request requires the deletion @@ -367,7 +367,7 @@ when they have a different type: There is no efficiency gain when reusing names: the assignments will have to create new objects anyway. However, when the complexity grows and each assignment is separated by other lines of code, including -'if' branches and loops, it becomes harder to ascertain what a given +:py:keyword:`if` branches and loops, it becomes harder to ascertain what a given variable's type is. Some coding practices, like functional programming, recommend never reassigning a variable. @@ -382,7 +382,7 @@ Mutable and immutable types Python has two kinds of built-in or user-defined types. Mutable types are those that allow in-place modification -of the content. Typical mutables are lists and dictionaries: +of the content. Typical mutables are :py:class:`list`s and :py:class:`dict`ionaries: All lists have mutating methods, like :py:meth:`list.append` or :py:meth:`list.pop`, and can be modified in place. The same goes for dictionaries. @@ -410,15 +410,15 @@ helps to clarify the intent of the code. For example, the immutable equivalent of a list is the tuple, created with ``(1, 2)``. This tuple is a pair that cannot be changed in-place, -and can be used as a key for a dictionary. +and can be used as a key for a :py:class:`dict`. One peculiarity of Python that can surprise beginners is that strings are immutable. This means that when constructing a string from its parts, it is much more efficient to accumulate the parts in a list, -which is mutable, and then glue ('join') the parts together when the +which is mutable, and then glue (:py:meth:`~str.join`) the parts together when the full string is needed. One thing to notice, however, is that list -comprehensions are better and faster than constructing a list in a loop -with calls to ``append()``. +comprehensions are better and faster than constructing a :py:class:`list` in a loop +with calls to :py:meth:`list.append()`. **Bad** @@ -448,10 +448,10 @@ with calls to ``append()``. nums = [str(n) for n in range(20)] print "".join(nums) -One final thing to mention about strings is that using ``join()`` is not always +One final thing to mention about strings is that using :py:meth:`~str.join()` is not always best. In the instances where you are creating a new string from a pre-determined number of strings, using the addition operator is actually faster, but in cases -like above or in cases where you are adding to an existing string, using ``join()`` +like above or in cases where you are adding to an existing string, using :py:meth:`~str.join()` should be your preferred method. .. code-block:: python diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 165117f2c..170ea22ff 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -44,7 +44,7 @@ most explicit and straightforward manner is preferred. return {'x': x, 'y': y} In the good code above, x and y are explicitly received from -the caller, and an explicit dictionary is returned. The developer +the caller, and an explicit :py:class:`dict` is returned. The developer using this function knows exactly what to do by reading the first and last lines, which is not the case with the bad example. @@ -104,7 +104,7 @@ 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 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 +Here ``cc`` and ``bcc`` are optional, and evaluate to :py:const:`None` when they are not passed another value. Calling a function with keyword arguments can be done in multiple ways in Python, @@ -273,7 +273,7 @@ Unpacking ~~~~~~~~~ If you know the length of a list or tuple, you can assign names to its -elements with unpacking. For example, since ``enumerate()`` will provide +elements with unpacking. For example, since :py:func:`enumerate()` will provide a tuple of two elements for each item in list: .. code-block:: python @@ -360,8 +360,10 @@ 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. +Even though both functions look identical, because :py:meth:`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 @@ -438,8 +440,8 @@ Here are some conventions you should follow to make your code easier to read. Check if variable equals a constant ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You don't need to explicitly compare a value to True, or None, or 0 - you can -just add it to the if statement. See `Truth Value Testing +You don't need to explicitly compare a value to :py:const:`True`, or :py:const:`None`, or :py:const:`0` - you can +just add it to the :py:keyword:`if` statement. See `Truth Value Testing `_ for a list of what is considered false. diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 1b754ca82..03064dec2 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 :py:meth:`setUp` and :py: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 @@ -49,9 +49,9 @@ Some general rules of testing: - 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 + :py:func:`square()` or even :py:func:`sqr()` is okat in running code, but in testing code you + would have names such as :py:func:`test_square_of_number_2()`, + :py:func:`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 @@ -79,7 +79,7 @@ Unittest 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 :py:class:`TestCase` base class. .. code-block:: python @@ -274,7 +274,7 @@ For example, you can monkey-patch a method: thing.method.assert_called_with(3, 4, 5, key='value') -To mock classes or objects in a module under test, use the ``patch`` decorator. +To mock classes or objects in a module under test, use the :py:func:`@patch` decorator. In the example below, an external search system is replaced with a mock that always returns the same result (but only for the duration of the test). From d82510371e00abe2ad544dc958c0ef4ff2b45426 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:06:52 -0400 Subject: [PATCH 12/33] starting/which-python.rst: Add `:abbr:` markup --- docs/starting/which-python.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 66dca2d57..fffa12769 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -74,9 +74,9 @@ 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 -module. +Python code to Java bytecode that is then executed in a :abbr:`JVM (Java Virtual Machine)`. +It has the additional advantage of being 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 need to write Python code for the JVM, Jython is the best choice. From 4c2c0611d0b3b6ad5056078ee32fd1686df31a8c Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:52:11 -0400 Subject: [PATCH 13/33] dev/env.rst: Markup tweaks --- docs/dev/env.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index d0636f970..9a8e6a9bd 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -40,7 +40,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 @@ -50,12 +50,16 @@ the bottom of the screen, and provide an easy way to jump to the corresponding line. It's very handy to call these functions whenever you save a file. In order to do this, add the following lines to your :file:`.vimrc`: +.. code-block:: + autocmd BufWritePost *.py call Pyflakes() autocmd BufWritePost *.py call Pep8() If you are already using syntastic_ you can enable it to run Pyflakes on write and show errors and warnings in the quickfix window. An example configuration -to do that which also shows status and warning messages in the statusbar would be:: +to do that which also shows status and warning messages in the statusbar would be: + +.. code-block:: set statusline+=%#warningmsg# set statusline+=%{SyntasticStatuslineFlag()} @@ -225,9 +229,9 @@ To start using the virtual environment, run: The name of the current virtual environment will now appear on the left -of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to +of the prompt (e.g. :samp:`(venv){Your-Computer}:{your_project} {UserName}$`) to let you know that it's active. From now on, any package that you install -using ``pip`` will be placed in the ``venv`` folder, isolated from the global +using :program:`pip` will be placed in the :file:`venv` folder, isolated from the global Python installation. Install packages as usual: @@ -238,12 +242,12 @@ Install packages as usual: To stop using an environment, simply type ``deactivate``. To remove the environment, just remove the directory it was installed into. (In this -case, it would be ``rm -rf venv``.) +case, it would be :command:`rm -rf venv`.) Other Notes ^^^^^^^^^^^ -Running ``virtualenv`` with the option ``--no-site-packages`` will not +Running :program:`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.] From 585a928ce0d900c3456e1a96a68d5daacc21ae4d Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 09:53:21 -0400 Subject: [PATCH 14/33] intro/duction.rst: Minor edits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I love how “place of inscrutable punctuation” forgot to end itself with any kind of punctuation. :P --- docs/intro/duction.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 23d9240f1..9e9b0ae53 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -11,7 +11,7 @@ include: Python's philosophy focuses on readability, from code blocks delineated with significant whitespace to intuitive keywords in - place of inscrutable punctuation + place of inscrutable punctuation. * **extensive standard libraries and third party modules for virtually any task** @@ -41,7 +41,7 @@ include: * **ubiquity on computers** Python is available on Windows, \*nix, and Mac. It runs wherever the - Java virtual machine runs, and the reference implementation CPython + Java virtual machine runs, and the reference implementation :program:`CPython` can help bring Python to wherever there is a working C compiler. * **friendly community** @@ -76,8 +76,8 @@ For the Community ~~~~~~~~~~~~~~~~~ All contributions to the Guide are welcome, from Pythonistas of all levels. -If you think there's a gap in what the Guide covers, fork the Guide on -GitHub and submit a pull request. +If you think there's a gap in what The Guide covers, fork the Guide on +GitHub and submit a pull request. Contributions are welcome from everyone, whether they're an old hand or a first-time Pythonista, and the authors to the Guide will gladly help if you From 61870ea22f476fea4b1e8c78468be511c6635e50 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:01:15 -0400 Subject: [PATCH 15/33] scenarios/scrape.rst: Tweak markup --- docs/scenarios/scrape.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index b19dc1388..efa144cb3 100644 --- a/docs/scenarios/scrape.rst +++ b/docs/scenarios/scrape.rst @@ -40,7 +40,7 @@ and parse it using the :module:`html` module and save the results in ``tree``: tree = html.fromstring(page.text) ``tree`` now contains the whole HTML file in a nice tree structure which -we can go over two different ways: XPath and CSSSelect. In this example, I +we can go over two different ways: :dfn:`XPath` and :dfn:`CSSSelect`. In this example, I will focus on the former. XPath is a way of locating information in structured documents such as @@ -53,8 +53,8 @@ can right click an element, choose 'Inspect element', highlight the code, right click again and choose 'Copy XPath'. After a quick analysis, we see that in our page the data is contained in -two elements - one is a div with title 'buyer-name' and the other is a -span with class 'item-price': +two elements - one is a ``div`` with title ``buyer-name`` and the other is a +span with class ``item-price``: .. code-block:: html From 0960b4fc5149d1466ea0f33ef1bc90be5ec54b25 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:02:17 -0400 Subject: [PATCH 16/33] shipping/freezing.rst: Tweak markup --- docs/shipping/freezing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 7fd199f74..428279467 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -28,7 +28,7 @@ pyInstaller yes yes yes no GPL yes no yes cx_Freeze yes yes yes yes PSF no yes yes no =========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== -.. todo:: Add other solutions: py2app +.. todo:: Add other solutions: :program:`py2app` .. note:: Freezing Python code on Linux into a Windows executable was only once @@ -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 `Configure.py`. + passing :option:`--onefile` to :file:`Configure.py`. Windows ------- @@ -72,7 +72,7 @@ Prerequisite is to install :ref:`Python on Windows `. 4. (Optionally) `one-file mode `_ -5. Generate ``.exe`` into ``dist`` directory: +5. Generate :program:`.exe` into :file:`dist` directory: .. code-block:: console From ba0f62754c212c037b35a2f18931a961a1375471 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:02:36 -0400 Subject: [PATCH 17/33] shipping/packaging.rst: Tweak markup --- docs/shipping/packaging.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 24352cac1..b491c5172 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -46,8 +46,8 @@ Go to your command prompt and type: $ python -m SimpleHTTPServer 9000 This runs a simple http server running on port 9000 and will list all packages -package installer. Using Pip, you would do it like: (like :module:`MyPackage`). Now you can install :module:`MyPackage` using any Python +package installer. Using :program:`pip`, you would do it like: .. code-block:: console @@ -66,8 +66,8 @@ 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 +It can be used to serve a set of packages to :program:`easy_install` or :program:`pip`. It includes helpful +features like an administrative command (:option:`-U`) which will update all its packages to their latest versions found on PyPI. From cbe2522895864acb3892bf6a93d157a1d00412d2 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:02:58 -0400 Subject: [PATCH 18/33] starting/install/linux.rst: Tweak markup --- docs/starting/install/linux.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index b2216aeea..62e343784 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -34,11 +34,11 @@ your own Python software with very little work. To obtain the latest version of Setuptools for Linux, refer to the documentation available here: `unix-setuptools `_ -The new``easy_install`` command you have available is considered by many to be -deprecated, so we will install its replacement: **pip**. Pip allows for +The new :program:`easy_install` command you have available is considered by many to be +deprecated, so we will install its replacement: :program:`pip`. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. -To install pip, simply open a command prompt and run +To install :program:`pip`, simply open a command prompt and run: .. code-block:: console @@ -48,22 +48,22 @@ To install pip, simply open a command prompt and run Virtualenv ---------- -After Setuptools & Pip, the next development tool that you should install is +After Setuptools and Pip, the next development tool that you should install is `virtualenv `_. Use pip .. code-block:: console $ pip install virtualenv -The virtualenv kit provides the ability to create virtual Python environments +The :program:`virtualenv` kit provides the ability to create virtual Python environments that do not interfere with either each other, or the main Python installation. -If you install virtualenv before you begin coding then you can get into the +If you install :program:`virtualenv` before you begin coding, then you can get into the habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. To set up a new Python environment, change the working directory to where ever -you want to store the environment, and run the virtualenv utility in your +you want to store the environment, and run the :program:`virtualenv` utility in your project's directory .. code-block:: console @@ -75,7 +75,7 @@ will change to show the active environment. Once you have finished working in the current virtual environment, run ``deactivate`` to restore your settings to normal. -Each new environment automatically includes a copy of ``pip``, so that you can +Each new environment automatically includes a copy of :program:`pip`, so that you can setup the third-party libraries and tools that you want to use in that environment. Put your own code within a subdirectory of the environment, however you wish. When you no longer need a particular environment, simply From 63dc23388dc94ca187b393abb2b0eaec9516a0c7 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:03:13 -0400 Subject: [PATCH 19/33] starting/install/osx.rst: Tweak markup --- docs/starting/install/osx.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 454928812..8d486b576 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -78,7 +78,7 @@ command. It also enables you to add this network installation capability to your own Python software with very little work. Homebrew already installed Setuptools for you. -Happily, when you ran `brew install python`, Homebrew also installed **pip**. +Happily, when you ran ``brew install python``, Homebrew also installed :program:`pip`. Pip allows for installation and uninstallation of packages, and is actively maintained. @@ -86,22 +86,22 @@ maintained. Virtualenv ---------- -After Setuptools & Pip, the next development tool that you should install is +After Setuptools and Pip, the next development tool that you should install is `virtualenv `_. Use pip .. code-block:: console $ pip install virtualenv -The virtualenv kit provides the ability to create virtual Python environments +The :program:`virtualenv` kit provides the ability to create virtual Python environments that do not interfere with either each other, or the main Python installation. -If you install virtualenv before you begin coding then you can get into the +If you install :program:`virtualenv` before you begin coding then you can get into the habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. To set up a new Python environment, move into the directory where you would -like to store the environment, and use the ``virtualenv`` utility to create +like to store the environment, and use the :program:`virtualenv` utility to create the new environment. .. code-block:: console @@ -113,14 +113,14 @@ will change to show the active environment. Once you have finished working in the current virtual environment, run ``deactivate`` to restore your settings to normal. -Each new environment automatically includes a copy of ``pip``, so that you can +Each new environment automatically includes a copy of :program:`pip`, so that you can setup the third-party libraries and tools that you want to use in that 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, -`RTFD `_ to find out more. +An useful set of extensions to :program:`virtualenv` is available in +:program:`virtualenvwrapper`. `RTFD `_ to find out more. -------------------------------- From b21c26b728da4ee5b949bb3cd1326c6b8c34755a Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:03:37 -0400 Subject: [PATCH 20/33] dev/env.rst: Tweak markup --- docs/dev/env.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 9a8e6a9bd..ffc59d524 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -73,10 +73,10 @@ Python-mode Python-mode_ is a complex solution in VIM for working with Python code. It has: -- Asynchronous Python code checking (``pylint``, ``pyflakes``, ``pep8``, ``mccabe``) in any combination -- Code refactoring and autocompletion with Rope +- Asynchronous Python code checking (:program:`pylint`, :program:`pyflakes`, :program:`pep8`, :program:`mccabe`) in any combination +- Code refactoring and autocompletion with :program:`rope` - Fast Python folding -- Virtualenv support +- :program:`virtualenv` support - Search by Python documentation and run Python code - Auto PEP8_ error fixes @@ -192,7 +192,7 @@ Interpreter Tools virtualenv ---------- -Virtualenv is a tool to keep the dependencies required by different projects +:program:`virtualenv` is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps your global site-packages directory clean and manageable. @@ -216,7 +216,7 @@ Create a virtual environment for a project: $ virtualenv venv ``virtualenv venv`` will create a folder in the current directory -which will contain the Python executable files, and a copy of the ``pip`` +which will contain the Python executable files, and a copy of the :program:`pip` library which you can use to install other packages. The name of the virtual environment (in this case, it was ``venv``) can be anything; omitting the name will place the files in the current directory instead. @@ -250,7 +250,7 @@ Other Notes Running :program:`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.] +[This is the default behavior for :program:`virtualenv` 1.7 and later.] In order to keep your environment consistent, it's a good idea to "freeze" the current state of the environment packages. To do this, run @@ -294,7 +294,7 @@ Put this into your :file:`~/.bash_profile` (Linux/Mac) file: This will prevent your virtualenvs from relying on your (global) :file:`site-packages` directory, so that they are completely separate.. -[note: This is the default behavior for ``virtualenv`` 1.7 and later] +[note: This is the default behavior for :program:`virtualenv` 1.7 and later] Other Tools ::::::::::: From 7b30151bb721208bf3ea56c40ed0f2c13796f248 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:03:51 -0400 Subject: [PATCH 21/33] dev/virtualenvs.rst: Tweak markup --- docs/dev/virtualenvs.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 34e6c8b3f..0179b3350 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -14,7 +14,7 @@ virtualenv `virtualenv `_ is a tool to create isolated Python environments. -Install it via pip: +Install it via :program:`pip`: .. code-block:: console @@ -64,7 +64,7 @@ virtualenvwrapper provides a set of commands which makes working with virtual environments much more pleasant. It also places all your virtual environments in one place. -To install (make sure **virtualenv** is already installed): +To install (make sure :program:`virtualenv` is already installed): .. code-block:: console @@ -76,7 +76,7 @@ To install (make sure **virtualenv** is already installed): For Windows, you can use the `virtualenvwrapper-powershell `_ clone. -To install (make sure **virtualenv** is already installed): +To install (make sure :program:`virtualenv` is already installed): .. code-block:: console @@ -102,7 +102,7 @@ This creates the :file:`venv` folder inside :file:`~/Envs`. $ workon venv -**virtualenvwrapper** provides tab-completion on environment names. It really +:program:`virtualenvwrapper` provides tab-completion on environment names. It really helps when you have a lot of environments and have trouble remembering their names. ``workon`` also deactivates whatever environment you are currently in, so you @@ -143,7 +143,7 @@ autoenv When you :command:`cd` into a directory containing :file:`.env`, `autoenv `_ automagically activates the environment. -Install it on Mac OS X using ``brew``: +Install it on Mac OS X using :program:`brew`: .. code-block:: console From b7b6f83a43ffa2db397058581ef1b06550b4c1ce Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:04:03 -0400 Subject: [PATCH 22/33] scenarios/admin.rst: Tweak markup --- docs/scenarios/admin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 4f3b15ac1..ea935123c 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -77,7 +77,7 @@ It supports remote command execution from a central point (master host) to multi hosts (minions). It also supports system states which can be used to configure multiple servers using simple template files. -Salt supports Python versions 2.6 and 2.7 and can be installed via pip: +:program:`Salt` supports Python versions 2.6 and 2.7 and can be installed via :program:`pip`: .. code-block:: console From db8d9aec6b7eee6e7827e359ca1836d3b235d48e Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:04:14 -0400 Subject: [PATCH 23/33] scenarios/gui.rst: Tweak markup --- 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 86551079e..d9e16abb1 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -91,7 +91,7 @@ available on the `Python Wiki `_. wxPython -------- -wxPython is a GUI toolkit for the Python programming language. It allows +:program:`wxPython` is a GUI toolkit for the Python programming language. It allows Python programmers to create programs with a robust, highly functional graphical user interface, simply and easily. It is implemented as a Python extension module (native code) that wraps the popular wxWidgets cross platform From afa597db3729d4e6b854180dfdb1321b4e229b47 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:05:29 -0400 Subject: [PATCH 24/33] scenarios/scientific.rst: Tweak whitespace, markup, and capitalization --- docs/scenarios/scientific.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index e95506517..7f66c6778 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -45,7 +45,6 @@ problem of running slower algorithms on Python by using multidimensional arrays and functions that operate on arrays. Any algorithm can then be expressed as a function on arrays, allowing the algorithms to be run quickly. - NumPy is part of the SciPy project, and is released as a separate library so people who only need the basic requirements can just use NumPy. @@ -54,16 +53,16 @@ NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+. Numba ----- -`Numba `_ is an Numpy aware Python compiler -(just-in-time (JIT) specializing compiler) which compiles annotated Python (and -Numpy) code to LLVM (Low Level Virtual Machine) (through special decorators). +`Numba `_ is an NumPy-aware Python :abbr:`JIT (just-in-time)` +compiler, which compiles annotated Python (and NumPy) code to +:abbr:`LLVM (Low Level Virtual Machine)` (through special decorators). Briefly, Numba using system that compiles Python code with LLVM to code which can be natively executed at runtime. SciPy ----- -`SciPy `_ is a library that uses Numpy for more mathematical +`SciPy `_ is a library that uses NumPy for more mathematical functions. SciPy uses NumPy arrays as the basic data structure. SciPy comes with modules for various commonly used tasks in scientific programming, for example: linear algebra, integration (calculus), ordinary differential equation @@ -83,7 +82,7 @@ can be browsed at the `matplotlib gallery Pandas ------ `Pandas `_ is data manipulation library -based on Numpy and which provides many useful functions for accessing, +based on NumPy and which provides many useful functions for accessing, indexing, merging and grouping data easily. The main data structure (DataFrame) is close to what could be found in the R statistical package, that is an heterogeneous data tables with name indexing, time series operations @@ -93,7 +92,7 @@ Rpy2 ---- `Rpy2 `_ is a Python binding for the R statistical package allowing to execute R functions from Python and passing -data back and forth the two environments. Rpy2 is the object oriented +data back and forth the two environments. Rpy2 is the object-oriented implementation of the binding based on `Rpy `_. PsychoPy From 9d90621b41b140e1294ccf1facce8a5ec108c713 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:05:47 -0400 Subject: [PATCH 25/33] starting/install/win.rst: Tweak markup --- docs/starting/install/win.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index 6acbd017e..762178787 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -29,7 +29,7 @@ Assuming that your Python installation is in :file:`C:\Python27\`, add this to y C:\Python27\;C:\Python27\Scripts\ -You can do this easily by running the following in ``powershell``: +You can do this easily by running the following in :program:`powershell`: .. code-block:: console @@ -57,12 +57,12 @@ To obtain the latest version of Setuptools for Windows, run the python script available here: `ez_setup.py `_ -You'll now have a new command available to you: **easy_install**. It is +You'll now have a new command available to you: :program:`easy_install`. It is 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. +:program:`pip`. Pip allows for uninstallation of packages, and is actively maintained, +unlike :program:`easy_install`. -To install pip, run the python script available here: +To install :program:`pip`, run the Python script available here: `get-pip.py `_ @@ -76,16 +76,15 @@ After Setuptools & Pip, the next development tool that you should install is > pip install virtualenv -The virtualenv kit provides the ability to create virtual Python environments +The :program:`virtualenv` kit provides the ability to create virtual Python environments that do not interfere with either each other, or the main Python installation. -If you install virtualenv before you begin coding then you can get into the +If you install :program:`virtualenv` before you begin coding then you can get into the habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. - To set up a new Python environment, change the working directory to wherever -you want to store the environment, and run the virtualenv utility in your +you want to store the environment, and run the :program:`virtualenv` utility in your project's directory .. code-block:: console @@ -98,7 +97,7 @@ active environment. Once you have finished working in the current virtual environment, run the :file:`deactivate.bat` batch file to restore your settings to normal. -Each new environment automatically includes a copy of ``pip`` in the +Each new environment automatically includes a copy of :program:`pip` in the :file:`Scripts` subdirectory, so that you can setup the third-party libraries and tools that you want to use in that environment. Put your own code within a subdirectory of the environment, however you wish. When you no longer need a From 9ff54851e31344c28692b5f017f78342075ec4e6 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:06:29 -0400 Subject: [PATCH 26/33] starting/pip-virtualenv.rst: Tweak markup --- docs/starting/pip-virtualenv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/pip-virtualenv.rst b/docs/starting/pip-virtualenv.rst index 0db949493..772f24167 100644 --- a/docs/starting/pip-virtualenv.rst +++ b/docs/starting/pip-virtualenv.rst @@ -3,7 +3,7 @@ Further Configuration of Pip and Virtualenv =========================================== -Requiring an active virtual environment for ``pip`` +Requiring an active virtual environment for :program:`pip` --------------------------------------------------- By now it should be clear that using virtual envirtonments is a great way to keep From 6a7c37ab008d0be041039166d8dd904a8677f035 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:07:18 -0400 Subject: [PATCH 27/33] writing/documentation.rst: Minor edit --- docs/writing/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index c005d1e4e..43c053c20 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -158,7 +158,7 @@ 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 manpages. It converts human readable textfiles to roff for terminal display, and also to HTML for the web. .. _Ronn: https://github.com/rtomayko/ronn From e139fd13ebf81bbbb26a4c75e2116f5931d3ea9b Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:07:28 -0400 Subject: [PATCH 28/33] writing/gotchas.rst: Tweak markup --- 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 e2643c29d..d074bccb3 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -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, but 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 @@ -134,7 +134,7 @@ up at the time the inner function is called. Here, whenever *any* of the returned functions are called, the value of ``i`` is looked up in the surrounding scope at call time. By then, the loop has -completed and ``i`` is left with its final value of 4. +completed and ``i`` is left with its final value of ``4``. What's particularly nasty about this gotcha is the seemingly prevalent misinformation that this has something to do with :ref:`lambdas ` From 69d0e487b2e749b60cb0f40edc18a9fb1311830b Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:09:31 -0400 Subject: [PATCH 29/33] writing/license.rst: Minor edit --- 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 a50023f22..8eb902f37 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -26,8 +26,8 @@ The latter are less permissive in the sense that they don't permit someone to add code to the software and distribute it without also including the source code for their changes. -To help you choose one for your project, there's a `license chooser `_, -**use it**. +To help you choose one for your project, there's a `license chooser `_. +**Use it**. **More Permissive** From 5d9c8582e31576670722d5fc73d893f83d2ed81c Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:09:47 -0400 Subject: [PATCH 30/33] writing/structure.rst: Tweak markup --- docs/writing/structure.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 5a117e641..86cc9ef83 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** @@ -197,7 +197,7 @@ 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 +``import very.deep.module as mod``. This allows you to use ``mod`` in place of the verbose repetition of :module:`very.deep.module`. Object-oriented programming @@ -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, it can be done 'manually', but using the :samp:`@{decorator}` syntax is clearer and thus preferred. .. code-block:: python @@ -319,12 +319,12 @@ 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 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. +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. The dynamic typing of Python is often considered to be a weakness, and indeed it can lead to complexities and hard-to-debug code. Something -named 'a' can be set to many different things, and the developer or the +named ``a`` can be set to many different things, and the developer or the maintainer needs to track this name in the code to make sure it has not been set to a completely unrelated object. @@ -371,7 +371,7 @@ grows and each assignment is separated by other lines of code, including variable's type is. Some coding practices, like functional programming, recommend never reassigning a variable. -In Java this is done with the `final` keyword. Python does not have a `final` keyword +In Java this is done with the ``final`` keyword. Python does not have a ``final`` keyword and it would be against its philosophy anyway. However, it may be a good discipline to avoid assigning to a variable more than once, and it helps in grasping the concept of mutable and immutable types. @@ -387,8 +387,8 @@ All lists have mutating methods, like :py:meth:`list.append` or :py:meth:`list.p can be modified in place. The same goes for dictionaries. Immutable types provide no method for changing their content. -For instance, the variable x set to the integer 6 has no "increment" method. If you -want to compute x + 1, you have to create another integer and give it +For instance, the variable ``x`` set to the integer ``6`` has no "increment" method. If you +want to compute ``x + 1``, you have to create another integer and give it a name. .. code-block:: python From 867862fca7d996e7543888ae13fe80487a6d0f54 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:10:04 -0400 Subject: [PATCH 31/33] writing/style.rst: Tweak markup --- docs/writing/style.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 170ea22ff..10e7fe038 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -43,7 +43,7 @@ most explicit and straightforward manner is preferred. def make_complex(x, y): return {'x': x, 'y': y} -In the good code above, x and y are explicitly received from +In the good code above, ``x`` and ``y`` are explicitly received from the caller, and an explicit :py:class:`dict` is returned. The developer using this function knows exactly what to do by reading the first and last lines, which is not the case with the bad example. @@ -176,8 +176,8 @@ 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 deeply from them. Many code analysis tools, such as :program:`pylint` +or :program:`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 @@ -192,10 +192,10 @@ We are all consenting adults As seen above, Python allows many tricks, and some of them are potentially 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 +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". +give a lot of mechanisms to prevent any misuse, is expressed by the saying: +"We are 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 @@ -204,7 +204,7 @@ Python community prefers to rely on a set of conventions indicating that these elements should not be accessed directly. The main convention for private properties and implementation details is to -prefix all "internals" with an underscore. If the client code breaks this rule +prefix all "internals" with an underscore (``_``). If the client code breaks this rule and accesses these marked elements, any misbehavior or problems encountered if the code is modified is the responsibility of the client code. @@ -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. @@ -328,7 +328,7 @@ Create a length-N list of lists ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Because lists are mutable, the ``*`` operator (as above) will create a list -of N references to the `same` list, which is not likely what you want. +of N references to the ``same`` list, which is not likely what you want. Instead, use a list comprehension: .. code-block:: python @@ -343,9 +343,11 @@ A common idiom for creating strings is to use :py:meth:`str.join` on an empty st letters = ['s', 'p', 'a', 'm'] word = ''.join(letters) -This will set the value of the variable *word* to 'spam'. This idiom can be applied to lists and tuples. +This will set the value of the variable ``word`` to ``'spam'``. +This idiom can be applied to lists and tuples. -Sometimes we need to search through a collection of things. Let's look at two options: lists and dictionaries. +Sometimes we need to search through a collection of things. +Let's look at two options: lists and dictionaries. Take the following code for example: From f8165929c4a5970098eb755bf769b80bd00793db Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:10:23 -0400 Subject: [PATCH 32/33] writing/tests.rst: Tweak markup --- docs/writing/tests.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 03064dec2..cf6c9236c 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -159,7 +159,7 @@ functions: def test_answer(): assert func(3) == 5 -and then running the `py.test` command +and then running the :program:`py.test` command .. code-block:: console @@ -207,14 +207,14 @@ xUnit-compatible test output, coverage reporting, and test selection. tox --- -tox is a tool for automating test environment management and testing against -multiple interpreter configurations +:program:`tox` is a tool for automating test environment management and testing against +multiple interpreter configurations. .. code-block:: console $ pip install tox -tox allows you to configure complicated multi-parameter test matrices via a +:program:`tox` allows you to configure complicated multi-parameter test matrices via a simple ini-style configuration file. `tox `_ @@ -225,13 +225,13 @@ Unittest2 :module:`unittest2` is a backport of Python 2.7's :module:`unittest` module which has an improved API and better assertions over the one available in previous versions of Python. -If you're using Python 2.6 or below, you can install it with pip +If you're using Python 2.6 or below, you can install it with :program:`pip`. .. code-block:: console $ pip install unittest2 -You may want to import the module under the name unittest to make porting code +You may want to import the module under the name ``unittest``, to make porting code to newer versions of the module easier in the future .. code-block:: python From 3cb82593b33ff9376e4f28b0de19f0b2fb53804b Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 5 Apr 2014 10:10:34 -0400 Subject: [PATCH 33/33] Readme.rst: Tweak markup --- Readme.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Readme.rst b/Readme.rst index 07106e2f0..21f76e6fb 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 :program:`hg` from :program:`git` easily If you aren't fond of reading reStructuredText, there is an almost up-to-date `HTML version at docs.python-guide.org