@@ -447,6 +469,10 @@ is simple enough to grasp from an example:
+
+But keep in mind that the full `Default Text`
+syntax allows for default content in the unrendered template.
+
.. rubric:: References
.. [1] `The mod_python project is now officially dead `_
From 53bf93d76770ba00ea6dcafbf4f1eb18b38dd905 Mon Sep 17 00:00:00 2001
From: Michael Bernstein
Date: Sun, 7 Dec 2014 13:43:48 -0600
Subject: [PATCH 046/760] A bit more editing and cleanup of the Chameleon
section.
---
docs/scenarios/web.rst | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index b267f74ec..c879438c2 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -422,14 +422,15 @@ engine implementation of the `Template Attribute Language (TAL) ` syntaxes.
Chameleon is available for Python 2.5 and up (including 3.x and pypy), and
-is commonly used by the `Pyramid Framework `_.
+is commonly used by the `Pyramid Framework `_.
Page Templates add within your document structure special element attributes
and text markup. Using a set of simple language constructs, you control the
document flow, element repetition, text replacement and translation. Because
of the attribute-based syntax, unrendered page templates are valid HTML and can
be viewed in a browser and even edited in WYSIWYG editors. This can make
-round-trip collaboration with designers and prototyping in a browser easier.
+round-trip collaboration with designers and prototyping with static files in a
+browser easier.
The basic TAL language is simple enough to grasp from an example:
@@ -471,7 +472,7 @@ you can replace it with a more terse and readable syntax that uses the pattern
But keep in mind that the full `Default Text`
-syntax allows for default content in the unrendered template.
+syntax also allows for default content in the unrendered template.
.. rubric:: References
From 459a7f23975c1f5e3c4057dfead94ce2381ed812 Mon Sep 17 00:00:00 2001
From: ankur
Date: Tue, 9 Dec 2014 01:03:07 +0530
Subject: [PATCH 047/760] Added a importpython weekly newsletter to the listing
---
docs/intro/news.rst | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/docs/intro/news.rst b/docs/intro/news.rst
index 32c44d4af..fbb3ebfac 100644
--- a/docs/intro/news.rst
+++ b/docs/intro/news.rst
@@ -16,6 +16,14 @@ Python-related news.
`/r/python `_
+Import Python Weekly
+~~~~~~~~~~~~~~~~
+
+Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets delivered in your inbox.
+Keep Your Python Programming Skills Updated.
+
+ `Import Python Weekly Newsletter `_
+
Pycoder's Weekly
~~~~~~~~~~~~~~~~
From 082203fd90c5fc6200f087ae0823affc6bbef7ff Mon Sep 17 00:00:00 2001
From: ankur
Date: Tue, 9 Dec 2014 10:38:46 +0530
Subject: [PATCH 048/760] Appended the Import Python Newsletter listing to the
news section
---
docs/intro/news.rst | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/docs/intro/news.rst b/docs/intro/news.rst
index fbb3ebfac..b44e7da5a 100644
--- a/docs/intro/news.rst
+++ b/docs/intro/news.rst
@@ -16,14 +16,6 @@ Python-related news.
`/r/python `_
-Import Python Weekly
-~~~~~~~~~~~~~~~~
-
-Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets delivered in your inbox.
-Keep Your Python Programming Skills Updated.
-
- `Import Python Weekly Newsletter `_
-
Pycoder's Weekly
~~~~~~~~~~~~~~~~
@@ -47,3 +39,11 @@ Python News is the news section in the official Python web site (www.python.org)
highlights the news from the Python community.
`Python News `_
+
+Import Python Weekly
+~~~~~~~~~~~~~~~~
+
+Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets delivered in your inbox.
+Keep Your Python Programming Skills Updated.
+
+ `Import Python Weekly Newsletter `_
From 49988bf59ca78ae96bea2cb000c5f19b3b43cdcd Mon Sep 17 00:00:00 2001
From: Sam Clift
Date: Thu, 11 Dec 2014 15:31:31 +0000
Subject: [PATCH 049/760] add initial JSON section
---
docs/contents.rst.inc | 1 +
docs/scenarios/json.rst | 138 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 139 insertions(+)
create mode 100644 docs/scenarios/json.rst
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index 8e8cd73d3..cc385325c 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -59,6 +59,7 @@ different scenarios.
scenarios/scientific
scenarios/imaging
scenarios/xml
+ scenarios/json
scenarios/crypto
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
new file mode 100644
index 000000000..3683eecfc
--- /dev/null
+++ b/docs/scenarios/json.rst
@@ -0,0 +1,138 @@
+JSON parsing
+===========
+
+json
+-----
+
+`json `_ is a standard libary which can convert JSON to a Dictionay.
+
+For example, a JSON string like this:
+
+.. code-block:: python
+
+ "{'first_name':'Guido','last_name':'Rossum'}"
+
+can be loaded like this:
+
+.. code-block:: python
+
+ import json
+ converted_dict = json.loads(json_string)
+
+you can now use it as a normal dictionary:
+
+.. code-block:: python
+
+ converted_dict['first_name']
+
+As well as converting a JSON string to a dictionary. You can convert a dictionary to JSON
+
+For example, given:
+
+.. code-block:: python
+
+ d = {
+ 'first_name': 'Guido',
+ 'second_name': 'Rossum'
+ }
+
+ import json
+ print json.dumps(d)
+ "{'first_name':'Guido','last_name':'Rossum'}"
+
+It is also possible to import JSON files:
+
+.. code-block:: python
+
+ import json
+ with file('path/to/file.json') as json_file:
+ processed_json = json.load(json_file)
+ print processsed_json
+ {u'first_name': u'Guido', u'last_name': u'Rossum'}
+
+As well as write to them:
+
+.. code-block:: python
+
+ import json
+ with file('path/to/file.json', 'w') as json_file:
+ dict = {
+ "first_name": "Guido",
+ "last_name": "Rossum",
+ "middle_name": "Van"
+ }
+ json.dump(dict, json_file)
+
+simplejson
+----------
+
+Installation
+
+.. code-block:: python
+
+ pip install simplejson
+
+`simplejson `_ is the externally maintained development version of the json library.
+
+simplejson is updated much more frequently than the Python. Meaning you can get updates much quicker.
+
+For example, a JSON string like this:
+
+.. code-block:: python
+
+ "{'first_name':'Guido','last_name':'Rossum'}"
+
+can be loaded like this:
+
+.. code-block:: python
+
+ import simplejson
+ converted_dict = simplejson.loads(json_string)
+
+you can now use it as a normal dictionary:
+
+.. code-block:: python
+
+ converted_dict['first_name']
+
+As well as converting a json string to dictionarys. You can convert dictionarys to json
+
+For example, given:
+
+.. code-block:: python
+
+ import simplejson
+
+ d = {
+ 'first_name': 'Guido',
+ 'second_name': 'Rossum'
+ }
+ print simplejson.dumps(d)
+ "{'first_name':'Guido','last_name':'Rossum'}"
+
+
+It is also possible to import JSON files:
+
+.. code-block:: python
+
+ import simplejson
+
+ with file('path/to/file.json') as json_file:
+ processed_json = simplejson.load(json_file)
+ print processsed_json
+ {u'first_name': u'Guido', u'last_name': u'Rossum'}
+
+As well as write to them:
+
+.. code-block:: python
+
+ import simplejson
+
+ with file('path/to/file.json', 'w') as json_file:
+ dict = {
+ "first_name": "Guido",
+ "last_name": "Rossum",
+ "middle_name": "Van"
+ }
+ simplejson.dump(dict, json_file)
+
From aa951a138ddf03f64dcf8fdab99e16b55bf372af Mon Sep 17 00:00:00 2001
From: Gerard Ryan
Date: Mon, 5 Jan 2015 12:08:51 +0000
Subject: [PATCH 050/760] Fix minor type in tests.rst: is -> in
---
docs/writing/tests.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index f416944a4..f8856d69e 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -58,7 +58,7 @@ Some general rules of testing:
good set of tests, you or other maintainers will rely largely on the
testing suite to fix the problem or modify a given behavior. Therefore
the testing code will be read as much as or even more than the running
- code. A unit test whose purpose is unclear is not very helpful is this
+ code. A unit test whose purpose is unclear is not very helpful in this
case.
- Another use of the testing code is as an introduction to new developers. When
From fa307c21413efd115dd883d5c9c92c07f0b01f19 Mon Sep 17 00:00:00 2001
From: Mark
Date: Wed, 14 Jan 2015 02:31:36 +0100
Subject: [PATCH 051/760] Update cli.rst
Fixed Cliff's documentation link, as the ReadTheDocs one is not working.
---
docs/scenarios/cli.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst
index 96a191410..c8cdcec73 100644
--- a/docs/scenarios/cli.rst
+++ b/docs/scenarios/cli.rst
@@ -56,7 +56,7 @@ who choose to create a command-line interface because it is quick and simple.
Cliff
------
-`Cliff `_ is a framework for
+`Cliff `_ is a framework for
building command-line programs. It uses setuptools entry points to provide
subcommands, output formatters, and other extensions. The framework is meant
to be used to create multi-level commands such as subversion and git, where
From f5ee4e207a693ff409f83cb608215eb97979fe1e Mon Sep 17 00:00:00 2001
From: Sam Clift
Date: Wed, 14 Jan 2015 15:09:50 +0000
Subject: [PATCH 052/760] Improvements to the JSON section
Thanks to https://github.com/mplewis
---
docs/scenarios/json.rst | 107 +++++++++++-----------------------------
1 file changed, 30 insertions(+), 77 deletions(-)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index 3683eecfc..8a6e4928f 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -1,33 +1,39 @@
-JSON parsing
+JSON
===========
-json
------
+The `json `_ library can read JSON strings into a Python dictionary or array. It can also serialize Python dictionaries or arrays into JSON strings.
-`json `_ is a standard libary which can convert JSON to a Dictionay.
+* There are six basic types in JSON: objects, arrays, numbers, strings, booleans, and null.
+* The root element of JSON representation is an object, signified by ``{ ... }``. JSON objects are analogous to Python dictionaries: they have keys which correspond to values.
+* JSON does not use single quotes. JSON exclusively uses double quotes. Using single quotes in the place of double quotes is invalid JSON syntax.
-For example, a JSON string like this:
+Parsing JSON
+------------
+The `json `_ libary is imported like this:
.. code-block:: python
- "{'first_name':'Guido','last_name':'Rossum'}"
+ import json
-can be loaded like this:
+Take the following string containing JSON data:
+
+.. code-block:: python
+
+ json_string = '{"first_name": "Guido", "last_name":"Rossum"}'
+
+It can be manpulated like this:
.. code-block:: python
- import json
converted_dict = json.loads(json_string)
-you can now use it as a normal dictionary:
+and can now be used as a normal dictionary:
.. code-block:: python
converted_dict['first_name']
-As well as converting a JSON string to a dictionary. You can convert a dictionary to JSON
-
-For example, given:
+As well as converting a JSON string to a dictionary. You can convert a dictionary to JSON:
.. code-block:: python
@@ -36,25 +42,24 @@ For example, given:
'second_name': 'Rossum'
}
- import json
- print json.dumps(d)
+ print(json.dumps(d))
"{'first_name':'Guido','last_name':'Rossum'}"
-It is also possible to import JSON files:
+We can also load a JSON file by using ``json.load`` instead of ``json.loads``:
.. code-block:: python
- import json
with file('path/to/file.json') as json_file:
processed_json = json.load(json_file)
- print processsed_json
+
+ print(processsed_json)
{u'first_name': u'Guido', u'last_name': u'Rossum'}
-As well as write to them:
+
+Here's an example of writing directly to a file by using ``json.dump`` instead of ``json.dumps``:
.. code-block:: python
- import json
with file('path/to/file.json', 'w') as json_file:
dict = {
"first_name": "Guido",
@@ -65,74 +70,22 @@ As well as write to them:
simplejson
----------
-
-Installation
-
-.. code-block:: python
-
- pip install simplejson
-
`simplejson `_ is the externally maintained development version of the json library.
-simplejson is updated much more frequently than the Python. Meaning you can get updates much quicker.
-
-For example, a JSON string like this:
-
-.. code-block:: python
-
- "{'first_name':'Guido','last_name':'Rossum'}"
-
-can be loaded like this:
-
-.. code-block:: python
-
- import simplejson
- converted_dict = simplejson.loads(json_string)
-
-you can now use it as a normal dictionary:
-
-.. code-block:: python
-
- converted_dict['first_name']
-
-As well as converting a json string to dictionarys. You can convert dictionarys to json
+simplejson mimics the json standard library, so you can start using simplejson instead of json by importing it under a different name
-For example, given:
+Installation
.. code-block:: python
- import simplejson
-
- d = {
- 'first_name': 'Guido',
- 'second_name': 'Rossum'
- }
- print simplejson.dumps(d)
- "{'first_name':'Guido','last_name':'Rossum'}"
-
+ pip install simplejson
-It is also possible to import JSON files:
+Usage
.. code-block:: python
- import simplejson
-
- with file('path/to/file.json') as json_file:
- processed_json = simplejson.load(json_file)
- print processsed_json
- {u'first_name': u'Guido', u'last_name': u'Rossum'}
-
-As well as write to them:
-
-.. code-block:: python
+ import simplejson as json
- import simplejson
+simplejson is available so that developers that use an older version of python can use the latest features available in the json lib.
- with file('path/to/file.json', 'w') as json_file:
- dict = {
- "first_name": "Guido",
- "last_name": "Rossum",
- "middle_name": "Van"
- }
- simplejson.dump(dict, json_file)
From 332fdcd6f184bceb7037c1fa0933fe982dc1eae4 Mon Sep 17 00:00:00 2001
From: Sam Clift
Date: Wed, 14 Jan 2015 15:19:24 +0000
Subject: [PATCH 053/760] arrays to lists
---
docs/scenarios/json.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index 8a6e4928f..c5857310c 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -1,9 +1,9 @@
JSON
===========
-The `json `_ library can read JSON strings into a Python dictionary or array. It can also serialize Python dictionaries or arrays into JSON strings.
+The `json `_ library can read JSON strings into a Python dictionary or list. It can also serialize Python dictionaries or lists into JSON strings.
-* There are six basic types in JSON: objects, arrays, numbers, strings, booleans, and null.
+* There are six basic types in JSON: objects, lists, numbers, strings, booleans, and null.
* The root element of JSON representation is an object, signified by ``{ ... }``. JSON objects are analogous to Python dictionaries: they have keys which correspond to values.
* JSON does not use single quotes. JSON exclusively uses double quotes. Using single quotes in the place of double quotes is invalid JSON syntax.
From 7ff1d0006fa7f3b0204a10af14cc5141dc47fd47 Mon Sep 17 00:00:00 2001
From: Tanya Schlusser
Date: Sat, 17 Jan 2015 11:55:26 -0600
Subject: [PATCH 054/760] First attemt at a section on logging.
---
docs/writing/logging.rst | 180 +++++++++++++++++++++++++++++++++++++++
1 file changed, 180 insertions(+)
create mode 100644 docs/writing/logging.rst
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
new file mode 100644
index 000000000..e9e8bd169
--- /dev/null
+++ b/docs/writing/logging.rst
@@ -0,0 +1,180 @@
+Logging
+=======
+
+The :mod:`logging` module has been a part of Python's Standard Library since
+version 2.3. It is succinctly described in :pep:`282`. The documentation
+is notoriously hard to read, except for the `basic logging tutorial`_,
+and often less useful than simply reading the source code.
+
+Logging serves two purposes:
+
+- **Diagnostic logging** records events related to the application's
+ operation. If a user calls in to report an error, for example, the logs
+ can be searched for context.
+- **Audit logging** records events for business analysis. A user's
+ transactions can be extracted and combined with other user details for
+ reports or to optimize a business goal.
+
+
+... or Print Statements?
+------------------------
+
+The only time that ``print`` is a better option than logging is when
+the goal is to display a help statement for a command line application.
+Other reasons why logging is better than ``print``:
+
+- The `log record`_, which is created with every logging event, contains
+ readily available diagnostic information such as the file name,
+ full path, function, and line number of the logging event.
+- Events logged in included modules are automatically accessible via the
+ root logger
+ to your application's logging stream, unless you filter them out.
+- Logging can be selectively silenced or disabled by using the method
+ :meth:`logging.Logger.setLevel` or setting the attribute
+ :attr:`logging.Logger.disabled` to ``True``.
+
+
+Logging in a Library
+--------------------
+
+Notes for `configuring logging for a library`_ are in the
+`basic logging tutorial`_. Because the *user*, not the library, should
+dictate what happens when a logging event occurs, One admonition bears
+repeating:
+
+.. note::
+ It is strongly advised that you do not add any handlers other than
+ NullHandler to your library’s loggers.
+
+
+Best practice when instantiating loggers in a library is to only create them
+using the ``__name__`` global variable: the :mod:`logging` module creates a
+hierarchy of loggers using dot notation, so using ``__name__`` ensures
+no name collisions.
+
+Here is an example of best practice from the `requests source`_ -- place
+this in your ``__init__.py``
+
+.. code-block:: python
+
+ # Set default logging handler to avoid "No handler found" warnings.
+ import logging
+ try: # Python 2.7+
+ from logging import NullHandler
+ except ImportError:
+ class NullHandler(logging.Handler):
+ def emit(self, record):
+ pass
+
+ logging.getLogger(__name__).addHandler(NullHandler())
+
+
+
+Logging in an Application
+-------------------------
+
+The `twelve factor app's `_, an authoritative reference
+for good practice in application development, contains a section on
+`logging best practice `_. It emphatically
+advocates for treating log events as an event stream, and for
+sending that event stream to standard output to be handled by the
+application environment. Do that.
+
+
+There are at least three ways to configure a logger:
+
+- using a file (recommended)
+- using a dictionary
+- using code
+
+Here is how with a file -- let us say it is named ``logging_config.txt``:
+
+.. code-block:: none
+
+ [loggers]
+ keys=root
+
+ [handlers]
+ keys=stream_handler
+
+ [formatters]
+ keys=formatter
+
+ [logger_root]
+ level=DEBUG
+ handlers=stream_handler
+
+ [handler_stream_handler]
+ class=StreamHandler
+ level=DEBUG
+ formatter=formatter
+ args=(sys.stderr,)
+
+ [formatter_formatter]
+ format=%(asctime)s %(name)-12s %(levelname)-8s %(message)s
+
+
+Then use :meth:`logging.config.fileConfig` in the code:
+
+.. code-block:: python
+
+ import logging
+ from logging.config import fileConfig
+
+ fileConfig('logging_config.txt')
+ logger = logging.getLogger()
+ logger.debug('often makes a very good meal of %s', 'visiting tourists')
+
+
+..
+ As of Python 2.7, you can use a dictionary with configuration details:
+
+ .. code-block:: python
+
+ import logging
+ from logging.config import dictConfig
+
+ logging_config = dict(
+ version = 1,
+ formatters = {
+ 'f': {'format':
+ '%(asctime)s %(name)-12s %(levelname)-8s %(message)s'}
+ },
+ handlers = {
+ 'h': {'class': 'logging.StreamHandler',
+ 'formatter': 'f',
+ 'level': logging.DEBUG}
+ },
+ loggers = {
+ root : {'handlers': ['h'],
+ 'level': logging.DEBUG}
+ }
+ )
+
+ dictConfig(logging_config)
+
+ logger = logging.getLogger()
+ logger.debug('often makes a very good meal of %s', 'visiting tourists')
+
+
+ Or instantiate the logger directly in code:
+
+ .. code-block:: python
+
+ import logging
+
+ logger = logging.getLogger()
+ handler = logging.StreamHandler()
+ formatter = logging.Formatter(
+ '%(asctime)s %(name)-12s %(levelname)-8s %(message)s')
+ handler.setFormatter(formatter)
+ logger.addHandler(handler)
+ logger.setLevel(logging.DEBUG)
+
+ logger.debug('often makes a very good meal of %s', 'visiting tourists')
+
+
+.. _basic logging tutorial: http://docs.python.org/howto/logging.html#logging-basic-tutorial
+.. _configuring logging for a library: https://docs.python.org/howto/logging.html#configuring-logging-for-a-library
+.. _log record: https://docs.python.org/library/logging.html#logrecord-attributes
+.. _requests source: https://github.com/kennethreitz/requests
From 95ecb66c9631960624687f1c77d341d629113493 Mon Sep 17 00:00:00 2001
From: Tanya Schlusser
Date: Sat, 17 Jan 2015 11:56:16 -0600
Subject: [PATCH 055/760] Added the logging section after the testing section
in the Writing page
---
docs/contents.rst.inc | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index cc385325c..b312ee3e6 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -32,6 +32,7 @@ This part of the guide focuses on best practices for writing Python code.
writing/reading
writing/documentation
writing/tests
+ writing/logging
writing/gotchas
writing/license
From 7c37ec8396b2487cc1dc38b86fa78f9d361163e5 Mon Sep 17 00:00:00 2001
From: Tanya Schlusser
Date: Sat, 17 Jan 2015 20:59:53 -0600
Subject: [PATCH 056/760] Modified the new writing/logging.rst according to
comments on the initial pull request
---
docs/writing/logging.rst | 121 +++++++++++++++++++++------------------
1 file changed, 66 insertions(+), 55 deletions(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index e9e8bd169..e138ad995 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -3,8 +3,7 @@ Logging
The :mod:`logging` module has been a part of Python's Standard Library since
version 2.3. It is succinctly described in :pep:`282`. The documentation
-is notoriously hard to read, except for the `basic logging tutorial`_,
-and often less useful than simply reading the source code.
+is notoriously hard to read, except for the `basic logging tutorial`_.
Logging serves two purposes:
@@ -16,8 +15,8 @@ Logging serves two purposes:
reports or to optimize a business goal.
-... or Print Statements?
-------------------------
+... or Print?
+-------------
The only time that ``print`` is a better option than logging is when
the goal is to display a help statement for a command line application.
@@ -73,23 +72,28 @@ this in your ``__init__.py``
Logging in an Application
-------------------------
-The `twelve factor app's `_, an authoritative reference
+The `twelve factor app `_, an authoritative reference
for good practice in application development, contains a section on
`logging best practice `_. It emphatically
advocates for treating log events as an event stream, and for
sending that event stream to standard output to be handled by the
-application environment. Do that.
+application environment.
There are at least three ways to configure a logger:
-- using a file (recommended)
+- using a file
- using a dictionary
- using code
-Here is how with a file -- let us say it is named ``logging_config.txt``:
+Example Configuration via an INI File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. code-block:: none
+Let us say the file is named ``logging_config.ini``.
+More details for the file format are in the `logging configuration`_
+section of the `logging tutorial`_.
+
+.. code-block:: ini
[loggers]
keys=root
@@ -126,55 +130,62 @@ Then use :meth:`logging.config.fileConfig` in the code:
logger.debug('often makes a very good meal of %s', 'visiting tourists')
-..
- As of Python 2.7, you can use a dictionary with configuration details:
-
- .. code-block:: python
-
- import logging
- from logging.config import dictConfig
-
- logging_config = dict(
- version = 1,
- formatters = {
- 'f': {'format':
- '%(asctime)s %(name)-12s %(levelname)-8s %(message)s'}
- },
- handlers = {
- 'h': {'class': 'logging.StreamHandler',
- 'formatter': 'f',
- 'level': logging.DEBUG}
- },
- loggers = {
- root : {'handlers': ['h'],
- 'level': logging.DEBUG}
- }
- )
-
- dictConfig(logging_config)
-
- logger = logging.getLogger()
- logger.debug('often makes a very good meal of %s', 'visiting tourists')
-
-
- Or instantiate the logger directly in code:
-
- .. code-block:: python
-
- import logging
-
- logger = logging.getLogger()
- handler = logging.StreamHandler()
- formatter = logging.Formatter(
- '%(asctime)s %(name)-12s %(levelname)-8s %(message)s')
- handler.setFormatter(formatter)
- logger.addHandler(handler)
- logger.setLevel(logging.DEBUG)
-
- logger.debug('often makes a very good meal of %s', 'visiting tourists')
+Example Configuration via a Dictionary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As of Python 2.7, you can use a dictionary with configuration details.
+:pep:`319` contains a list of the mandatory and optional elements in
+the configuration dictionary.
+
+.. code-block:: python
+
+ import logging
+ from logging.config import dictConfig
+
+ logging_config = dict(
+ version = 1,
+ formatters = {
+ 'f': {'format':
+ '%(asctime)s %(name)-12s %(levelname)-8s %(message)s'}
+ },
+ handlers = {
+ 'h': {'class': 'logging.StreamHandler',
+ 'formatter': 'f',
+ 'level': logging.DEBUG}
+ },
+ loggers = {
+ root : {'handlers': ['h'],
+ 'level': logging.DEBUG}
+ }
+ )
+
+ dictConfig(logging_config)
+
+ logger = logging.getLogger()
+ logger.debug('often makes a very good meal of %s', 'visiting tourists')
+
+
+Example Configuration Directly in Code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+ import logging
+
+ logger = logging.getLogger()
+ handler = logging.StreamHandler()
+ formatter = logging.Formatter(
+ '%(asctime)s %(name)-12s %(levelname)-8s %(message)s')
+ handler.setFormatter(formatter)
+ logger.addHandler(handler)
+ logger.setLevel(logging.DEBUG)
+
+ logger.debug('often makes a very good meal of %s', 'visiting tourists')
.. _basic logging tutorial: http://docs.python.org/howto/logging.html#logging-basic-tutorial
+.. _logging configuration: https://docs.python.org/howto/logging.html#configuring-logging
+.. _logging tutorial: http://docs.python.org/howto/logging.html
.. _configuring logging for a library: https://docs.python.org/howto/logging.html#configuring-logging-for-a-library
.. _log record: https://docs.python.org/library/logging.html#logrecord-attributes
.. _requests source: https://github.com/kennethreitz/requests
From 1cfb637cb1babcc7f0ecb1d48b6f3bb4d093e3a5 Mon Sep 17 00:00:00 2001
From: Tanya Schlusser
Date: Sat, 17 Jan 2015 21:05:56 -0600
Subject: [PATCH 057/760] Removed a stray capitalization and improved the
grammar in the 'print' vs 'logging' section
---
docs/writing/logging.rst | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index e138ad995..7faa55363 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -28,8 +28,8 @@ Other reasons why logging is better than ``print``:
- Events logged in included modules are automatically accessible via the
root logger
to your application's logging stream, unless you filter them out.
-- Logging can be selectively silenced or disabled by using the method
- :meth:`logging.Logger.setLevel` or setting the attribute
+- Logging can be selectively silenced by using the method
+ :meth:`logging.Logger.setLevel` or disabled by setting the attribute
:attr:`logging.Logger.disabled` to ``True``.
@@ -37,8 +37,8 @@ Logging in a Library
--------------------
Notes for `configuring logging for a library`_ are in the
-`basic logging tutorial`_. Because the *user*, not the library, should
-dictate what happens when a logging event occurs, One admonition bears
+`logging tutorial`_. Because the *user*, not the library, should
+dictate what happens when a logging event occurs, one admonition bears
repeating:
.. note::
@@ -86,6 +86,7 @@ There are at least three ways to configure a logger:
- using a dictionary
- using code
+
Example Configuration via an INI File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
From 0c1551ae85940d9f75a79865356da02a72abad7b Mon Sep 17 00:00:00 2001
From: Tanya Schlusser
Date: Sat, 17 Jan 2015 21:09:52 -0600
Subject: [PATCH 058/760] Added pro / con bullets to the list of ways to
configure a logger
---
docs/writing/logging.rst | 17 ++++++++++++++---
1 file changed, 14 insertions(+), 3 deletions(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index 7faa55363..0cee15d1c 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -82,9 +82,20 @@ application environment.
There are at least three ways to configure a logger:
-- using a file
-- using a dictionary
-- using code
+- Using an INI-formatted file:
+ - *Pro* -- possible to update configuration while running
+ using the function :func:`logging.config.listen` to listen
+ on a socket.
+ - *Con* -- less control (*e.g.* custom subclassed filters or loggers)
+ than possible when configuring a logger in code.
+- Using a dictionary or a JSON-formatted file:
+ - *Pro* -- in addition to updating while running, it is possible to
+ load from a file using the :mod:`json` module, in the standard
+ library since Python 2.6.
+ - *Con* -- less control than when configuring a logger in code.
+- Using code:
+ - *Pro* -- complete control over the configuration.
+ - *Con* -- modifications require a change to source code.
Example Configuration via an INI File
From df7a22568bc4e944fd37a41ebf1f2740ff54976d Mon Sep 17 00:00:00 2001
From: Tanya Schlusser
Date: Sat, 17 Jan 2015 21:43:22 -0600
Subject: [PATCH 059/760] Italic pro/con to bold, and '--' to colon after the
pro/con
---
docs/writing/logging.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index 0cee15d1c..70e20de54 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -83,19 +83,19 @@ application environment.
There are at least three ways to configure a logger:
- Using an INI-formatted file:
- - *Pro* -- possible to update configuration while running
+ - **Pro**: possible to update configuration while running
using the function :func:`logging.config.listen` to listen
on a socket.
- - *Con* -- less control (*e.g.* custom subclassed filters or loggers)
+ - **Con**: less control (*e.g.* custom subclassed filters or loggers)
than possible when configuring a logger in code.
- Using a dictionary or a JSON-formatted file:
- - *Pro* -- in addition to updating while running, it is possible to
+ - **Pro**: in addition to updating while running, it is possible to
load from a file using the :mod:`json` module, in the standard
library since Python 2.6.
- - *Con* -- less control than when configuring a logger in code.
+ - **Con**: less control than when configuring a logger in code.
- Using code:
- - *Pro* -- complete control over the configuration.
- - *Con* -- modifications require a change to source code.
+ - **Pro**: complete control over the configuration.
+ - **Con**: modifications require a change to source code.
Example Configuration via an INI File
From 37ed5fc40a75b60d2d3cb9f4e8f11ce6a7f32d96 Mon Sep 17 00:00:00 2001
From: Sam Clift
Date: Sun, 18 Jan 2015 14:22:30 +0000
Subject: [PATCH 060/760] update based on PR feedback
---
docs/scenarios/json.rst | 59 +++++++----------------------------------
1 file changed, 10 insertions(+), 49 deletions(-)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index c5857310c..29d87c44f 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -1,15 +1,12 @@
JSON
-===========
+====
-The `json `_ library can read JSON strings into a Python dictionary or list. It can also serialize Python dictionaries or lists into JSON strings.
-
-* There are six basic types in JSON: objects, lists, numbers, strings, booleans, and null.
-* The root element of JSON representation is an object, signified by ``{ ... }``. JSON objects are analogous to Python dictionaries: they have keys which correspond to values.
-* JSON does not use single quotes. JSON exclusively uses double quotes. Using single quotes in the place of double quotes is invalid JSON syntax.
+The `json `_ library can parse JSON from strings or files. When parsing, the library converts the JSON into a Python dictionary or list. It can also parse Python dictionaries or lists into JSON strings.
Parsing JSON
------------
-The `json `_ libary is imported like this:
+
+The json libary is imported like this:
.. code-block:: python
@@ -21,7 +18,7 @@ Take the following string containing JSON data:
json_string = '{"first_name": "Guido", "last_name":"Rossum"}'
-It can be manpulated like this:
+It can be parsed like this:
.. code-block:: python
@@ -31,9 +28,10 @@ and can now be used as a normal dictionary:
.. code-block:: python
- converted_dict['first_name']
+ print(converted_dict['first_name'])
+ "Guido"
-As well as converting a JSON string to a dictionary. You can convert a dictionary to JSON:
+You can also convert a dictionary to JSON:
.. code-block:: python
@@ -45,47 +43,10 @@ As well as converting a JSON string to a dictionary. You can convert a dictionar
print(json.dumps(d))
"{'first_name':'Guido','last_name':'Rossum'}"
-We can also load a JSON file by using ``json.load`` instead of ``json.loads``:
-
-.. code-block:: python
-
- with file('path/to/file.json') as json_file:
- processed_json = json.load(json_file)
-
- print(processsed_json)
- {u'first_name': u'Guido', u'last_name': u'Rossum'}
-
-
-Here's an example of writing directly to a file by using ``json.dump`` instead of ``json.dumps``:
-
-.. code-block:: python
-
- with file('path/to/file.json', 'w') as json_file:
- dict = {
- "first_name": "Guido",
- "last_name": "Rossum",
- "middle_name": "Van"
- }
- json.dump(dict, json_file)
simplejson
----------
-`simplejson `_ is the externally maintained development version of the json library.
-
-simplejson mimics the json standard library, so you can start using simplejson instead of json by importing it under a different name
-
-Installation
-
-.. code-block:: python
-
- pip install simplejson
-
-Usage
-
-.. code-block:: python
-
- import simplejson as json
-
-simplejson is available so that developers that use an older version of python can use the latest features available in the json lib.
+`simplejson `_ is the externally maintained development version of the json library.
+simplejson mimics the json standard library, it is available so that developers that use an older version of python can use the latest features available in the json lib.
From f1e196a73f3cef46af504b4b5705a60327df6949 Mon Sep 17 00:00:00 2001
From: Ian Cordasco
Date: Sun, 18 Jan 2015 09:58:33 -0600
Subject: [PATCH 061/760] Commit last few necessary edits
These were all previously ignored in the last two pull requests.
---
docs/scenarios/json.rst | 18 +++++++-----------
1 file changed, 7 insertions(+), 11 deletions(-)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index 29d87c44f..a3f7ffa01 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -6,12 +6,6 @@ The `json `_ library can parse JSON
Parsing JSON
------------
-The json libary is imported like this:
-
-.. code-block:: python
-
- import json
-
Take the following string containing JSON data:
.. code-block:: python
@@ -22,26 +16,28 @@ It can be parsed like this:
.. code-block:: python
- converted_dict = json.loads(json_string)
+ import json
+ parsed_json = json.loads(json_string)
and can now be used as a normal dictionary:
.. code-block:: python
- print(converted_dict['first_name'])
+ print(parsed_json['first_name'])
"Guido"
-You can also convert a dictionary to JSON:
+You can also convert a the following to JSON:
.. code-block:: python
d = {
'first_name': 'Guido',
- 'second_name': 'Rossum'
+ 'second_name': 'Rossum',
+ 'titles': ['BDFL', 'Developer'],
}
print(json.dumps(d))
- "{'first_name':'Guido','last_name':'Rossum'}"
+ '{"first_name": "Guido", "last_name": "Rossum", "titles": ["BDFL", "Developer"]}'
simplejson
From 0f797099e1c99133d1d4db01c8aee9e4b707e0cb Mon Sep 17 00:00:00 2001
From: Ian Cordasco
Date: Sun, 18 Jan 2015 09:59:38 -0600
Subject: [PATCH 062/760] Change logging_config extension to ini
---
docs/writing/logging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index 70e20de54..4a36edbb0 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -137,7 +137,7 @@ Then use :meth:`logging.config.fileConfig` in the code:
import logging
from logging.config import fileConfig
- fileConfig('logging_config.txt')
+ fileConfig('logging_config.ini')
logger = logging.getLogger()
logger.debug('often makes a very good meal of %s', 'visiting tourists')
From 4fbc739be7131eae487e0e3dba0f3ac622e96e9d Mon Sep 17 00:00:00 2001
From: Matthew Lewis
Date: Thu, 5 Feb 2015 13:57:28 -0600
Subject: [PATCH 063/760] Add details on how to use simplejson
---
docs/scenarios/json.rst | 14 +++++++++++---
1 file changed, 11 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index a3f7ffa01..225ed2334 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -26,7 +26,7 @@ and can now be used as a normal dictionary:
print(parsed_json['first_name'])
"Guido"
-You can also convert a the following to JSON:
+You can also convert the following to JSON:
.. code-block:: python
@@ -43,6 +43,14 @@ You can also convert a the following to JSON:
simplejson
----------
-`simplejson `_ is the externally maintained development version of the json library.
+The JSON library was added to Python in version 2.6. If you're using an earlier version of Python, the `simplejson `_ library is available via PyPI.
-simplejson mimics the json standard library, it is available so that developers that use an older version of python can use the latest features available in the json lib.
+simplejson mimics the json standard library. It is available so that developers that use older versions of Python can use the latest features available in the json lib.
+
+You can start using simplejson when the json library is not available by importing simplejson under a different name:
+
+.. code-block:: python
+
+ import simplejson as json
+
+After importing simplejson as json, the above examples will all work as if you were using the standard json library.
From ecc570d1c421a1f6ea285dfeb202a037ce74b912 Mon Sep 17 00:00:00 2001
From: Matthew Lewis
Date: Thu, 5 Feb 2015 14:03:06 -0600
Subject: [PATCH 064/760] Improve wording of intro paragraph
---
docs/scenarios/json.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index 225ed2334..2ca49e8cc 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -1,7 +1,7 @@
JSON
====
-The `json `_ library can parse JSON from strings or files. When parsing, the library converts the JSON into a Python dictionary or list. It can also parse Python dictionaries or lists into JSON strings.
+The `json `_ library can parse JSON from strings or files. The library parses JSON into a Python dictionary or list. It can also convert Python dictionaries or lists into JSON strings.
Parsing JSON
------------
From 2e2d70ca9be42ae644d202fdf5c7673dae65c566 Mon Sep 17 00:00:00 2001
From: Matthew Lewis
Date: Thu, 5 Feb 2015 14:03:18 -0600
Subject: [PATCH 065/760] Add info on working with file objects
---
docs/scenarios/json.rst | 30 ++++++++++++++++++++++++++++++
1 file changed, 30 insertions(+)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index 2ca49e8cc..98a0292e1 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -39,6 +39,36 @@ You can also convert the following to JSON:
print(json.dumps(d))
'{"first_name": "Guido", "last_name": "Rossum", "titles": ["BDFL", "Developer"]}'
+Working with File Objects
+-------------------------
+
+We can also load a JSON file by using ``json.load`` instead of ``json.loads``:
+
+.. code-block:: python
+
+ import json
+
+ with file('path/to/file.json') as f:
+ loaded_json = json.load(f)
+
+ print(loaded_json) # {'first_name': 'Ada', 'last_name': 'Lovelace'}
+
+Here's an example of writing directly to a file by using ``json.dump`` instead of ``json.dumps``:
+
+.. code-block:: python
+
+ import json
+
+ my_data = {
+ 'name': 'Alan Turing',
+ 'played_by': 'Benedict Cumberbatch'
+ }
+
+ with file('path/to/file.json', 'w') as f:
+ json.dump(my_data, f)
+
+``path/to/file.json`` now contains a JSON representation of the my_data dictionary.
+
simplejson
----------
From 4ffb7ff3d8c700ff22160108b192a98d15e31a40 Mon Sep 17 00:00:00 2001
From: Michael Dunn
Date: Tue, 10 Feb 2015 17:15:18 -0500
Subject: [PATCH 066/760] Update logging.rst
The PEP referenced for configuring logging via - '319' should be '391'.
Just a simple fix.
---
docs/writing/logging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index 4a36edbb0..c280e8570 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -146,7 +146,7 @@ Example Configuration via a Dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As of Python 2.7, you can use a dictionary with configuration details.
-:pep:`319` contains a list of the mandatory and optional elements in
+:pep:`391` contains a list of the mandatory and optional elements in
the configuration dictionary.
.. code-block:: python
From 86d29a3c773ba1d6a344ea18d157a6d2c7f75051 Mon Sep 17 00:00:00 2001
From: Michael Dunn
Date: Tue, 10 Feb 2015 18:16:14 -0500
Subject: [PATCH 067/760] Update logging.rst
The name of a dictionary key `root` was not properly enclosed in quotes, which results in a syntax error when people copy this code.
Thanks!
---
docs/writing/logging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index c280e8570..46a4f341f 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -166,7 +166,7 @@ the configuration dictionary.
'level': logging.DEBUG}
},
loggers = {
- root : {'handlers': ['h'],
+ 'root' : {'handlers': ['h'],
'level': logging.DEBUG}
}
)
From 2b15ec8af2cc0965a89dc91c121212737793041d Mon Sep 17 00:00:00 2001
From: Michael Dunn
Date: Tue, 10 Feb 2015 21:06:36 -0500
Subject: [PATCH 068/760] Update logging.rst
Removed whitespace in violation of PEP 8 and aligned lines.
---
docs/writing/logging.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index 46a4f341f..7032ea0e2 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -166,8 +166,8 @@ the configuration dictionary.
'level': logging.DEBUG}
},
loggers = {
- 'root' : {'handlers': ['h'],
- 'level': logging.DEBUG}
+ 'root': {'handlers': ['h'],
+ 'level': logging.DEBUG}
}
)
From f6d503dd90f6782f55de4a4fdeb21fe82a53b643 Mon Sep 17 00:00:00 2001
From: Matthew Lewis
Date: Wed, 11 Feb 2015 15:18:04 -0600
Subject: [PATCH 069/760] Revert "Add info on working with file objects"
This reverts commit 2e2d70ca9be42ae644d202fdf5c7673dae65c566.
---
docs/scenarios/json.rst | 30 ------------------------------
1 file changed, 30 deletions(-)
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index 98a0292e1..2ca49e8cc 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -39,36 +39,6 @@ You can also convert the following to JSON:
print(json.dumps(d))
'{"first_name": "Guido", "last_name": "Rossum", "titles": ["BDFL", "Developer"]}'
-Working with File Objects
--------------------------
-
-We can also load a JSON file by using ``json.load`` instead of ``json.loads``:
-
-.. code-block:: python
-
- import json
-
- with file('path/to/file.json') as f:
- loaded_json = json.load(f)
-
- print(loaded_json) # {'first_name': 'Ada', 'last_name': 'Lovelace'}
-
-Here's an example of writing directly to a file by using ``json.dump`` instead of ``json.dumps``:
-
-.. code-block:: python
-
- import json
-
- my_data = {
- 'name': 'Alan Turing',
- 'played_by': 'Benedict Cumberbatch'
- }
-
- with file('path/to/file.json', 'w') as f:
- json.dump(my_data, f)
-
-``path/to/file.json`` now contains a JSON representation of the my_data dictionary.
-
simplejson
----------
From 938b9325fa9659a3d9b2af6e5ac6611f47fb8ca7 Mon Sep 17 00:00:00 2001
From: Tao Meng
Date: Thu, 12 Feb 2015 13:16:47 +0800
Subject: [PATCH 070/760] Update osx.rst
---
docs/starting/install/osx.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
index 56ad745b8..ac2b5f7d6 100644
--- a/docs/starting/install/osx.rst
+++ b/docs/starting/install/osx.rst
@@ -3,7 +3,7 @@
Installing Python on Mac OS X
=============================
-The latest version of Mac OS X, Mavericks, **comes with Python 2.7 out of the box**.
+The latest version of Mac OS X, Yosemite, **comes with Python 2.7 out of the box**.
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
From 4ad53a49165629b843e08bdfbf634feba5cbb63a Mon Sep 17 00:00:00 2001
From: Vishal Sodani
Date: Mon, 16 Feb 2015 12:48:55 +0530
Subject: [PATCH 071/760] Use virtualwrapper-win on windows
---
docs/dev/virtualenvs.rst | 9 ++++-----
1 file changed, 4 insertions(+), 5 deletions(-)
diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
index f68b3f5e7..73ff9eef9 100644
--- a/docs/dev/virtualenvs.rst
+++ b/docs/dev/virtualenvs.rst
@@ -132,16 +132,15 @@ To install (make sure **virtualenv** is already installed):
(`Full virtualenvwrapper install instructions `_.)
-For Windows, you can use the `virtualenvwrapper-powershell `_ clone.
+For Windows, you can use the `virtualenvwrapper-win `_.
To install (make sure **virtualenv** is already installed):
.. code-block:: console
- PS> pip install virtualenvwrapper-powershell
- PS> $env:WORKON_HOME="~/Envs"
- PS> mkdir $env:WORKON_HOME
- PS> import-module virtualenvwrapper
+ $ pip install virtualenvwrapper-win
+
+In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs
Basic Usage
~~~~~~~~~~~
From 9f8bda579e4197f1c6a41927705a263da126af03 Mon Sep 17 00:00:00 2001
From: "Saira J. Barlas"
Date: Wed, 25 Feb 2015 20:50:51 +0000
Subject: [PATCH 072/760] Python course for beginners
It really helped me as a beginner hence the recommendation. Also added an extra space (where necessary) in between each suggestion to make it more clear for other people who edit. Thanks!
---
docs/intro/learning.rst | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 4b9c4dcda..9f85981f4 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -51,6 +51,7 @@ as programs that can break them.
`Hacking Secret Ciphers with Python `_
+
Learn Python the Hard Way
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -78,6 +79,7 @@ experience programming in another language.
`Dive Into Python 3 `_
+
Think Python: How to Think Like a Computer Scientist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -115,6 +117,7 @@ More information about test driven development can be found at these resources:
`Test Driven Development `_
+
A Byte of Python
~~~~~~~~~~~~~~~~
@@ -125,6 +128,14 @@ previous programming experience.
`A Byte of Python for Python 3.x `_
+Learn to Program in Python with Codeacademy
+~~~~~~~~~~~~~~~~~~~~
+
+A Codeacademy course for the absolute Python beginner. This free and interactive course provides and teaches the basics (and beyond) of Python programming whilst testing the user's knowledge in between progress.
+
+ `Learn to Program in Python with Codeacademy `_
+
+
Advanced
--------
From 12dc0651fc0e6668ee1939a10380214cc8a22cf7 Mon Sep 17 00:00:00 2001
From: Vincent Zee
Date: Sat, 28 Feb 2015 21:25:07 +0100
Subject: [PATCH 073/760] Fix bad url.
---
CONTRIBUTING.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 481f3f63c..ca09a1fa0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ How to contribute
This guide is under heavy development. If you would like to contribute, please
see:
-http://docs.python-guide.org/en/latest/notes/contribute/
+http://python-guide.readthedocs.org/en/latest/notes/contribute.html
Style Guide
From d6c2c8d16d66e86a935b578143be973a350e192f Mon Sep 17 00:00:00 2001
From: Vincent Zee
Date: Sat, 28 Feb 2015 21:35:37 +0100
Subject: [PATCH 074/760] Fixed url to contribute page
---
docs/_templates/sidebarintro.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
index 216c94065..ecb9f39dd 100644
--- a/docs/_templates/sidebarintro.html
+++ b/docs/_templates/sidebarintro.html
@@ -23,7 +23,7 @@ Contributors
This guide is the result of the collaboration of
135+ people
around the world, and your contributions
- are welcome!
+ are welcome!
From 5aac29d245f8693bdb8ce5074866ceb2d60f12c3 Mon Sep 17 00:00:00 2001
From: Vincent Zee
Date: Sat, 28 Feb 2015 22:23:07 +0100
Subject: [PATCH 075/760] Fixed the urls pointing to contribute and fixed some
lines that were longer than 78 characters.
---
CONTRIBUTING.md | 2 +-
docs/_templates/sidebarintro.html | 2 +-
docs/writing/documentation.rst | 11 ++++++-----
docs/writing/gotchas.rst | 16 +++++++++-------
docs/writing/license.rst | 5 +++--
5 files changed, 20 insertions(+), 16 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ca09a1fa0..0035989a7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ How to contribute
This guide is under heavy development. If you would like to contribute, please
see:
-http://python-guide.readthedocs.org/en/latest/notes/contribute.html
+http://docs.python-guide.org/en/latest/notes/contribute.html
Style Guide
diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
index ecb9f39dd..0bfc69a02 100644
--- a/docs/_templates/sidebarintro.html
+++ b/docs/_templates/sidebarintro.html
@@ -23,7 +23,7 @@ Contributors
This guide is the result of the collaboration of
135+ people
around the world, and your contributions
- are welcome!
+ are welcome!
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
index 0aeb77b86..85f48de42 100644
--- a/docs/writing/documentation.rst
+++ b/docs/writing/documentation.rst
@@ -40,12 +40,12 @@ of the following components:
done with the product, using one or two extremely simplified use
cases. This is the thirty-second pitch for your project.
-- A *tutorial* should show some primary use cases in more detail. The reader will
- follow a step-by-step procedure to set-up a working prototype.
+- A *tutorial* should show some primary use cases in more detail. The reader
+ will follow a step-by-step procedure to set-up a working prototype.
- An *API reference* is typically generated from the code (see
- :ref:`docstrings `). It will list all publicly available interfaces,
- parameters, and return values.
+ :ref:`docstrings `). It will list all publicly available
+ interfaces, parameters, and return values.
- *Developer documentation* is intended for potential contributors. This can
include code convention and general design strategy of the project.
@@ -107,7 +107,8 @@ In Python, *docstrings* describe modules, classes, and functions:
"""Returns the square root of self times self."""
...
-In general, follow the comment section of :pep:`8#comments` (the "Python Style Guide").
+In general, follow the comment section of :pep:`8#comments` (the "Python Style
+Guide").
Commenting Sections of Code
~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst
index a59eb9b2e..b12fbd5f1 100644
--- a/docs/writing/gotchas.rst
+++ b/docs/writing/gotchas.rst
@@ -6,9 +6,10 @@ avoids surprises. However, there are a few cases that can be confusing to
newcomers.
Some of these cases are intentional but can be potentially surprising. Some
-could arguably be considered language warts. In general though, what follows is a collection
-of potentially tricky behavior that might seem strange at first glance, but is
-generally sensible once you're aware of the underlying cause for the surprise.
+could arguably be considered language warts. In general though, what follows
+is a collection of potentially tricky behavior that might seem strange at first
+glance, but is generally sensible once you're aware of the underlying cause for
+the surprise.
.. _default_args:
@@ -139,7 +140,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``:
+and in fact the same exact behavior is exhibited by just using an ordinary
+``def``:
.. code-block:: python
@@ -179,6 +181,6 @@ Alternatively, you can use the functools.partial function:
When the Gotcha Isn't a Gotcha
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Sometimes you want your closures to behave this way. Late binding is good in lots of
-situations. Looping to create unique functions is unfortunately a case where
-they can cause hiccups.
+Sometimes you want your closures to behave this way. Late binding is good in
+lots of situations. Looping to create unique functions is unfortunately a case
+where they can cause hiccups.
diff --git a/docs/writing/license.rst b/docs/writing/license.rst
index 60099ea01..0a5256b69 100644
--- a/docs/writing/license.rst
+++ b/docs/writing/license.rst
@@ -48,5 +48,6 @@ To help you choose one for your project, there's a `license chooser `_.
-
+A good overview of licenses with explanations of what one can, cannot,
+and must do using a particular software can be found at
+`tl;drLegal `_.
From 7e385158c760281421c316efdcbe56e458a639b3 Mon Sep 17 00:00:00 2001
From: Vincent Zee
Date: Sun, 1 Mar 2015 00:17:23 +0100
Subject: [PATCH 076/760] Corrected lines to be no longer than 78 characters
---
docs/dev/env.rst | 87 +++++++++-------
docs/dev/virtualenvs.rst | 17 ++--
docs/intro/duction.rst | 3 +-
docs/intro/learning.rst | 73 +++++++-------
docs/intro/news.rst | 8 +-
docs/scenarios/admin.rst | 99 ++++++++++---------
docs/scenarios/ci.rst | 18 ++--
docs/scenarios/client.rst | 9 +-
docs/scenarios/crypto.rst | 6 +-
docs/scenarios/db.rst | 34 ++++---
docs/scenarios/gui.rst | 11 ++-
docs/scenarios/imaging.rst | 12 ++-
docs/scenarios/json.rst | 19 +++-
docs/scenarios/network.rst | 8 +-
docs/scenarios/scientific.rst | 18 ++--
docs/scenarios/scrape.rst | 7 +-
docs/scenarios/web.rst | 45 +++++----
docs/shipping/packaging.rst | 35 ++++---
docs/starting/pip-virtualenv.rst | 88 +++++++++--------
docs/writing/license.rst | 7 +-
docs/writing/logging.rst | 20 ++--
docs/writing/structure.rst | 145 ++++++++++++++-------------
docs/writing/style.rst | 164 ++++++++++++++++---------------
docs/writing/tests.rst | 10 +-
24 files changed, 504 insertions(+), 439 deletions(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index 37673e4fe..0503e9010 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -29,31 +29,33 @@ following lines::
With these settings, newlines are inserted after 79 characters and indentation
is set to 4 spaces per tab. If you also use Vim for other languages, there is a
-handy plugin called indent_, which handles indentation settings for Python source
-files.
+handy plugin called indent_, which handles indentation settings for Python
+source files.
-There is also a handy syntax plugin called syntax_ featuring some improvements over
-the syntax file included in Vim 6.1.
+There is also a handy syntax plugin called syntax_ featuring some improvements
+over 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 :option:`+python` you can also utilize some very handy
-plugins to do these checks from within the editor.
+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
-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 :file:`.vimrc`::
+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
+:file:`.vimrc`::
autocmd BufWritePost *.py call Pyflakes()
autocmd BufWritePost *.py call Pep8()
If you are already using syntastic_, you can set 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::
set statusline+=%#warningmsg#
set statusline+=%{SyntasticStatuslineFlag()}
@@ -112,8 +114,8 @@ TextMate
--------
`TextMate `_ brings Apple's approach to operating
- systems into the world of text editors. By bridging UNIX underpinnings and GUI,
- TextMate cherry-picks the best of both worlds to the benefit of expert
+ systems into the world of text editors. By bridging UNIX underpinnings and
+ GUI, TextMate cherry-picks the best of both worlds to the benefit of expert
scripters and novice users alike.
Sublime Text
@@ -124,18 +126,21 @@ Sublime Text
extraordinary features and amazing performance.
Sublime Text has excellent support for editing Python code and uses Python for
-its plugin API. It also has a diverse variety of plugins, `some of which `_
-allow for in-editor PEP8 checking and code "linting".
+its plugin API. It also has a diverse variety of plugins,
+`some of which `_ allow for
+in-editor PEP8 checking and code "linting".
Atom
----
`Atom `_ is a hackable text editor for the 21st century,
- built on atom-shell, and based on everything we love about our favorite editors.
+ built on atom-shell, and based on everything we love about our favorite
+ editors.
-Atom is web native (HTML, CSS, JS), focusing on modular design and easy plugin development.
-It comes with native package control and plethora of packages. Recommended for Python
-development is `Linter `_ combined with
+Atom is web native (HTML, CSS, JS), focusing on modular design and easy plugin
+development. It comes with native package control and plethora of packages.
+Recommended for Python development is
+`Linter `_ combined with
`linter-flake8 `_.
@@ -147,9 +152,10 @@ PyCharm / IntelliJ IDEA
`PyCharm `_ is developed by JetBrains, also
known for IntelliJ IDEA. Both share the same code base and most of PyCharm's
-features can be brought to IntelliJ with the free `Python Plug-In `_.
-There are two versions of PyCharm: Professional Edition (Free 30-day trial)
-and Community Edition(Apache 2.0 License) with fewer features.
+features can be brought to IntelliJ with the free
+`Python Plug-In `_. There are two
+versions of PyCharm: Professional Edition (Free 30-day trial) and Community
+Edition(Apache 2.0 License) with fewer features.
Eclipse
@@ -172,9 +178,10 @@ Spyder
------
`Spyder `_ is an IDE specifically geared
-toward working with scientific Python libraries (namely `Scipy `_).
-It includes integration with pyflakes_, `pylint `_
-and `rope `_.
+toward working with scientific Python libraries (namely
+`Scipy `_). It includes integration with pyflakes_,
+`pylint `_ and
+`rope `_.
Spyder is open-source (free), offers code completion, syntax highlighting,
a class and function browser, and object inspection.
@@ -195,11 +202,13 @@ NINJA-IDE
`NINJA-IDE `_ (from the recursive acronym: "Ninja-IDE
Is Not Just Another IDE") is a cross-platform IDE, specially designed to build
-Python applications, and runs on Linux/X11, Mac OS X and Windows desktop operating
-systems. Installers for these platforms can be downloaded from the website.
+Python applications, and runs on Linux/X11, Mac OS X and Windows desktop
+operating systems. Installers for these platforms can be downloaded from the
+website.
-NINJA-IDE is open-source software (GPLv3 licence) and is developed in Python and
-Qt. The source files can be downloaded from `GitHub `_.
+NINJA-IDE is open-source software (GPLv3 licence) and is developed
+in Python and Qt. The source files can be downloaded from
+`GitHub `_.
Eric (The Eric Python IDE)
@@ -210,8 +219,8 @@ offering sourcecode autocompletion, syntax highlighting, support for version
control systems, python 3 support, integrated web browser, python shell,
integrated debugger and a flexible plug-in system. Written in python, it is
based on the Qt gui toolkit, integrating the Scintilla editor control. Eric
-is an open-source software project (GPLv3 licence) with more than ten years of active
-development.
+is an open-source software project (GPLv3 licence) with more than ten years of
+active development.
Interpreter Tools
@@ -221,15 +230,16 @@ Interpreter Tools
Virtual Environments
--------------------
-A Virtual Environment 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.
+A Virtual Environment 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.
For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.
-To start using and see more information: `Virtual Environments `_ docs.
+To start using and see more information:
+`Virtual Environments `_ docs.
Other Tools
:::::::::::
@@ -273,7 +283,8 @@ BPython
-------
`bpython `_ is an alternative interface to the
-Python interpreter for Unix-like operating systems. It has the following features:
+Python interpreter for Unix-like operating systems. It has the following
+features:
* In-line syntax highlighting.
* Readline-like autocomplete with suggestions displayed as you type.
diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
index 73ff9eef9..8c3403591 100644
--- a/docs/dev/virtualenvs.rst
+++ b/docs/dev/virtualenvs.rst
@@ -1,10 +1,10 @@
Virtual Environments
====================
-A Virtual Environment 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.
+A Virtual Environment 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.
For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.
@@ -32,10 +32,11 @@ Basic Usage
$ cd my_project_folder
$ 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`` 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.
+``virtualenv venv`` will create a folder in the current directory which will
+contain the Python executable files, and a copy of the ``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.
This creates a copy of Python in whichever directory you ran the command in,
placing it in a folder named :file:`venv`.
diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst
index 935839055..5930d7f64 100644
--- a/docs/intro/duction.rst
+++ b/docs/intro/duction.rst
@@ -84,4 +84,5 @@ first-time Pythonista, and the authors to the Guide will gladly help if you
have any questions about the appropriateness, completeness, or accuracy of
a contribution.
-To get started working on The Hitchhiker's Guide, see the :doc:`/notes/contribute` page.
+To get started working on The Hitchhiker's Guide,
+see the :doc:`/notes/contribute` page.
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 4b9c4dcda..d8de701e5 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -7,9 +7,9 @@ Beginner
The Python Tutorial
~~~~~~~~~~~~~~~~~~~~
-This is the official tutorial. It covers all the basics, and offers a tour of the
-language and the standard library. Recommended for those who need a quickstart
-guide to the language.
+This is the official tutorial. It covers all the basics, and offers a tour of
+the language and the standard library. Recommended for those who need a
+quickstart guide to the language.
`The Python Tutorial `_
@@ -18,15 +18,16 @@ Learn Python Interactive Tutorial
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Learnpython.org is an easy non-intimidating way to get introduced to Python.
-The website takes the same approach used on the popular `Try Ruby `_
-website, it has an interactive Python interpreter built into the site that
-allows you to go through the lessons without having to install Python locally.
+The website takes the same approach used on the popular
+`Try Ruby `_ website, it has an interactive Python
+interpreter built into the site that allows you to go through the lessons
+without having to install Python locally.
`Learn Python `_
-If you want a more traditional book, *Python For You and Me* is an
-excellent resource for learning all aspects of the language.
+If you want a more traditional book, *Python For You and Me* is an excellent
+resource for learning all aspects of the language.
`Python for You and Me `_
@@ -118,8 +119,8 @@ More information about test driven development can be found at these resources:
A Byte of Python
~~~~~~~~~~~~~~~~
-A free introductory book that teaches Python at the beginner level, it assumes no
-previous programming experience.
+A free introductory book that teaches Python at the beginner level, it assumes
+no previous programming experience.
`A Byte of Python for Python 2.x `_
`A Byte of Python for Python 3.x `_
@@ -131,8 +132,9 @@ Advanced
Pro Python
~~~~~~~~~~
-This book is for intermediate to advanced Python programmers who are looking to understand how
-and why Python works the way it does and how they can take their code to the next level.
+This book is for intermediate to advanced Python programmers who are looking to
+understand how and why Python works the way it does and how they can take their
+code to the next level.
`Pro Python `_
@@ -158,8 +160,8 @@ A Guide to Python's Magic Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a collection of blog posts by Rafe Kettler which explain 'magic methods'
-in Python. Magic methods are surrounded by double underscores (i.e. __init__) and
-can make classes and objects behave in different and magical ways.
+in Python. Magic methods are surrounded by double underscores (i.e. __init__)
+and can make classes and objects behave in different and magical ways.
`A Guide to Python's Magic Methods `_
@@ -170,17 +172,17 @@ For Engineers and Scientists
A Primer on Scientific Programming with Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A Primer on Scientific Programming with Python, written by Hans Petter Langtangen,
-mainly covers Python's usage in the scientific field. In the book, examples are
-chosen from mathematics and the natural sciences.
+A Primer on Scientific Programming with Python, written by Hans Petter
+Langtangen, mainly covers Python's usage in the scientific field. In the book,
+examples are chosen from mathematics and the natural sciences.
`A Primer on Scientific Programming with Python `_
Numerical Methods in Engineering with Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, puts the
-emphasis on numerical methods and how to implement them in Python.
+Numerical Methods in Engineering with Python, written by Jaan Kiusalaas,
+puts the emphasis on numerical methods and how to implement them in Python.
`Numerical Methods in Engineering with Python `_
@@ -190,9 +192,9 @@ Miscellaneous topics
Problem Solving with Algorithms and Data Structures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Problem Solving with Algorithms and Data Structures covers a range of data structures and
-algorithms. All concepts are illustrated with Python code along with interactive samples
-that can be run directly in the browser.
+Problem Solving with Algorithms and Data Structures covers a range of data
+structures and algorithms. All concepts are illustrated with Python code along
+with interactive samples that can be run directly in the browser.
`Problem Solving with Algorithms and Data Structures
`_
@@ -200,9 +202,10 @@ that can be run directly in the browser.
Programming Collective Intelligence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Programming Collective Intelligence introduces a wide array of basic machine learning and
-data mining methods. The exposition is not very mathematically formal, but rather focuses
-on explaining the underlying intuition and shows how to implement the algorithms in Python.
+Programming Collective Intelligence introduces a wide array of basic machine
+learning and data mining methods. The exposition is not very mathematically
+formal, but rather focuses on explaining the underlying intuition and shows
+how to implement the algorithms in Python.
`Programming Collective Intelligence `_
@@ -221,17 +224,17 @@ as writing C extensions.
The Python Language Reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This is Python's reference manual, it covers the syntax and the core semantics of the
-language.
+This is Python's reference manual, it covers the syntax and the core semantics
+of the language.
`The Python Language Reference `_
Python Pocket Reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Python Pocket Reference, written by Mark Lutz, is an easy to use reference to the
-core language, with descriptions of commonly used modules and toolkits. It covers
-Python 3 and 2.6 versions.
+Python Pocket Reference, written by Mark Lutz, is an easy to use reference to
+the core language, with descriptions of commonly used modules and toolkits. It
+covers Python 3 and 2.6 versions.
`Python Pocket Reference `_
@@ -248,11 +251,11 @@ Writing Idiomatic Python
~~~~~~~~~~~~~~~~~~~~~~~~
"Writing Idiomatic Python", written by Jeff Knupp, contains the most common and
-important Python idioms in a format that maximizes identification and understanding.
-Each idiom is presented as a recommendation of a way to write some commonly
-used piece of code, followed by an explanation of why the idiom is important.
-It also contains two code samples for each idiom: the "Harmful" way to write it
-and the "Idiomatic" way.
+important Python idioms in a format that maximizes identification and
+understanding. Each idiom is presented as a recommendation of a way to write
+some commonly used piece of code, followed by an explanation of why the idiom
+is important. It also contains two code samples for each idiom: the "Harmful"
+way to write it and the "Idiomatic" way.
`For Python 2.7.3+ `_
diff --git a/docs/intro/news.rst b/docs/intro/news.rst
index b44e7da5a..b48e8bd11 100644
--- a/docs/intro/news.rst
+++ b/docs/intro/news.rst
@@ -35,15 +35,15 @@ new releases, jobs, etc. related to Python.
Python News
~~~~~~~~~~~~~
-Python News is the news section in the official Python web site (www.python.org). It briefly
-highlights the news from the Python community.
+Python News is the news section in the official Python web site
+(www.python.org). It briefly highlights the news from the Python community.
`Python News `_
Import Python Weekly
~~~~~~~~~~~~~~~~
-Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets delivered in your inbox.
-Keep Your Python Programming Skills Updated.
+Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets
+delivered in your inbox. Keep Your Python Programming Skills Updated.
`Import Python Weekly Newsletter `_
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
index af11cdf47..172e1289d 100644
--- a/docs/scenarios/admin.rst
+++ b/docs/scenarios/admin.rst
@@ -38,8 +38,8 @@ server.
run('git pull')
run('touch app.wsgi')
-With the previous code saved in a file named :file:`fabfile.py`, we can check memory
-usage with:
+With the previous code saved in a file named :file:`fabfile.py`, we can check
+memory usage with:
.. code-block:: console
@@ -72,10 +72,10 @@ programs, and host grouping.
Salt
----
-`Salt `_ is an open source infrastructure management tool.
-It supports remote command execution from a central point (master host) to multiple
-hosts (minions). It also supports system states which can be used to configure
-multiple servers using simple template files.
+`Salt `_ is an open source infrastructure management
+tool. It supports remote command execution from a central point (master host)
+to multiple 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:
@@ -83,8 +83,9 @@ Salt supports Python versions 2.6 and 2.7 and can be installed via pip:
$ pip install salt
-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.
+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.
@@ -92,21 +93,24 @@ The following command lists all available minion hosts, using the ping module.
$ salt '*' test.ping
-The host filtering is accomplished by matching the minion id, or using the grains system.
-The `grains `_ system
-uses static host information like the operating system version or the CPU architecture to
-provide a host taxonomy for the Salt modules.
+The host filtering is accomplished by matching the minion id,
+or using the grains system. The
+`grains `_
+system uses static host information like the operating system version or the
+CPU architecture to provide a host taxonomy for the Salt modules.
-The following command lists all available minions running CentOS using the grains system:
+The following command lists all available minions running CentOS using the
+grains system:
.. code-block:: console
$ salt -G 'os:CentOS' test.ping
-Salt also provides a state system. States can be used to configure the minion hosts.
+Salt also provides a state system. States can be used to configure the minion
+hosts.
-For example, when a minion host is ordered to read the following state file, it will install
-and start the Apache server:
+For example, when a minion host is ordered to read the following state file,
+it will install and start the Apache server:
.. code-block:: yaml
@@ -241,28 +245,29 @@ Puppet
------
`Puppet `_ is IT Automation and configuration management
-software from Puppet Labs that allows System Administrators to define the state of
-their IT Infrastructure, thereby providing an elegant way to manage their fleet of
-physical and virtual machines.
-
-Puppet is available both as an Open Source and an Enterprise variant. Modules are
-small, shareable units of code written to automate or define the state of a system.
-`Puppet Forge `_ is a repository for modules written
-by the community for Open Source and Enterprise Puppet.
-
-Puppet Agents are installed on nodes whose state needs to be monitored or changed.
-A desginated server known as the Puppet Master is responsible for orchastrating the
-agent nodes.
-
-Agent nodes send basic facts about the system such as to the operating system, kernel,
-architecture, ip address, hostname etc. to the Puppet Master.
-The Puppet Master then compiles a catalog with information provided by the agents on
-how each node should be configured and sends it to the agent. The agent enforces the
-change as prescribed in the catalog and sends a report back to the Puppet Master.
-
-Facter is an interesting tool that ships with Puppet that pulls basic facts about
-the system. These facts can be referenced as a variable while writing your
-Puppet modules.
+software from Puppet Labs that allows System Administrators to define the state
+of their IT Infrastructure, thereby providing an elegant way to manage their
+fleet of physical and virtual machines.
+
+Puppet is available both as an Open Source and an Enterprise variant. Modules
+are small, shareable units of code written to automate or define the state of a
+system. `Puppet Forge `_ is a repository for
+modules written by the community for Open Source and Enterprise Puppet.
+
+Puppet Agents are installed on nodes whose state needs to be monitored or
+changed. A desginated server known as the Puppet Master is responsible for
+orchastrating the agent nodes.
+
+Agent nodes send basic facts about the system such as to the operating system,
+kernel, architecture, ip address, hostname etc. to the Puppet Master.
+The Puppet Master then compiles a catalog with information provided by the
+agents on how each node should be configured and sends it to the agent. The
+agent enforces the change as prescribed in the catalog and sends a report back
+to the Puppet Master.
+
+Facter is an interesting tool that ships with Puppet that pulls basic facts
+about the system. These facts can be referenced as a variable while writing
+your Puppet modules.
.. code-block:: console
@@ -273,8 +278,8 @@ Puppet modules.
$ facter operatingsystem
Ubuntu
-Writing Modules in Puppet is pretty straight forward. Puppet Manifests together form
-Puppet Modules. Puppet manifest end with an extension of ``.pp``.
+Writing Modules in Puppet is pretty straight forward. Puppet Manifests together
+form Puppet Modules. Puppet manifest end with an extension of ``.pp``.
Here is an example of 'Hello World' in Puppet.
.. code-block:: puppet
@@ -285,9 +290,10 @@ Here is an example of 'Hello World' in Puppet.
#the notification message by default.
}
-Here is another example with system based logic. Note how the operatingsystem fact
-is being used as a variable prepended with the ``$`` sign. Similarly, this holds true
-for other facts such as hostname which can be referenced by ``$hostname``
+Here is another example with system based logic. Note how the operatingsystem
+fact is being used as a variable prepended with the ``$`` sign. Similarly, this
+holds true for other facts such as hostname which can be referenced by
+``$hostname``
.. code-block:: puppet
@@ -298,9 +304,10 @@ for other facts such as hostname which can be referenced by ``$hostname``
},
}
-There are several resource types for Puppet but the package-file-service paradigm is all
-you need for undertaking majority of the configuration management. The following Puppet code makes sure
-that the OpenSSH-Server package is installed in a system and the sshd service is notified to restart
+There are several resource types for Puppet but the package-file-service
+paradigm is all you need for undertaking majority of the configuration
+management. The following Puppet code makes sure that the OpenSSH-Server
+package is installed in a system and the sshd service is notified to restart
everytime the sshd configuration file is changed.
.. code-block:: puppet
diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst
index 7923c8ebf..43b422094 100644
--- a/docs/scenarios/ci.rst
+++ b/docs/scenarios/ci.rst
@@ -62,15 +62,15 @@ which provides the following features:
Travis-CI
---------
-`Travis-CI `_ is a distributed CI server which builds tests
-for open source projects for free. It provides multiple workers to run Python tests
-on and seamlessly integrates with GitHub. You can even have it comment on your Pull
-Requests whether this particular changeset breaks the build or not. So if you are
-hosting your code on GitHub, travis-ci is a great and easy way to get started with
-Continuous Integration.
-
-In order to get started, add a :file:`.travis.yml` file to your repository with this
-example content::
+`Travis-CI `_ is a distributed CI server which builds
+tests for open source projects for free. It provides multiple workers to run
+Python tests on and seamlessly integrates with GitHub. You can even have it
+comment on your Pull Requests whether this particular changeset breaks the
+build or not. So if you are hosting your code on GitHub, travis-ci is a great
+and easy way to get started with Continuous Integration.
+
+In order to get started, add a :file:`.travis.yml` file to your repository with
+this example content::
language: python
python:
diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst
index d589a47c9..2dc7748cd 100644
--- a/docs/scenarios/client.rst
+++ b/docs/scenarios/client.rst
@@ -45,10 +45,11 @@ library is designed to have a familiar socket-style API.
RabbitMQ
--------
-RabbitMQ is an open source message broker software that implements the Advanced Message Queuing Protocol (AMQP).
-The RabbitMQ server is written in the Erlang programming language and is built on the Open Telecom Platform
-framework for clustering and failover. Client libraries to interface with the broker are available
-for all major programming languages.
+RabbitMQ is an open source message broker software that implements the Advanced
+Message Queuing Protocol (AMQP). The RabbitMQ server is written in the Erlang
+programming language and is built on the Open Telecom Platform framework for
+clustering and failover. Client libraries to interface with the broker are
+available for all major programming languages.
- `Homepage `_
- `GitHub Organization `_
diff --git a/docs/scenarios/crypto.rst b/docs/scenarios/crypto.rst
index 15f3af798..94bd58d11 100644
--- a/docs/scenarios/crypto.rst
+++ b/docs/scenarios/crypto.rst
@@ -9,9 +9,9 @@ library that provides cryptographic recipes and primitives. It supports
Python 2.6-2.7, Python 3.2+ and PyPy.
-Cryptography is divided into two layers of recipes and hazardous materials (hazmat).
-The recipes layer provides simple API for proper symmetric encryption and the
-hazmat layer provides low-level cryptographic primitives.
+Cryptography is divided into two layers of recipes and hazardous materials
+(hazmat). The recipes layer provides simple API for proper symmetric
+encryption and the hazmat layer provides low-level cryptographic primitives.
diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst
index feda08f04..c89f02d81 100644
--- a/docs/scenarios/db.rst
+++ b/docs/scenarios/db.rst
@@ -30,39 +30,47 @@ Django ORM
The Django ORM is the interface used by `Django `_
to provide database access.
-It's based on the idea of `models `_,
+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 attribute of the model represents a database field.
-- Django gives you an automatically-generated database-access API; see `Making queries `__.
+- Django gives you an automatically-generated database-access API; see
+ `Making queries `__.
peewee
------
-`peewee `_ is another ORM with a focus on being lightweight with support for
-Python 2.6+ and 3.2+ which supports SQLite, MySQL and Postgres by default. The `model layer `_
-is similar to that of the Django ORM and it has `SQL-like methods `_
-to query data. While SQLite, MySQL and Postgres are supported out-of-the-box, there is a `collection of add-ons `_
+`peewee `_ is another ORM with a focus
+on being lightweight with support for Python 2.6+ and 3.2+ which supports
+SQLite, MySQL and Postgres by default. The
+`model layer `_
+is similar to that of the Django ORM and it has
+`SQL-like methods `_
+to query data. While SQLite, MySQL and Postgres are supported out-of-the-box,
+there is a `collection of add-ons `_
available.
PonyORM
-------
-`PonyORM `_ is an ORM that takes a different approach to querying the database. Instead of writing
-an SQL-like language or boolean expressions, Python's generator syntax is used. There's also an graphical schema editor
-that can generate PonyORM entities for you. It supports Python 2.6+ and Python 3.3+ and can connect to SQLite, MySQL,
-Postgres & Oracle
+`PonyORM `_ is an ORM that takes a different approach to
+querying the database. Instead of writing an SQL-like language or boolean
+expressions, Python's generator syntax is used. There's also an graphical
+schema editor that can generate PonyORM entities for you. It supports Python
+2.6+ and Python 3.3+ and can connect to SQLite, MySQL, Postgres & Oracle
SQLObject
---------
-`SQLObject `_ is yet another ORM. It supports a wide variety of databases: Common database systems
-MySQL, Postgres and SQLite and more exotic systems like SAP DB, SyBase and MSSQL. It only supports Python 2 from
-Python 2.6 upwards.
+`SQLObject `_ is yet another ORM. It supports a wide
+variety of databases: Common database systems MySQL, Postgres and SQLite and
+more exotic systems like SAP DB, SyBase and MSSQL. It only supports Python 2
+from Python 2.6 upwards.
.. There's no official information on this on their page, this information was gathered by looking at their source code
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index 7c3c6346a..05901fda2 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -22,8 +22,8 @@ GTk
PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library
itself, it is currently licensed under the GNU LGPL. It is worth noting that
PyGTK only currently supports the Gtk-2.X API (NOT Gtk-3.0). It is currently
-recommended that PyGTK not be used for new projects and that existing applications
-be ported from PyGTK to PyGObject.
+recommended that PyGTK not be used for new projects and that existing
+applications be ported from PyGTK to PyGObject.
Kivy
----
@@ -33,7 +33,8 @@ 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 is free to use. It operates
on all major platforms (Linux, OSX, Windows, Android).
@@ -62,8 +63,8 @@ PyjamasDesktop (pyjs Desktop)
-----------------------------
PyjamasDesktop is a port of Pyjamas. PyjamasDesktop is application widget set
for desktop and a cross-platform framework. (After release v0.6 PyjamasDesktop
-is a part of Pyjamas (Pyjs)). Briefly, it allows the exact same Python web application
-source code to be executed as a standalone desktop application.
+is a part of Pyjamas (Pyjs)). Briefly, it allows the exact same Python web
+application source code to be executed as a standalone desktop application.
`Python Wiki for PyjamasDesktop `_.
diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst
index 557b44d46..83010d382 100644
--- a/docs/scenarios/imaging.rst
+++ b/docs/scenarios/imaging.rst
@@ -9,17 +9,19 @@ Python Imaging Library
----------------------
The `Python Imaging Library `_, or PIL
-for short, is *the* library for image manipulation in Python. Unfortunately, its
-development has stagnated, with its last release in 2009.
+for short, is *the* library for image manipulation in Python. Unfortunately,
+its development has stagnated, with its last release in 2009.
-Luckily for you, there's an actively-developed fork of PIL called `Pillow `_ -
-it's easier to install, runs on all operating systems, and supports Python 3.
+Luckily for you, there's an actively-developed fork of PIL called
+`Pillow `_ - it's easier to install, runs on
+all operating systems, and supports Python 3.
Installation
~~~~~~~~~~~~
Before installing Pillow, you'll have to install Pillow's prerequisites. Find
-the instructions for your platform `here `_.
+the instructions for your platform
+`here `_.
After that, it's straightforward:
diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst
index 2ca49e8cc..b5145fc4c 100644
--- a/docs/scenarios/json.rst
+++ b/docs/scenarios/json.rst
@@ -1,7 +1,9 @@
JSON
====
-The `json `_ library can parse JSON from strings or files. The library parses JSON into a Python dictionary or list. It can also convert Python dictionaries or lists into JSON strings.
+The `json `_ library can parse
+JSON from strings or files. The library parses JSON into a Python dictionary
+or list. It can also convert Python dictionaries or lists into JSON strings.
Parsing JSON
------------
@@ -43,14 +45,21 @@ You can also convert the following to JSON:
simplejson
----------
-The JSON library was added to Python in version 2.6. If you're using an earlier version of Python, the `simplejson `_ library is available via PyPI.
+The JSON library was added to Python in version 2.6.
+If you're using an earlier version of Python, the
+`simplejson `_ library is
+available via PyPI.
-simplejson mimics the json standard library. It is available so that developers that use older versions of Python can use the latest features available in the json lib.
+simplejson mimics the json standard library. It is available so that developers
+that use older versions of Python can use the latest features available in the
+json lib.
-You can start using simplejson when the json library is not available by importing simplejson under a different name:
+You can start using simplejson when the json library is not available by
+importing simplejson under a different name:
.. code-block:: python
import simplejson as json
-After importing simplejson as json, the above examples will all work as if you were using the standard json library.
+After importing simplejson as json, the above examples will all work as if you
+were using the standard json library.
diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst
index 48eccf208..dd8bfa67d 100644
--- a/docs/scenarios/network.rst
+++ b/docs/scenarios/network.rst
@@ -7,7 +7,8 @@ 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
-----
@@ -30,5 +31,6 @@ For a quick start, read the `ZeroMQ guide `_.
gevent
------
-`gevent `_ is a coroutine-based Python networking library
-that uses greenlets to provide a high-level synchronous API on top of the libev event loop.
+`gevent `_ is a coroutine-based Python networking
+library that uses greenlets to provide a high-level synchronous API on top of
+the libev event loop.
diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst
index 86f64093d..8600bc9b2 100644
--- a/docs/scenarios/scientific.rst
+++ b/docs/scenarios/scientific.rst
@@ -95,9 +95,10 @@ Rpy2
----
`Rpy2 `_ is a Python binding for the R
-statistical package allowing the execution of R functions from Python and passing
-data back and forth between the two environments. Rpy2 is the object oriented
-implementation of the `Rpy `_ bindings.
+statistical package allowing the execution of R functions from Python and
+passing data back and forth between the two environments. Rpy2 is the object
+oriented implementation of the `Rpy `_
+bindings.
PsychoPy
--------
@@ -121,11 +122,12 @@ Unofficial Windows Binaries for Python Extension Packages
---------------------------------------------------------
Many people who do scientific computing are on Windows, yet many of the
-scientific computing packages are notoriously difficult to build and install
-on this platform. `Christoph Gohlke `_
-however, has compiled a list of Windows binaries for many useful Python packages.
-The list of packages has grown from a mainly scientific Python resource to a more
-general list. If you're on Windows, you may want to check it out.
+scientific computing packages are notoriously difficult to build and install on
+this platform. `Christoph Gohlke `_
+however, has compiled a list of Windows binaries for many useful Python
+packages. The list of packages has grown from a mainly scientific Python
+resource to a more general list. If you're on Windows, you may want to check it
+out.
Anaconda
--------
diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst
index 8e1a6fc03..65560d3da 100644
--- a/docs/scenarios/scrape.rst
+++ b/docs/scenarios/scrape.rst
@@ -19,9 +19,10 @@ lxml and Requests
`lxml `_ is a pretty extensive library written for parsing
XML and HTML documents very quickly, even handling messed up tags in the
-process. We will also be using the `Requests `_
-module instead of the already built-in urllib2 module due to improvements in speed and
-readability. You can easily install both using ``pip install lxml`` and
+process. We will also be using the
+`Requests `_ module instead of the
+already built-in urllib2 module due to improvements in speed and readability.
+You can easily install both using ``pip install lxml`` and
``pip install requests``.
Let's start with the imports:
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index f7932959e..dd3539ec5 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -92,9 +92,10 @@ Support can be found on its `mailing list `_ is a scalable, non-blocking web server and web application framework with
-a relative simple usage. Tornado is known for its high performance.
-It was initially developed for `friendfeed `_ , a real time chat and blog system.
+`Tornado `_ is a scalable, non-blocking web server
+and web application framework with a relative simple usage. Tornado is known
+for its high performance. It was initially developed for
+`friendfeed `_ , a real time chat and blog system.
In the Jinja2 template engine example it is used to serve the rendered pages.
@@ -108,9 +109,9 @@ and functionality and can thus not be considered lightweight. On the other
hand, it does not provide all the functionality Django does. Instead Pyramid
brings basic support for most regular tasks and provides a great deal of
extensibility. Additionally, Pyramid has a huge focus on complete
-`documentation `__. As
-a little extra it comes with the Werkzeug Debugger which allows you to debug a
-running web application in the browser.
+`documentation `__.
+As a little extra it comes with the Werkzeug Debugger which allows you to debug
+a running web application in the browser.
**Support** can also be found in the
`documentation `__.
@@ -250,9 +251,10 @@ Gondor
~~~~~~
`Gondor `_ is a PaaS specialized for deploying Django
-and Pinax applications. Gondor recommends Django version 1.6 and supports any WSGI application on
-Python version 2.7. Gondor can automatically configure your Django site if you
-use :file:`local_settings.py` for site-specific configuration information.
+and Pinax applications. Gondor recommends Django version 1.6 and supports any
+WSGI application on Python version 2.7. Gondor can automatically configure your
+Django site if you use :file:`local_settings.py` for site-specific configuration
+information.
Gondor has a guide on deploying `Django projects `_.
@@ -260,23 +262,20 @@ Gondor has a guide on deploying `Django projects `_ provides an extensive guide on creating and maintaining Python packages.
+The `Python Packaging Guide `_
+provides an extensive guide on creating and maintaining Python packages.
For Python Developers
:::::::::::::::::::::
-If you're writing an open source Python module, `PyPI `_,
-more properly known as *The Cheeseshop*, is the place to host it.
+If you're writing an open source Python module, `PyPI `_
+, more properly known as *The Cheeseshop*, is the place to host it.
Pip vs. easy_install
--------------------
-Use `pip `_. More details `here `_
+Use `pip `_. More details
+`here `_
Personal PyPI
-------------
If you want to install packages from a source other than PyPI, (say, if
-your packages are *proprietary*), you can do it by hosting a simple http server,
-running from the directory which holds those packages which need to be installed.
+your packages are *proprietary*), you can do it by hosting a simple http
+server, running from the directory which holds those packages which need to be
+installed.
**Showing an example is always beneficial**
-For example, if you want to install a package called :file:`MyPackage.tar.gz`, and
-assuming this is your directory structure:
+For example, if you want to install a package called :file:`MyPackage.tar.gz`,
+and assuming this is your directory structure:
- archive
@@ -55,8 +58,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
-:file:`MyPackage` and keeping :file:`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*, you can still install MyPackage using:
.. code-block:: console
@@ -65,16 +68,18 @@ you can still install MyPackage using:
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 (:option:`-U`) which will update all its packages to their
-latest versions found on PyPI.
+`Pypiserver `_ is a minimal PyPI
+compatible server. It can be used to serve a set of packages to easy_install
+or pip. It includes helpful features like an administrative command
+(:option:`-U`) which will update all its packages to their latest versions
+found on PyPI.
S3-Hosted PyPi
++++++++++++++
-One simple option for a personal PyPi server is to use Amazon S3. A prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
+One simple option for a personal PyPi server is to use Amazon S3. A
+prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
1. **Install all your requirements from PyPi or another source**
2. **Install pip2pi**
diff --git a/docs/starting/pip-virtualenv.rst b/docs/starting/pip-virtualenv.rst
index b632c2b5b..fedcbe120 100644
--- a/docs/starting/pip-virtualenv.rst
+++ b/docs/starting/pip-virtualenv.rst
@@ -6,51 +6,53 @@ Further Configuration of Pip and Virtualenv
Requiring an active virtual environment for ``pip``
---------------------------------------------------
-By now it should be clear that using virtual envirtonments is a great way to keep
-your development environment clean and keeping different projects' requirements
-separate.
+By now it should be clear that using virtual envirtonments is a great way to
+keep your development environment clean and keeping different projects'
+requirements separate.
When you start working on many different projects, it can be hard to remember to
-activate the related virtual environment when you come back to a specific project.
-As a result of this, it is very easy to install packages globally while thinking
-that you are actually installing the package for the virtual environment of the
-project. Over time this can result in a messy global package list.
+activate the related virtual environment when you come back to a specific
+project. As a result of this, it is very easy to install packages globally
+while thinking that you are actually installing the package for the virtual
+environment of the 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
-:file:`~/.bashrc` file:
+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 :file:`~/.bashrc` file:
.. code-block:: console
export PIP_REQUIRE_VIRTUALENV=true
-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.
+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.
.. code-block:: console
$ pip install requests
Could not find an activated virtualenv (required).
-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:
+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 :file:`pip.ini` file is used by Windows operating systems and it can
-be found at:
+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 :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 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
``[global]`` settings to require an active virtual environment:
@@ -68,9 +70,9 @@ add the following lines to this new file:
require-virtualenv = true
-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 :file:`~/.bashrc` 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 :file:`~/.bashrc` file:
.. code-block:: console
@@ -78,38 +80,38 @@ the following to your :file:`~/.bashrc` file:
PIP_REQUIRE_VIRTUALENV="" pip "$@"
}
-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.
+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.
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
-projects.
+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 projects.
-It is surely unnecessary to re-download the same packages/libraries each time you
-start working on a new project (and in a new virtual environmen as a result).
+It is surely unnecessary to re-download the same packages/libraries each time
+you 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 :file:`.bashrc` or :file:`.bash_profile`
-file.
+On UNIX systems, you can add the following line to your :file:`.bashrc` or
+:file:`.bash_profile` file.
.. code-block:: console
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 :file:`.bashrc` (or :file:`.bash_profile`)
-file and you will be all set.
+access). After adding this line, ``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 :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 :file:`pip.ini` file under ``[global]`` settings:
+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 :file:`pip.ini` file under ``[global]`` settings:
.. code-block:: console
@@ -123,6 +125,6 @@ Similarly, on UNIX systems you should simply add the following line to your
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 :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.
+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/license.rst b/docs/writing/license.rst
index 0a5256b69..6c42df767 100644
--- a/docs/writing/license.rst
+++ b/docs/writing/license.rst
@@ -2,10 +2,9 @@ Choosing a License
==================
Your source publication *needs* a license. In the US, if no license is
-specified, users have no legal right to download, modify, or
-distribute. Furthermore, people can't contribute to your code unless
-you tell them what rules to play by. Choosing a license is complicated, so
-here are some pointers:
+specified, users have no legal right to download, modify, or distribute.
+Furthermore, people can't contribute to your code unless you tell them what
+rules to play by. Choosing a license is complicated, so here are some pointers:
Open source. There are plenty of `open source licenses
`_ available to choose
diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
index 7032ea0e2..8763e8dba 100644
--- a/docs/writing/logging.rst
+++ b/docs/writing/logging.rst
@@ -23,11 +23,10 @@ the goal is to display a help statement for a command line application.
Other reasons why logging is better than ``print``:
- The `log record`_, which is created with every logging event, contains
- readily available diagnostic information such as the file name,
- full path, function, and line number of the logging event.
-- Events logged in included modules are automatically accessible via the
- root logger
- to your application's logging stream, unless you filter them out.
+ readily available diagnostic information such as the file name, full path,
+ function, and line number of the logging event.
+- Events logged in included modules are automatically accessible via the root
+ logger to your application's logging stream, unless you filter them out.
- Logging can be selectively silenced by using the method
:meth:`logging.Logger.setLevel` or disabled by setting the attribute
:attr:`logging.Logger.disabled` to ``True``.
@@ -83,15 +82,14 @@ application environment.
There are at least three ways to configure a logger:
- Using an INI-formatted file:
- - **Pro**: possible to update configuration while running
- using the function :func:`logging.config.listen` to listen
- on a socket.
+ - **Pro**: possible to update configuration while running using the
+ function :func:`logging.config.listen` to listen on a socket.
- **Con**: less control (*e.g.* custom subclassed filters or loggers)
than possible when configuring a logger in code.
- Using a dictionary or a JSON-formatted file:
- - **Pro**: in addition to updating while running, it is possible to
- load from a file using the :mod:`json` module, in the standard
- library since Python 2.6.
+ - **Pro**: in addition to updating while running, it is possible to load
+ from a file using the :mod:`json` module, in the standard library since
+ Python 2.6.
- **Con**: less control than when configuring a logger in code.
- Using code:
- **Pro**: complete control over the configuration.
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 2c9b163b3..1dfebf42c 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -34,8 +34,8 @@ to do it poorly. Some signs of a poorly structured project
include:
- Multiple and messy circular dependencies: if your classes
- Table and Chair in :file:`furn.py` need to import Carpenter from :file:`workers.py`
- to answer a question such as ``table.isdoneby()``,
+ Table and Chair in :file:`furn.py` need to import Carpenter from
+ :file:`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
have a circular dependency. In this case you will have to resort to
@@ -85,17 +85,17 @@ 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
-modules such as `os` and `sys`, third-party modules you have installed in your
-environment, or your project's internal modules.
+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 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 :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 :file:`spam.py` file in a folder named :file:`my`
-which is not the case. There is an
+In the case of `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.
@@ -106,18 +106,18 @@ Aside from some naming restrictions, nothing special is required for a Python
file to be a module, but you need to understand the import mechanism in order
to use this concept properly and avoid some issues.
-Concretely, the ``import modu`` statement will look for the proper file, which is
-:file:`modu.py` in the same directory as the caller if it exists. If it is not
-found, the Python interpreter will search for :file:`modu.py` in the "path"
+Concretely, the ``import modu`` statement will look for the proper file, which
+is :file:`modu.py` in the same directory as the caller if it exists. If it is
+not found, the Python interpreter will search for :file:`modu.py` in the "path"
recursively and raise an ImportError exception if it is not found.
-Once :file:`modu.py` is found, the Python interpreter will execute the module in an
-isolated scope. Any top-level statement in :file:`modu.py` will be executed,
+Once :file:`modu.py` is found, the Python interpreter will execute the module in
+an isolated scope. Any top-level statement in :file:`modu.py` will be executed,
including other imports if any. Function and class definitions are stored in
the module's dictionary.
-Then, the module's variables, functions, and classes will be available to the caller
-through the module's namespace, a central concept in programming that is
+Then, the module's variables, functions, and classes will be available to the
+caller through the module's namespace, a central concept in programming that is
particularly helpful and powerful in Python.
In many languages, an ``include file`` directive is used by the preprocessor to
@@ -127,14 +127,15 @@ means that you generally don't have to worry that the included code could have
unwanted effects, e.g. override an existing function with the same name.
It is possible to simulate the more standard behavior by using a special syntax
-of the import statement: ``from modu import *``. This is generally considered bad
-practice. **Using** ``import *`` **makes code harder to read and makes dependencies less
-compartmentalized**.
+of the import statement: ``from modu import *``. This is generally considered
+bad practice. **Using** ``import *`` **makes code harder to read and makes
+dependencies less compartmentalized**.
Using ``from modu import func`` is a way to pinpoint the function you want to
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
-only advantage over a simpler ``import modu`` is that it will save a little typing.
+only advantage over a simpler ``import modu`` is that it will save a little
+typing.
**Very bad**
@@ -176,29 +177,32 @@ Packages
Python provides a very straightforward packaging system, which is simply an
extension of the module mechanism to a directory.
-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 :file:`__init__.py` file, which is used to
-gather all package-wide definitions.
+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 :file:`__init__.py` file, which is
+used to gather all package-wide definitions.
-A file :file:`modu.py` in the directory :file:`pack/` is imported with the statement ``import
-pack.modu``. This statement will look for an :file:`__init__.py` file in :file:`pack`, execute
-all of its top-level statements. Then it will look for a file named :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 named :file:`pack/modu.py` and
execute all of its top-level statements. After these operations, any variable,
-function, or class defined in :file:`modu.py` is available in the pack.modu namespace.
+function, or class defined in :file:`modu.py` is available in the pack.modu
+namespace.
A commonly seen issue is to add too much code to :file:`__init__.py`
files. When the project complexity grows, there may be sub-packages and
-sub-sub-packages in a deep directory structure. In this case, importing a single item
-from a sub-sub-package will require executing all :file:`__init__.py` files met while
-traversing the tree.
+sub-sub-packages in a deep directory structure. In this case, importing a
+single item from a sub-sub-package will require executing all
+:file:`__init__.py` files met while traversing the tree.
-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.
+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:
-``import very.deep.module as mod``. This allows you to use `mod` in place of the verbose
-repetition of ``very.deep.module``.
+``import very.deep.module as mod``. This allows you to use `mod` in place of the
+verbose repetition of ``very.deep.module``.
Object-oriented programming
---------------------------
@@ -232,27 +236,28 @@ functionality. The problem, as pointed out by the discussions about functional
programming, comes from the "state" part of the equation.
In some architectures, typically web applications, multiple instances of Python
-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
+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
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
-of this item at the same time, it may happen that the deletion actually occurs after
-the first process loaded the item, and then we have to mark as read a deleted
-object.
+of this item at the same time, it may happen that the deletion actually occurs
+after the first process loaded the item, and then we have to mark as read a
+deleted object.
This and other issues led to the idea that using stateless functions is a
better programming paradigm.
Another way to say the same thing is to suggest using functions and procedures
with as few implicit contexts and side-effects as possible. A function's
-implicit context is made up of any of the global variables or items in the persistence layer
-that are accessed from within the function. Side-effects are the changes that a function makes
-to its implicit context. If a function saves or deletes data in a global variable or
-in the persistence layer, it is said to have a side-effect.
+implicit context is made up of any of the global variables or items in the
+persistence layer that are accessed from within the function. Side-effects are
+the changes that a function makes to its implicit context. If a function saves
+or deletes data in a global variable or in the persistence layer, it is said to
+have a side-effect.
Carefully isolating functions with context and side-effects from functions with
logic (called pure functions) allow the following benefits:
@@ -314,19 +319,18 @@ of the function logic.
Dynamic typing
--------------
-Python is dynamically typed, which means that variables
-do not have a fixed type. In fact, in Python, variables are very
-different from what they are in many other languages, specifically
-statically-typed languages. Variables are not a segment of the computer's
-memory where some value is written, they are 'tags' or 'names' pointing
-to objects. It is therefore possible for the variable 'a' to be set to
-the value 1, then to the value 'a string', then to a function.
+Python is dynamically typed, which means that variables do not have a fixed
+type. In fact, in Python, variables are very different from what they are in
+many other languages, specifically statically-typed languages. Variables are not
+a segment of the computer's memory where some value is written, they are 'tags'
+or 'names' pointing to objects. It is therefore possible for the variable 'a' to
+be set to the value 1, then to the value 'a string', then to a function.
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
-maintainer needs to track this name in the code to make sure it has not
-been set to a completely unrelated object.
+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 maintainer needs to track
+this name in the code to make sure it has not been set to a completely unrelated
+object.
Some guidelines help to avoid this issue:
@@ -370,26 +374,25 @@ grows and each assignment is separated by other lines of code, including
'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.
-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.
+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 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.
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:
-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.
+Mutable types are those that allow in-place modification of the content. Typical
+mutables are lists and dictionaries: 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.
-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
-a name.
+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 a name.
.. code-block:: python
@@ -451,8 +454,8 @@ with calls to ``append()``.
One final thing to mention about strings is that using ``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()``
-should be your preferred method.
+like above or in cases where you are adding to an existing string, using
+``join()`` should be your preferred method.
.. code-block:: python
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 3f4cfa852..94ba24182 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -11,8 +11,8 @@ recognised fact that code is read much more often than it is written.
One reason for Python code to be easily read and understood is its relatively
complete set of Code Style guidelines and "Pythonic" idioms.
-Moreover, when a veteran Python developer (a Pythonista) points to portions of code
-and says they are not "Pythonic", it usually means that these lines
+Moreover, when a veteran Python developer (a Pythonista) points to portions of
+code and says they are not "Pythonic", it usually means that these lines
of code do not follow the common guidelines and fail to express the intent in
what is considered the best (hear: most readable) way.
@@ -86,40 +86,42 @@ Function arguments
Arguments can be passed to functions in four different ways.
-1. **Positional arguments** are mandatory and have no default values. They are the
-simplest form of arguments and they can be used for the few function arguments
-that are fully part of the function's meaning and their order is natural. For
-instance, in ``send(message, recipient)`` or ``point(x, y)`` the user of the
-function has no difficulty remembering that those two functions require two
-arguments, and in which order.
-
-In those two cases, it is possible to use argument names when calling the functions
-and, doing so, it is possible to switch the order of arguments, calling for instance
-``send(recipient='World', message='Hello')`` and ``point(y=2, x=1)`` but this
-reduces readability and is unnecessarily verbose, compared to the more straightforward
-calls to ``send('Hello', 'World')`` and ``point(1, 2)``.
-
-2. **Keyword arguments** are not mandatory and have default values. They are often
-used for optional parameters sent to the function. When a function has more than
-two or three positional parameters, its signature is more difficult to remember
-and using keyword arguments 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
-passed another value.
-
-Calling a function with keyword arguments can be done in multiple ways in Python,
-for example it is possible to follow the order of arguments in the definition without
-explicitly naming the arguments, like in ``send('Hello', 'World', 'Cthulhu', 'God')``,
-sending a blind carbon copy to God. It would also be possible to name arguments in
-another order, like in ``send('Hello again', 'World', bcc='God', cc='Cthulhu')``.
-Those two possibilities are better avoided without any strong reason to not
-follow the syntax that is the closest to the function definition: ``send('Hello',
-'World', cc='Cthulhu', bcc='God')``.
+1. **Positional arguments** are mandatory and have no default values. They are
+ the simplest form of arguments and they can be used for the few function
+ arguments that are fully part of the function's meaning and their order is
+ natural. For instance, in ``send(message, recipient)`` or ``point(x, y)``
+ the user of the function has no difficulty remembering that those two
+ functions require two arguments, and in which order.
+
+In those two cases, it is possible to use argument names when calling the
+functions and, doing so, it is possible to switch the order of arguments,
+calling for instance ``send(recipient='World', message='Hello')`` and
+``point(y=2, x=1)`` but this reduces readability and is unnecessarily verbose,
+compared to the more straightforward calls to ``send('Hello', 'World')`` and
+``point(1, 2)``.
+
+2. **Keyword arguments** are not mandatory and have default values. They are
+ often used for optional parameters sent to the function. When a function has
+ more than two or three positional parameters, its signature is more difficult
+ to remember and using keyword arguments 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 passed another value.
+
+Calling a function with keyword arguments can be done in multiple ways in
+Python, for example it is possible to follow the order of arguments in the
+definition without explicitly naming the arguments, like in
+``send('Hello', 'World', 'Cthulhu', 'God')``, sending a blind carbon copy to
+God. It would also be possible to name arguments in another order, like in
+``send('Hello again', 'World', bcc='God', cc='Cthulhu')``. Those two
+possibilities are better avoided without any strong reason to not follow the
+syntax that is the closest to the function definition:
+``send('Hello', 'World', cc='Cthulhu', bcc='God')``.
As a side note, following `YAGNI `_
-principle, it is often harder to remove an optional argument (and its logic inside the
-function) that was added "just in case" and is seemingly never used, than to add a
-new optional argument and its logic when needed.
+principle, it is often harder to remove an optional argument (and its logic
+inside the function) that was added "just in case" and is seemingly never used,
+than to add a new optional argument and its logic when needed.
3. The **arbitrary argument list** is the third way to pass arguments to a
function. If the function intention is better expressed by a signature with an
@@ -139,11 +141,12 @@ it explicitly: ``send(message, recipients)`` and call it with ``send('Hello',
the recipient list as a list beforehand, and it opens the possibility to pass
any sequence, including iterators, that cannot be unpacked as other sequences.
-4. The **arbitrary keyword argument dictionary** is the last way to pass arguments
-to functions. If the function requires an undetermined series of named
-arguments, it is possible to use the ``**kwargs`` construct. In the function
-body, ``kwargs`` will be a dictionary of all the passed named arguments that
-have not been caught by other keyword arguments in the function signature.
+4. The **arbitrary keyword argument dictionary** is the last way to pass
+ arguments to functions. If the function requires an undetermined series of
+ named arguments, it is possible to use the ``**kwargs`` construct. In the
+ function body, ``kwargs`` will be a dictionary of all the passed named
+ arguments that have not been caught by other keyword arguments in the
+ function signature.
The same caution as in the case of *arbitrary argument list* is necessary, for
similar reasons: these powerful techniques are to be used when there is a
@@ -158,8 +161,8 @@ Python functions that are:
* easy to read (the name and arguments need no explanations)
-* easy to change (adding a new keyword argument does not break other parts of the
- code)
+* easy to change (adding a new keyword argument does not break other parts of
+ the code)
Avoid the magical wand
~~~~~~~~~~~~~~~~~~~~~~
@@ -198,8 +201,8 @@ give a lot of mechanisms to prevent any misuse, is expressed by the saying: "We
are all consenting adults".
This doesn't mean that, for example, no properties are considered private, and
-that no proper encapsulation is possible in Python. Rather, instead of relying on
-concrete walls erected by the developers between their code and other's, the
+that no proper encapsulation is possible in Python. Rather, instead of relying
+on concrete walls erected by the developers between their code and other's, the
Python community prefers to rely on a set of conventions indicating that these
elements should not be accessed directly.
@@ -217,27 +220,29 @@ but making a public property private might be a much harder operation.
Returning values
~~~~~~~~~~~~~~~~
-When a function grows in complexity it is not uncommon to use multiple return statements
-inside the function's body. However, in order to keep a clear intent and a sustainable
-readability level, it is preferable to avoid returning meaningful values from many
-output points in the body.
-
-There are two main cases for returning values in a function: the result of the function
-return when it has been processed normally, and the error cases that indicate a wrong
-input parameter or any other reason for the function to not be able to complete its
-computation or task.
-
-If you do not wish to raise exceptions for the second case, then returning a value, such
-as None or False, indicating that the function could not perform correctly might be needed. In this
-case, it is better to return as early as the incorrect context has been detected. It will
-help to flatten the structure of the function: all the code after the return-because-of-error
-statement can assume the condition is met to further compute the function's main result.
+When a function grows in complexity it is not uncommon to use multiple return
+statements inside the function's body. However, in order to keep a clear intent
+and a sustainable readability level, it is preferable to avoid returning
+meaningful values from many output points in the body.
+
+There are two main cases for returning values in a function: the result of the
+function return when it has been processed normally, and the error cases that
+indicate a wrong input parameter or any other reason for the function to not be
+able to complete its computation or task.
+
+If you do not wish to raise exceptions for the second case, then returning a
+value, such as None or False, indicating that the function could not perform
+correctly might be needed. In this case, it is better to return as early as the
+incorrect context has been detected. It will help to flatten the structure of
+the function: all the code after the return-because-of-error statement can
+assume the condition is met to further compute the function's main result.
Having multiple such return statements is often necessary.
-However, when a function has multiple main exit points for its normal course, it becomes
-difficult to debug the returned result, so it may be preferable to keep a single exit
-point. This will also help factoring out some code paths, and the multiple exit points
-are a probable indication that such a refactoring is needed.
+However, when a function has multiple main exit points for its normal course,
+it becomes difficult to debug the returned result, so it may be preferable to
+keep a single exit point. This will also help factoring out some code paths,
+and the multiple exit points are a probable indication that such a refactoring
+is needed.
.. code-block:: python
@@ -256,14 +261,15 @@ are a probable indication that such a refactoring is needed.
Idioms
------
-A programming idiom, put simply, is a *way* to write code. The notion of programming idioms
-is discussed amply at `c2 `_ and at `Stack Overflow `_.
+A programming idiom, put simply, is a *way* to write code. The notion of
+programming idioms is discussed amply at `c2 `_
+and at `Stack Overflow `_.
Idiomatic Python code is often referred to as being *Pythonic*.
-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.
+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.
Some common Python idioms follow:
@@ -346,16 +352,19 @@ Instead, use a list comprehension:
four_lists = [[] for __ in xrange(4)]
-A common idiom for creating strings is to use :py:meth:`str.join` on an empty string.
+A common idiom for creating strings is to use :py:meth:`str.join` on an empty
+string.
.. code-block:: python
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:
@@ -374,8 +383,9 @@ 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 dictionary can be done very quickly.
-For more information see this `StackOverflow `_
+the hash of the dictionary, finding keys in the dictionary can be done very
+quickly. For more information see this
+`StackOverflow `_
page.
Zen of Python
@@ -604,11 +614,11 @@ Line Continuations
~~~~~~~~~~~~~~~~~~
When a logical line of code is longer than the accepted limit, you need to
-split it over multiple physical lines. The Python interpreter will join consecutive
-lines if the last character of the line is a backslash. This is helpful
-in some cases, but should usually be avoided because of its fragility: a white space
-added to the end of the line, after the backslash, will break the code and may
-have unexpected results.
+split it over multiple physical lines. The Python interpreter will join
+consecutive lines if the last character of the line is a backslash. This is
+helpful in some cases, but should usually be avoided because of its fragility:
+a white space added to the end of the line, after the backslash, will break the
+code and may have unexpected results.
A better solution is to use parentheses around your elements. Left with an
unclosed parenthesis on an end-of-line the Python interpreter will join the
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
index f8856d69e..f014bfdfd 100644
--- a/docs/writing/tests.rst
+++ b/docs/writing/tests.rst
@@ -20,11 +20,11 @@ Some general rules of testing:
- Try hard to make tests that run fast. If one single test needs more than a
few milliseconds to run, development will be slowed down or the tests will
- not be run as often as is desirable. In some cases, tests can't be fast because
- they need a complex data structure to work on, and this data structure must
- be loaded every time the test runs. Keep these heavier tests in a separate
- test suite that is run by some scheduled task, and run all other tests as
- often as needed.
+ not be run as often as is desirable. In some cases, tests can't be fast
+ because they need a complex data structure to work on, and this data structure
+ must be loaded every time the test runs. Keep these heavier tests in a
+ separate test suite that is run by some scheduled task, and run all other
+ tests as often as needed.
- Learn your tools and learn how to run a single test or a test case. Then,
when developing a function inside a module, run this function's tests very
From 060851270d0a8ccabc3bd40e1d6398ae5e74463f Mon Sep 17 00:00:00 2001
From: taddeimania
Date: Sun, 8 Mar 2015 22:07:31 -0500
Subject: [PATCH 077/760] Revise 'consenting adult' verbiage
---
docs/writing/style.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 94ba24182..4d00666ee 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -89,7 +89,7 @@ Arguments can be passed to functions in four different ways.
1. **Positional arguments** are mandatory and have no default values. They are
the simplest form of arguments and they can be used for the few function
arguments that are fully part of the function's meaning and their order is
- natural. For instance, in ``send(message, recipient)`` or ``point(x, y)``
+ natural. For instance, in ``send(message, recipient)`` or ``point(x, y)``
the user of the function has no difficulty remembering that those two
functions require two arguments, and in which order.
@@ -190,7 +190,7 @@ them is very important.
Like a kung fu master, a Pythonista knows how to kill with a single finger, and
never to actually do it.
-We are all consenting adults
+We are all responsible users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As seen above, Python allows many tricks, and some of them are potentially
@@ -198,7 +198,7 @@ dangerous. A good example is that any client code can override an object's
properties and methods: there is no "private" keyword in Python. This
philosophy, very different from highly defensive languages like Java, which
give a lot of mechanisms to prevent any misuse, is expressed by the saying: "We
-are all consenting adults".
+are all responsible users".
This doesn't mean that, for example, no properties are considered private, and
that no proper encapsulation is possible in Python. Rather, instead of relying
From 2876c05e72ad4b76bbb43f76586242dd8f5deb80 Mon Sep 17 00:00:00 2001
From: Chris Streeter
Date: Tue, 17 Mar 2015 18:15:00 -0700
Subject: [PATCH 078/760] Fix link to pip vs easy_install
---
docs/starting/install/osx.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
index ac2b5f7d6..367be136f 100644
--- a/docs/starting/install/osx.rst
+++ b/docs/starting/install/osx.rst
@@ -73,7 +73,7 @@ software over a network (usually the Internet) with a single command
capability to your own Python software with very little work.
``pip`` is a tool for easily installing and managing Python packages,
-that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_,
+that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_,
and is actively maintained.
From 315eba8d79c241829622059e5981bf63e5c43a20 Mon Sep 17 00:00:00 2001
From: Tony Narlock
Date: Fri, 20 Mar 2015 11:25:41 -0700
Subject: [PATCH 079/760] Add ptpython to other tools
https://github.com/jonathanslenders/ptpython/
---
docs/dev/env.rst | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index 0503e9010..9977d74df 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -278,7 +278,6 @@ most out of using Python interactively. Its main components are:
$ pip install ipython
-
BPython
-------
@@ -298,3 +297,24 @@ features:
.. code-block:: console
$ pip install bpython
+
+ptpython
+--------
+
+`ptpython `_ is a REPL build
+on top of the `prompt_toolkit `_
+library. It is considered to be an alternative to BPython_. Features include:
+
+* Syntax highlighting
+* Autocompletion
+* Multiline editing
+* Emacs and VIM Mode
+* Embedding REPL inside of your code
+* Syntax Validation
+* Tab pages
+* Support for integrating with IPython_'s shell, by installing IPython
+ ``pip install ipython`` and running ``ptipython``.
+
+.. code-block:: console
+
+ $ pip install ptpython
From 7325e07008a5e8120d00d57023bb2d624f68c25e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20Kolding-S=C3=B8rensen?=
Date: Sun, 12 Apr 2015 12:09:32 +0200
Subject: [PATCH 080/760] update latest version link to 2.7.9
---
docs/starting/install/win.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst
index 69f026065..20208cd87 100644
--- a/docs/starting/install/win.rst
+++ b/docs/starting/install/win.rst
@@ -3,7 +3,7 @@
Installing Python on Windows
============================
-First, download the `latest version `_
+First, download the `latest version `_
of Python 2.7 from the official Website. If you want to be sure you are installing a fully
up-to-date version then use the "Windows Installer" link from the home page of the
`Python.org web site `_ .
From 5468e02eccfd4b4a046dee38ab2a70e1890e716e Mon Sep 17 00:00:00 2001
From: Alex Clark
Date: Fri, 1 May 2015 20:48:34 -0400
Subject: [PATCH 081/760] Update imaging.rst
Refer to official Pillow documentation instead of outdated release README; installation instructions were relocated from ``README.rst`` to docs/ sometime after 2.8.1 was released. And docs have been hosted on RTD for quite some time.
---
docs/scenarios/imaging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst
index 83010d382..5d4e25bfb 100644
--- a/docs/scenarios/imaging.rst
+++ b/docs/scenarios/imaging.rst
@@ -21,7 +21,7 @@ Installation
Before installing Pillow, you'll have to install Pillow's prerequisites. Find
the instructions for your platform
-`here `_.
+`here `_.
After that, it's straightforward:
From 28e365f1ea45fc58c6c4d08aad7c546fded9e38f Mon Sep 17 00:00:00 2001
From: Kristi Nikolla
Date: Sun, 3 May 2015 11:20:37 -0400
Subject: [PATCH 082/760] Removed broken link to Zen of Python in style.rst
---
docs/writing/style.rst | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 4d00666ee..a4e3e8887 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -418,8 +418,7 @@ Also known as :pep:`20`, the guiding principles for Python's design.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
-For some examples of good Python style, see `this Stack Overflow question
-`_ or `these
+For some examples of good Python style, see `these
slides from a Python user group
`_.
From f7ee56f50d7fb12377f5ddf3e31695c2523a2cf5 Mon Sep 17 00:00:00 2001
From: Kristi Nikolla
Date: Sun, 3 May 2015 11:25:46 -0400
Subject: [PATCH 083/760] Corrected line ending after removing broken link
---
docs/writing/style.rst | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index a4e3e8887..ae37cf6e3 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -418,9 +418,8 @@ Also known as :pep:`20`, the guiding principles for Python's design.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
-For some examples of good Python style, see `these
-slides from a Python user group
-`_.
+For some examples of good Python style, see `these slides from a Python user
+group `_.
PEP 8
-----
From ad9f689f830ff9199650fa494db73a2e5fe89ec0 Mon Sep 17 00:00:00 2001
From: Dave Forgac
Date: Sun, 3 May 2015 22:11:32 -0400
Subject: [PATCH 084/760] Fixed broken contributing link
---
CONTRIBUTING.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0035989a7..481f3f63c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ How to contribute
This guide is under heavy development. If you would like to contribute, please
see:
-http://docs.python-guide.org/en/latest/notes/contribute.html
+http://docs.python-guide.org/en/latest/notes/contribute/
Style Guide
From 6af3912ce696ae2e3e3d6debd77a9fe5e08aa2c7 Mon Sep 17 00:00:00 2001
From: vienno
Date: Wed, 13 May 2015 19:09:10 +0200
Subject: [PATCH 085/760] jython version now 2.7
---
docs/starting/which-python.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst
index 0be021635..2b633b8c9 100644
--- a/docs/starting/which-python.rst
+++ b/docs/starting/which-python.rst
@@ -113,7 +113,7 @@ 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.
-Jython currently supports up to Python 2.5. [#jython_ver]_
+Jython currently supports up to Python 2.7. [#jython_ver]_
IronPython
----------
@@ -146,7 +146,7 @@ PythonNet supports from Python 2.3 up to Python 2.7. [#pythonnet_ver]_
.. [#pypy_ver] http://pypy.org/compat.html
-.. [#jython_ver] http://wiki.python.org/jython/JythonFaq/GeneralInfo#Is_Jython_the_same_language_as_Python.3F
+.. [#jython_ver] https://hg.python.org/jython/file/412a8f9445f7/NEWS
.. [#iron_ver] http://ironpython.codeplex.com/releases/view/81726
From 7e7e971588050196bc9bd7f439c786321aa7c4a1 Mon Sep 17 00:00:00 2001
From: Taylor Edmiston
Date: Fri, 15 May 2015 21:11:51 -0400
Subject: [PATCH 086/760] Add mkproject instructions for virtualenvwrapper
---
docs/dev/virtualenvs.rst | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
index 8c3403591..e7f3d0ed1 100644
--- a/docs/dev/virtualenvs.rst
+++ b/docs/dev/virtualenvs.rst
@@ -160,6 +160,14 @@ This creates the :file:`venv` folder inside :file:`~/Envs`.
$ workon venv
+Alternatively, you can make a project, which creates the virtual environment,
+and also a project directory inside ``$PROJECT_HOME``, which is ``cd`` -ed into
+when you ``workon myproject``.
+
+.. code-block:: console
+
+ $ mkproject myproject
+
**virtualenvwrapper** provides tab-completion on environment names. It really
helps when you have a lot of environments and have trouble remembering their
names.
From bb593a1b949a170c7458a7f991a6ad850088774a Mon Sep 17 00:00:00 2001
From: vipul
Date: Mon, 18 May 2015 19:39:16 +0530
Subject: [PATCH 087/760] fixes #532 added doc for vim-flake8
fixes #532 added doc for vim-flake8
fixes #532 added doc for vim-flake8
---
docs/dev/env.rst | 15 ++++++---------
1 file changed, 6 insertions(+), 9 deletions(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index 0503e9010..d9a6fce4e 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -41,16 +41,14 @@ errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you.
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
-install vim-pyflakes_. Now you can map the functions ``Pep8()`` or
-``Pyflakes()`` to any hotkey or action you want in Vim. Both plugins will
+For PEP8 checking and pyflakes, you can install vim-flake8_. Now you can map the
+function ``Flake8`` to any hotkey or action you want in Vim. The plugin 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
+the corresponding line. It's very handy to call this function whenever you save
+a file. In order to do this, add the following line to your
:file:`.vimrc`::
- autocmd BufWritePost *.py call Pyflakes()
- autocmd BufWritePost *.py call Pep8()
+ autocmd BufWritePost *.py call Flake8()
If you are already using syntastic_, you can set it to run Pyflakes on write
and show errors and warnings in the quickfix window. An example configuration
@@ -88,12 +86,11 @@ using ```` key or any other customized keys.
.. _indent: http://www.vim.org/scripts/script.php?script_id=974
.. _syntax: http://www.vim.org/scripts/script.php?script_id=790
.. _Pyflakes: http://pypi.python.org/pypi/pyflakes/
-.. _vim-pyflakes: https://github.com/nvie/vim-pyflakes
.. _PEP8: http://pypi.python.org/pypi/pep8/
-.. _vim-pep8: https://github.com/nvie/vim-pep8
.. _syntastic: https://github.com/scrooloose/syntastic
.. _Python-mode: https://github.com/klen/python-mode
.. _SuperTab: http://www.vim.org/scripts/script.php?script_id=1643
+.. _vim-flake8: https://github.com/nvie/vim-flake8
Emacs
-----
From 06e3bcef58c7e7f704ea9b37d0b0b26ebc6d5b20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Fern=C3=A1ndez=20Ramos?=
Date: Sun, 24 May 2015 18:09:05 +0200
Subject: [PATCH 088/760] Fix rst formatting for chameleon link
---
docs/scenarios/web.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index dd3539ec5..14080f341 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -418,7 +418,7 @@ Chameleon
`Chameleon `_ Page Templates are an HTML/XML template
engine implementation of the `Template Attribute Language (TAL) `_,
`TAL Expression Syntax (TALES) `_,
-and `Macro Expansion TAL (Metal) ` syntaxes.
+and `Macro Expansion TAL (Metal) `_ syntaxes.
Chameleon is available for Python 2.5 and up (including 3.x and pypy), and
is commonly used by the `Pyramid Framework `_.
From 9b1e9e268650a673ad59ae65030641a2734fa62c Mon Sep 17 00:00:00 2001
From: spollard
Date: Thu, 18 Jun 2015 10:57:23 -0600
Subject: [PATCH 089/760] Update gui.rst
---
docs/scenarios/gui.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index 05901fda2..55959fabd 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -42,17 +42,17 @@ on all major platforms (Linux, OSX, Windows, Android).
The main resource for information is the website: http://kivy.org
PyObjC
-~~~~~~
+------
.. note:: Only available on OS X. Don't pick this if you're writing a cross-platform application.
PySide
-~~~~~~
+------
PySide is a Python binding of the cross-platform GUI toolkit Qt.
http://developer.qt.nokia.com/wiki/PySideDownloads/
PyQt
-~~~~
+----
.. note:: If your software does not fully comply with the GPL you will need a commercial license!
PyQt provides Python bindings for the Qt Framework (see below).
From ec78861eef2faa5f87cb2bfa390ad6aab8d22d92 Mon Sep 17 00:00:00 2001
From: Sriram Sundarraj
Date: Fri, 17 Jul 2015 16:12:58 +0530
Subject: [PATCH 090/760] Fixes #543. % is not depricated in PEP3101.
---
docs/writing/structure.rst | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 1dfebf42c..98be4bf11 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -469,9 +469,8 @@ like above or in cases where you are adding to an existing string, using
.. note::
You can also use the :ref:`% ` formatting operator
to concatenate a pre-determined number of strings besides :py:meth:`str.join`
- and ``+``. However, according to :pep:`3101`, the ``%`` operator became
- deprecated in Python 3.1 and will be replaced by the :py:meth:`str.format`
- method in the later versions.
+ and ``+``. However, :pep:`3101`, discourages the usage of the ``%`` operator
+ in favor of the :py:meth:`str.format` method.
.. code-block:: python
From 6f8082d1b6079ccbe84f5c2671ade1bf602418bd Mon Sep 17 00:00:00 2001
From: Andy Smith
Date: Sun, 16 Aug 2015 20:58:12 +0100
Subject: [PATCH 091/760] reflect unification of python in emacs.
---
docs/dev/env.rst | 4 ----
1 file changed, 4 deletions(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index d9a6fce4e..6aca3b71c 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -100,10 +100,6 @@ it can be some work to wire up correctly. A good start if you're already an
Emacs user is `Python Programming in Emacs`_ at EmacsWiki.
1. Emacs itself comes with a Python mode.
-2. Python ships with an alternate version:
- `python-mode.el `_
-3. Fabián Ezequiel Gallina's `python.el `_
- provides nice functionality and behavior out of the box
.. _Python Programming in Emacs: http://emacswiki.org/emacs/PythonProgrammingInEmacs
From 1a79ec73c223059372d6bd2a9b4d4af1cfd8ee0d Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 21 Aug 2015 13:27:33 +0100
Subject: [PATCH 092/760] Intro paras for Freezing and Packaging Your Code
I've tried to describe why you would choose one method over
another, and what the relative advantages and disadvantages
are of each method.
I'm painfully aware that I haven't covered the combo of
freezing an application *then* creating a Linux distro
package of it, but maybe that's a battle for another day.
My intent is to add more content on the Freezing page
once this commit is accepted, so I can hear your feedback
before doing any further work.
Thanks.
---
docs/shipping/freezing.rst | 32 ++++++++++++++----
docs/shipping/packaging.rst | 67 +++++++++++++++++++++++++++++++++++--
2 files changed, 90 insertions(+), 9 deletions(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 9eb559ec0..668bdeb09 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -1,17 +1,35 @@
+.. _freezing-your-code-ref:
+
+==================
Freezing Your Code
==================
-An alternative to shipping your code is freezing it — shipping it as an
-executable with a bundled Python interpreter.
+To 'Freeze' your code is to distribute to end-users as an executable which
+includes a bundled Python interpreter.
-Many applications you use every day do this:
+Applications such as 'Dropbox', BitTorrent clients, 'Eve Online' and
+'Civilisation IV' do this.
-- Dropbox
-- BitTorrent
-- ...
+The advantage of distributing this way is that your application will work even
+if the user doesn't already have the required version of Python installed. On
+Windows, and even on many Linux distributions and OSX versions, the right
+version of Python will not already be installed.
-.. todo:: Fill in "Freezing Your Code" stub
+One disadvantage is that it will bloat your distribution by about 2Mb.
+Another problem is that your application, once downloaded by a user, will
+not receive any security updates to the version of Python it uses.
+
+Alternatives to Freezing
+------------------------
+:ref:`Packaging your code ` is for distributing
+libraries or tools to other developers.
+
+On Linux, an alternative to freezing is to
+:ref:`create a Linux distro package `
+(e.g. a .deb file for Debian or Ubuntu.)
+
+.. todo:: Fill in "Freezing Your Code" stub
Comparison
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index 482a18c84..d854c0d01 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -1,13 +1,43 @@
+.. _packaging-your-code-ref:
+
+===================
Packaging Your Code
===================
-Packaging your code is important.
+Package your code to share it with other developers. For example
+to share a library for other developers to use in their application,
+or for development tools like 'py.test'.
+
+An advantage of this method of distribution is its well established ecosystem
+of tools such as PyPI and pip, which make it easy for other developers to
+download and install your package either for casual experiments, or as part of
+large, professional systems.
-You'll need to package your code first before sharing it with other developers.
+It is a well-established convention for Python code to be shared this way.
+If your code isn't packaged on PyPI, then it will be harder
+for other developers to find it, and to use it as part of their existing
+process. They will regard such projects with substantial suspicion of being
+either badly managed or abandoned.
+
+The downside of distributing code like this is that it relies on the
+recipient understanding how to install the required version of Python,
+and being able and willing to use tools such as pip to install your code's
+other dependencies. This is fine when distributing to other developers, but
+makes this method unsuitable for distributing applications to end-uers.
The `Python Packaging Guide `_
provides an extensive guide on creating and maintaining Python packages.
+Alternatives to Packaging
+:::::::::::::::::::::::::
+
+To distribute applications to end-users, you should
+:ref:`freeze your application `.
+
+On Linux, you may also want to consider
+:ref:`creating a Linux distro package `
+(e.g. a .deb file for Debian or Ubuntu.)
+
For Python Developers
:::::::::::::::::::::
@@ -106,9 +136,42 @@ prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage`
+.. _packaging-for-linux-distributions-ref:
+
For Linux Distributions
::::::::::::::::::::::::
+Creating a Linux distro package is arguably the "right way" to distribute code
+on Linux.
+
+Because a distribution package doesn't include the Python interpreter, it
+makes the download and install about 2Mb smaller than
+:ref:`freezing your application `.
+
+Also, if a distribution releases a new security update for Python, then your
+application will automatically start using that new version of Python.
+
+However, creating and maintaining the different configurations required for
+each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red
+Hat/Fedora, etc) is a fair amount of work. If your code is an application that
+you plan to distribute on other platforms, then you'll also have to create and
+maintain the separate config required to freeze your application for Windows
+and OSX. It would be much less work to simply create and maintain a single
+config for one of the cross platform :ref:`freezing tools
+`, which will produce stand-alone executables for all
+distributions of Linux, as well as Windows and OSX.
+
+Creating a distribution package is also problematic if your code is for a
+version of Python that isn't currently supported by a distribution.
+Having to tell *some versions* of Ubuntu end-users that they need to add `the
+'dead-snakes' PPA `_
+using `sudo apt-repository` commands before they can install your .deb file
+makes for an extremely hostile user experience. Not only that, but you'd have
+to maintain a custom equivalent of these instructions for every distribution,
+and worse, have your users read, understand, and act on them.
+
+Having said all that, here's how to do it:
+
* `Fedora `_
* `Debian and Ubuntu `_
* `Arch `_
From 5587288b81412cb18f30408bbf160afcfc0d4536 Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 21 Aug 2015 13:30:50 +0100
Subject: [PATCH 093/760] Freezing: clarify how it affects Python security
updates
---
docs/shipping/freezing.rst | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 668bdeb09..cdea1e661 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -16,8 +16,9 @@ Windows, and even on many Linux distributions and OSX versions, the right
version of Python will not already be installed.
One disadvantage is that it will bloat your distribution by about 2Mb.
-Another problem is that your application, once downloaded by a user, will
-not receive any security updates to the version of Python it uses.
+Another problem is that your application will not receive any security updates
+to the version of Python it uses unless you freeze a new version and get
+users to download it.
Alternatives to Freezing
------------------------
From 2914f721881a6387b6ddbc783b2ccb1348a73ba1 Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 21 Aug 2015 14:54:53 +0100
Subject: [PATCH 094/760] Megabyte is abbreviated 'MB', according to wikipedia
---
docs/shipping/freezing.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index cdea1e661..2d8b0e3ce 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -15,7 +15,7 @@ if the user doesn't already have the required version of Python installed. On
Windows, and even on many Linux distributions and OSX versions, the right
version of Python will not already be installed.
-One disadvantage is that it will bloat your distribution by about 2Mb.
+One disadvantage is that it will bloat your distribution by about 2MB.
Another problem is that your application will not receive any security updates
to the version of Python it uses unless you freeze a new version and get
users to download it.
From 72e00459bb202f188423f59c6b45e6838269771c Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 21 Aug 2015 14:56:41 +0100
Subject: [PATCH 095/760] Megabyte is abbreviated 'MB', according to wikipedia
---
docs/shipping/packaging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index d854c0d01..40486c153 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -145,7 +145,7 @@ Creating a Linux distro package is arguably the "right way" to distribute code
on Linux.
Because a distribution package doesn't include the Python interpreter, it
-makes the download and install about 2Mb smaller than
+makes the download and install about 2MB smaller than
:ref:`freezing your application `.
Also, if a distribution releases a new security update for Python, then your
From 04e38e9e8ba14439896023791793c9fc1ad50e6b Mon Sep 17 00:00:00 2001
From: Paulius Labanauskis
Date: Sun, 23 Aug 2015 09:02:59 +0300
Subject: [PATCH 096/760] Fixed a broken PEP acceptance workflow link.
---
docs/intro/community.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/intro/community.rst b/docs/intro/community.rst
index f54caffea..ff65aabff 100644
--- a/docs/intro/community.rst
+++ b/docs/intro/community.rst
@@ -65,7 +65,7 @@ Submitting a PEP
Here's an overview of the PEP acceptance workflow:
- .. image:: http://www.python.org/dev/peps/pep-0001/pep-0001-1.png
+ .. image:: https://www.python.org/m/dev/peps/pep-0001/pep-0001-1.png
Python Conferences
From c0b377e84dda2d27f249b77f77c6ed3adef3543c Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 28 Aug 2015 11:01:00 +0100
Subject: [PATCH 097/760] also mention .rpm as an example Linux package
---
docs/shipping/freezing.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 2d8b0e3ce..e333f6976 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -28,7 +28,7 @@ libraries or tools to other developers.
On Linux, an alternative to freezing is to
:ref:`create a Linux distro package `
-(e.g. a .deb file for Debian or Ubuntu.)
+(e.g. .deb files for Debian or Ubuntu, or .rpm files for Red Hat and SuSE.)
.. todo:: Fill in "Freezing Your Code" stub
From df345c0ca098b1ab33d528fc731582274b26e152 Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 28 Aug 2015 11:21:43 +0100
Subject: [PATCH 098/760] add mention of bdist_rpm
---
docs/shipping/packaging.rst | 3 +++
1 file changed, 3 insertions(+)
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index 40486c153..18d8fd450 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -151,6 +151,9 @@ makes the download and install about 2MB smaller than
Also, if a distribution releases a new security update for Python, then your
application will automatically start using that new version of Python.
+[Producing an RPM file using the bdist_rpm command](https://docs.python.org/3/distutils/builtdist.html#creating-rpm-packages)
+for use by distributions like Red Hat or SuSE is trivially easy.
+
However, creating and maintaining the different configurations required for
each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red
Hat/Fedora, etc) is a fair amount of work. If your code is an application that
From 62282e47e8a1724dae7708f71851f46cac51c24d Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 28 Aug 2015 11:33:55 +0100
Subject: [PATCH 099/760] fix markup
---
docs/shipping/packaging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index 18d8fd450..064e6a9e2 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -151,7 +151,7 @@ makes the download and install about 2MB smaller than
Also, if a distribution releases a new security update for Python, then your
application will automatically start using that new version of Python.
-[Producing an RPM file using the bdist_rpm command](https://docs.python.org/3/distutils/builtdist.html#creating-rpm-packages)
+The `Producing an RPM file using the bdist_rpm command
Date: Fri, 28 Aug 2015 11:35:21 +0100
Subject: [PATCH 100/760] fix markup again
---
docs/shipping/packaging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index 064e6a9e2..020baed79 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -151,7 +151,7 @@ makes the download and install about 2MB smaller than
Also, if a distribution releases a new security update for Python, then your
application will automatically start using that new version of Python.
-The `Producing an RPM file using the bdist_rpm command `_
for use by distributions like Red Hat or SuSE is trivially easy.
However, creating and maintaining the different configurations required for
From b4f393c83ab4b34b202cfd0c0656312e6899eb4b Mon Sep 17 00:00:00 2001
From: Jonathan Hartley
Date: Fri, 28 Aug 2015 11:36:35 +0100
Subject: [PATCH 101/760] fix grammar typos
---
docs/shipping/packaging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
index 020baed79..2fa1ca7ab 100644
--- a/docs/shipping/packaging.rst
+++ b/docs/shipping/packaging.rst
@@ -151,7 +151,7 @@ makes the download and install about 2MB smaller than
Also, if a distribution releases a new security update for Python, then your
application will automatically start using that new version of Python.
-The `Producing an RPM file using the bdist_rpm command `_
+The bdist_rpm command makes `producing an RPM file `_
for use by distributions like Red Hat or SuSE is trivially easy.
However, creating and maintaining the different configurations required for
From ee19ef65c846cd33e59f51cbeecc3844bd6cef0a Mon Sep 17 00:00:00 2001
From: SeongHoon Ryu
Date: Thu, 3 Sep 2015 00:19:15 +0900
Subject: [PATCH 102/760] serif failback
---
docs/_themes/kr/static/flasky.css_t | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/_themes/kr/static/flasky.css_t b/docs/_themes/kr/static/flasky.css_t
index c86b80b4f..690a11696 100644
--- a/docs/_themes/kr/static/flasky.css_t
+++ b/docs/_themes/kr/static/flasky.css_t
@@ -14,7 +14,7 @@
/* -- page layout ----------------------------------------------------------- */
body {
- font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro';
+ font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro' , serif;
font-size: 17px;
background-color: white;
color: #000;
@@ -532,4 +532,4 @@ a:hover tt {
.revsys-inline {
display: none!important;
-}
\ No newline at end of file
+}
From 4c84110606283600009a3ff12ed4bf6cbffde069 Mon Sep 17 00:00:00 2001
From: Brett Cannon
Date: Wed, 9 Sep 2015 09:16:58 -0700
Subject: [PATCH 103/760] Point to the Python 3 porting HOWTO
Kept up-to-date unlike Armin's blog post on the subject.
---
docs/starting/which-python.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst
index 2b633b8c9..29146d889 100644
--- a/docs/starting/which-python.rst
+++ b/docs/starting/which-python.rst
@@ -58,8 +58,8 @@ software you're depending on will block your adoption of Python 3.
`Further Reading `_
-It is possible to `write code that works on Python 2.6, 2.7, and 3.3
-`_. This
+It is possible to `write code that works on Python 2.6, 2.7, and Python 3
+`_. This
ranges from trivial to hard depending upon the kind of software
you are writing; if you're a beginner there are far more important things to
worry about.
From 2187540f9d97b937a7f1ca29e1eca53f0a82bf5b Mon Sep 17 00:00:00 2001
From: Markus Hackspacher
Date: Wed, 16 Sep 2015 21:40:40 +0200
Subject: [PATCH 104/760] pyside link
---
docs/scenarios/gui.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index 55959fabd..19e888d1c 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -49,7 +49,9 @@ PySide
------
PySide is a Python binding of the cross-platform GUI toolkit Qt.
-http://developer.qt.nokia.com/wiki/PySideDownloads/
+ pip install pyside
+
+https://wiki.qt.io/Category:LanguageBindings::PySide::Downloads
PyQt
----
From 4b6bbd5efbe91c67b159f16d6fe7626278a26f43 Mon Sep 17 00:00:00 2001
From: i-rme
Date: Wed, 30 Sep 2015 20:53:53 +0200
Subject: [PATCH 105/760] quick start is written wrong
---
docs/intro/learning.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 10fdca00c..ba4a95965 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -9,7 +9,7 @@ The Python Tutorial
This is the official tutorial. It covers all the basics, and offers a tour of
the language and the standard library. Recommended for those who need a
-quickstart guide to the language.
+quick-start guide to the language.
`The Python Tutorial `_
From e88dad2dc0a5ced43d9c1f2727ec70f842036519 Mon Sep 17 00:00:00 2001
From: "Rajath Kumar M.P"
Date: Thu, 1 Oct 2015 02:45:41 +0530
Subject: [PATCH 106/760] Minor Edit
Latest is El Capitan
---
docs/starting/install/osx.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
index 367be136f..28b1800e6 100644
--- a/docs/starting/install/osx.rst
+++ b/docs/starting/install/osx.rst
@@ -3,7 +3,7 @@
Installing Python on Mac OS X
=============================
-The latest version of Mac OS X, Yosemite, **comes with Python 2.7 out of the box**.
+The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**.
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
From 04cf7b2f51b35bed44f253c0a0367e9b6724689a Mon Sep 17 00:00:00 2001
From: George Gognadze
Date: Thu, 1 Oct 2015 02:19:10 +0400
Subject: [PATCH 107/760] Update the Readme.rst
f should be capitalized.
---
Readme.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Readme.rst b/Readme.rst
index bf7f1838b..56c7a7ac1 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -20,7 +20,7 @@ Topics include:
- Py2app, Py2exe, bbfreeze, pyInstaller
- Pip
- Virtualenv
-- fabric
+- Fabric
- Exhaustive module recommendations, grouped by topic/purpose
- Which libraries to use for what
- Server configurations & tools for various web frameworks
From 258bc91c537657574e4d8e087d82c21a1b137ac4 Mon Sep 17 00:00:00 2001
From: Anuj Pahuja
Date: Thu, 1 Oct 2015 12:56:08 +0530
Subject: [PATCH 108/760] Contribute link on sidebar fixed
---
docs/_templates/sidebarintro.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
index 0bfc69a02..216c94065 100644
--- a/docs/_templates/sidebarintro.html
+++ b/docs/_templates/sidebarintro.html
@@ -23,7 +23,7 @@ Contributors
This guide is the result of the collaboration of
135+ people
around the world, and your contributions
- are welcome!
+ are welcome!
From a35561efc9d19687297d00e19ca8e0fdbcf8d2a6 Mon Sep 17 00:00:00 2001
From: "Rajath Kumar M.P"
Date: Thu, 1 Oct 2015 18:39:55 +0530
Subject: [PATCH 109/760] IPython install edit
Installs dependencies for notebook.
---
docs/dev/env.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index 391f230ce..3c33b1338 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -268,7 +268,7 @@ most out of using Python interactively. Its main components are:
.. code-block:: console
- $ pip install ipython
+ $ pip install ipython[all]
BPython
From 0e48f6cc3d06557ff342e761003b0deea6ba99ca Mon Sep 17 00:00:00 2001
From: Aaron Critchley
Date: Thu, 1 Oct 2015 23:19:20 +0100
Subject: [PATCH 110/760] Un-hypenating best practice
---
Readme.rst | 2 +-
docs/_templates/sidebarintro.html | 2 +-
docs/_templates/sidebarlogo.html | 2 +-
docs/index.rst | 2 +-
docs/intro/duction.rst | 2 +-
5 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/Readme.rst b/Readme.rst
index 56c7a7ac1..17fb855c5 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -9,7 +9,7 @@ Hitchhiker's Guide to Python
be done.**
This guide is currently under heavy development. This opinionated guide
-exists to provide both novice and expert Python developers a best-practice
+exists to provide both novice and expert Python developers a best practice
handbook to the installation, configuration, and usage of Python on a daily
basis.
diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
index 0bfc69a02..1d745dbcd 100644
--- a/docs/_templates/sidebarintro.html
+++ b/docs/_templates/sidebarintro.html
@@ -1,6 +1,6 @@
Python Guide.
- This opinionated guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
+ This opinionated guide exists to provide both novice and expert Python developers a best practice handbook to the installation, configuration, and usage of Python on a daily basis.
Get Updates
diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html
index 70a9b3d4e..67650e89f 100644
--- a/docs/_templates/sidebarlogo.html
+++ b/docs/_templates/sidebarlogo.html
@@ -1,6 +1,6 @@
- This opinionated guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
+ This opinionated guide exists to provide both novice and expert Python developers a best practice handbook to the installation, configuration, and usage of Python on a daily basis.
Get Updates
diff --git a/docs/index.rst b/docs/index.rst
index 3e34d33f0..0371c6373 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,7 +12,7 @@ Welcome to The Hitchhiker's Guide to Python.
`fork us on GitHub `_!
This *opinionated* guide exists to provide both novice and expert Python
-developers a best-practice handbook to the installation, configuration, and
+developers a best practice handbook to the installation, configuration, and
usage of Python on a daily basis.
.. include:: contents.rst.inc
diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst
index 5930d7f64..e18d146c2 100644
--- a/docs/intro/duction.rst
+++ b/docs/intro/duction.rst
@@ -61,7 +61,7 @@ Purpose
~~~~~~~
The Hitchhiker's Guide to Python exists to provide both novice and expert
-Python developers a best-practice handbook to the installation, configuration,
+Python developers a best practice handbook for the installation, configuration,
and usage of Python on a daily basis.
From 8f18bcecec854533b36e7d3c062824a793a42534 Mon Sep 17 00:00:00 2001
From: "L. Caputo"
Date: Thu, 1 Oct 2015 21:02:18 -0400
Subject: [PATCH 111/760] Corrected typo.
Standardized spelling to match Oxford spelling throughout the rest of the text. Changed 'recognised' to 'recognized'.
---
docs/writing/style.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index ae37cf6e3..5e661516c 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -6,7 +6,7 @@ Code Style
If you ask Python programmers what they like most in Python, they will
often say its high readability. Indeed, a high level of readability
is at the heart of the design of the Python language, following the
-recognised fact that code is read much more often than it is written.
+recognized fact that code is read much more often than it is written.
One reason for Python code to be easily read and understood is its relatively
complete set of Code Style guidelines and "Pythonic" idioms.
From 4a40fe3a22650924a3a1f3ed39e4d91624a2e0e0 Mon Sep 17 00:00:00 2001
From: "Rajath Kumar M.P"
Date: Fri, 2 Oct 2015 12:34:28 +0530
Subject: [PATCH 112/760] updated
---
docs/dev/env.rst | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index 3c33b1338..ee5e6bb21 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -268,8 +268,13 @@ most out of using Python interactively. Its main components are:
.. code-block:: console
- $ pip install ipython[all]
+ $ pip install ipython
+To download and install IPython with all it's main optional dependencies for the notebook, qtconsole, tests, and other functionalities
+
+.. code-block:: console
+
+ $pip install ipython[all]
BPython
-------
From 510b3c61da591fd696c10a3a0ed361236a9423de Mon Sep 17 00:00:00 2001
From: "Rajath Kumar M.P"
Date: Fri, 2 Oct 2015 19:20:07 +0530
Subject: [PATCH 113/760] update - 2
---
docs/dev/env.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index ee5e6bb21..dae86e4cd 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -270,11 +270,11 @@ most out of using Python interactively. Its main components are:
$ pip install ipython
-To download and install IPython with all it's main optional dependencies for the notebook, qtconsole, tests, and other functionalities
+To download and install IPython with all it's optional dependencies for the notebook, qtconsole, tests, and other functionalities
.. code-block:: console
- $pip install ipython[all]
+ $ pip install ipython[all]
BPython
-------
From a829c6e9baa489e4bef5ec2608832a501d5b55f6 Mon Sep 17 00:00:00 2001
From: Varun Agrawal
Date: Fri, 2 Oct 2015 14:32:04 +0000
Subject: [PATCH 114/760] PIL installation link fix
---
docs/scenarios/imaging.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst
index 5d4e25bfb..f0f18bde8 100644
--- a/docs/scenarios/imaging.rst
+++ b/docs/scenarios/imaging.rst
@@ -21,7 +21,7 @@ Installation
Before installing Pillow, you'll have to install Pillow's prerequisites. Find
the instructions for your platform
-`here `_.
+`here `_.
After that, it's straightforward:
From 1f0a62a8f896d81927939dad0d25df9faa94b936 Mon Sep 17 00:00:00 2001
From: Varun Agrawal
Date: Fri, 2 Oct 2015 14:51:18 +0000
Subject: [PATCH 115/760] updated virtualenv sectio to remove duplicates
---
docs/dev/env.rst | 8 +-------
1 file changed, 1 insertion(+), 7 deletions(-)
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
index 391f230ce..9405e258a 100644
--- a/docs/dev/env.rst
+++ b/docs/dev/env.rst
@@ -223,13 +223,7 @@ Interpreter Tools
Virtual Environments
--------------------
-A Virtual Environment 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.
-
-For example, you can work on a project which requires Django 1.3 while also
-maintaining a project which requires Django 1.0.
+Virtual Environments provide a powerful way to isolate project package dependencies. This means that you can use packages particular to a Python project without installing them system wide and thus avoiding potential version conflicts.
To start using and see more information:
`Virtual Environments `_ docs.
From 45c01b0955e5ee27dcd6de3073eecd04d9e262e9 Mon Sep 17 00:00:00 2001
From: Ryan Sandridge
Date: Fri, 2 Oct 2015 14:32:57 -0400
Subject: [PATCH 116/760] Fixing typo. Singular object, not plural.
---
docs/writing/structure.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 98be4bf11..f99c53eb0 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -213,7 +213,7 @@ can be somewhat misleading and needs to be clarified.
In Python, everything is an object, and can be handled as such. This is what is
meant when we say, for example, that functions are first-class objects.
Functions, classes, strings, and even types are objects in Python: like any
-objects, they have a type, they can be passed as function arguments, they may
+object, they have a type, they can be passed as function arguments, they may
have methods and properties. In this understanding, Python is an
object-oriented language.
From e79bbce25520d4032044fc77755be7906bf1799c Mon Sep 17 00:00:00 2001
From: Ryan Sandridge
Date: Fri, 2 Oct 2015 14:37:44 -0400
Subject: [PATCH 117/760] Adding conjunction "and" after the serial comma.
---
docs/writing/structure.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index f99c53eb0..05a90e816 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -213,8 +213,8 @@ can be somewhat misleading and needs to be clarified.
In Python, everything is an object, and can be handled as such. This is what is
meant when we say, for example, that functions are first-class objects.
Functions, classes, strings, and even types are objects in Python: like any
-object, they have a type, they can be passed as function arguments, they may
-have methods and properties. In this understanding, Python is an
+object, they have a type, they can be passed as function arguments, and they
+may have methods and properties. In this understanding, Python is an
object-oriented language.
However, unlike Java, Python does not impose object-oriented programming as the
From c16bc50cb815b35b573411322deea05ff1feed6d Mon Sep 17 00:00:00 2001
From: George Gognadze |