From c95f0d010b64570203c9e57bc54ffd5d5ac4c791 Mon Sep 17 00:00:00 2001
From: Mahan Marwat
Date: Sat, 3 Oct 2015 10:38:14 +0500
Subject: [PATCH 001/572] PyGObject section added
PyGObject (Python GTK+ 3 bindings) section has been added.
---
docs/scenarios/gui.rst | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
index 19e888d1c..47e3d825d 100644
--- a/docs/scenarios/gui.rst
+++ b/docs/scenarios/gui.rst
@@ -25,6 +25,13 @@ 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.
+PyGObject aka (PyGi)
+--------------------
+`PyGObject `_ provides Python bindings, which gives access to the entire GNOME software platform.
+It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial `_.
+
+`API Reference `_
+
Kivy
----
`Kivy `_ is a Python library for development of multi-touch
From 94f1e45754e852fdf8d40bb8c8b15852e1646071 Mon Sep 17 00:00:00 2001
From: bhchance
Date: Tue, 20 Oct 2015 18:44:26 -0500
Subject: [PATCH 002/572] Update learning.rst
Added description of Effective Python, copying format of other book writeups.
---
docs/intro/learning.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index ba4a95965..f918e1509 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -139,6 +139,15 @@ A Codeacademy course for the absolute Python beginner. This free and interactive
Advanced
--------
+Effective Python
+~~~~~~~~~~~~~~~~
+
+This book contains 59 specific ways to improve writing Pythonic code. At 227
+pages, it is a very brief overview of some of the most commons adapations
+programmers need to make to become efficient intermediate level Python
+programmers.
+
+ `Effective Python `_
Pro Python
~~~~~~~~~~
From 5ce9c8a445c60f3f1da21bd340ab99857d3f0a31 Mon Sep 17 00:00:00 2001
From: Gordon Senesac Jr
Date: Thu, 22 Oct 2015 20:22:57 -0500
Subject: [PATCH 003/572] Added serialization.rst file to scenarios.
---
docs/scenarios/serialization.rst | 40 ++++++++++++++++++++++++++++++++
1 file changed, 40 insertions(+)
create mode 100644 docs/scenarios/serialization.rst
diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst
new file mode 100644
index 000000000..ac0494f14
--- /dev/null
+++ b/docs/scenarios/serialization.rst
@@ -0,0 +1,40 @@
+==================
+Data Serialization
+==================
+
+What is data serialization?
+---------------------------
+
+Data serialization is the concept of converting structured data into a format
+that allows it to be shared or stored in such a way that its original
+structure to be recovered. In some cases, the secondary intention of data
+serialization is to minimize the size of the serialized data which then
+minimizes disk space or bandwidth requirements.
+
+Pickle
+------
+
+The native data serialization module for Python is called `Pickle
+`_.
+
+Here's an example:
+
+.. code-block:: python
+
+ import pickle
+
+ #Here's an example dict
+ grades = { 'Alice': 89, 'Bob': 72, 'Charles': 87 }
+
+ #Use dumps to convert the object to a serialized string
+ serial_grades = pickle.dumps( grades )
+
+ #Use loads to de-serialize an object
+ received_grades = pickle.loads( serial_grades )
+
+Protobuf
+--------
+
+If you're looking for a serialization module that has support in multiple
+languages, Google's `Protobuf
+`_ library is an option.
From 77cf4f478d4effec4833e211e6bb76ff54960cef Mon Sep 17 00:00:00 2001
From: sirMackk
Date: Thu, 22 Oct 2015 07:55:18 +0200
Subject: [PATCH 004/572] Adds context manager section to structure.rst
---
docs/writing/structure.rst | 69 ++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 05a90e816..7d9a06274 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -316,6 +316,75 @@ expensive function in a table and use them directly instead of recomputing
them when they have already been computed. This is clearly not part
of the function logic.
+Context Managers
+----------------
+
+A context manager is a Python object that provides extra contextual information
+to an action. This extra information takes the form of running a function upon
+initiating the context using the ``with`` statement as well as running a function
+upon completing all the code inside the ``with`` block. The most well known
+example of using a context manager is operating on a file:
+
+.. code-block:: python
+
+ with open('file.txt') as f:
+ contents = f.read()
+
+Anyone familiar with this pattern knows that invoking ``open`` in this fashion
+ensures that ``f``'s ``close`` method will be called at some point. This reduces
+a developer's cognitive load and makes code easier to read.
+
+There are two easy ways to implement this functionality yourself: using a class
+or using a generator. Let's implement the above functionality ourselves, starting
+with the class approach:
+
+.. code-block:: python
+
+ class CustomOpen(object):
+ def __init__(self, filename):
+ self.file = open(filename)
+
+ def __enter__(self):
+ return self.file
+
+ def __exit__(self, ctx_type, ctx_value, ctx_traceback):
+ self.file.close()
+
+ with CustomOpen('file') as f:
+ contents = f.read()
+
+This is just a regular Python object with two extra methods that are used
+by the ``with`` statement. CustomOpen is first instantiated and then its
+``__enter__`` method is called and whatever ``__enter__`` returns is assigned to
+``f`` in the ``as f`` part of the statement. When the contents of the ``with`` block
+is finished executing, the ``__exit__`` method is then called.
+
+And now the generator approach using Python's own
+`contextlib `_:
+
+.. code-block:: python
+
+ from contextlib import contextmanager
+
+ @contextmanager
+ def custom_open(filename):
+ f = open(filename)
+ yield f
+ f.close()
+
+ with custom_open('file') as f:
+ contents = f.read()
+
+This works in exactly the same way as the class example above, albeit it's
+more terse. The ``custom_open`` function executes until it reaches the ``yield``
+statement. It then gives control back to the ``with`` statement, which assigns
+whatever was ``yield``'ed to `f` in the ``as f`` portion.
+
+Since the two approaches appear the same, we should follow the Zen of Python
+to decide when to use which. The class approach might be better if there's
+a considerable amount of logic to encapsulate. The function approach
+might be better for situations where we're dealing with a simple action.
+
Dynamic typing
--------------
From bbead84641fde56daa6e7c5fad5a2ada076bb019 Mon Sep 17 00:00:00 2001
From: jxu093
Date: Sun, 25 Oct 2015 22:39:16 -0400
Subject: [PATCH 005/572] Add misc learning resource
fullstackpython for web development
---
docs/intro/learning.rst | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 12a1326f3..b84ae268d 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -241,6 +241,21 @@ through a series of code transformations, "When you see this, do that instead."
`Transforming Code into Beautiful, Idiomatic Python `_
+Fullstack Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fullstack Python offers a complete top-to-bottom resource for web development
+using Python.
+
+From setting up the webserver, to designing the front-end, choosing a database,
+optimizing/scaling, etc.
+
+As the name suggests, it covers everything you need to build and run a complete
+web app from scratch.
+
+ `Fullstack Python `_
+
+
References
----------
From 7c6848beb6575790a5f28d7be83ca3ddc9269f8a Mon Sep 17 00:00:00 2001
From: Steven Bock
Date: Tue, 27 Oct 2015 21:53:06 -0700
Subject: [PATCH 006/572] Added Codecademy description
Elaborated on the Codecademy description so it specifies that the user's code is interpreted in-browser for feedback on the user's work. This part wasn't specified very well in the previous description.
---
docs/intro/learning.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 12a1326f3..67a19aa29 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -30,7 +30,7 @@ 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 `_
-
+
Online Python Tutor
~~~~~~~~~~~~~~~~~~~
@@ -143,6 +143,7 @@ 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.
+This course also features a built in interpreter for receiving instant feedback on your learning.
`Learn to Program in Python with Codeacademy `_
From 3bfafa47d31c23b82fb1ff02c0f517e3918013aa Mon Sep 17 00:00:00 2001
From: dshendler
Date: Wed, 28 Oct 2015 23:48:10 -0500
Subject: [PATCH 007/572] updated location of windows install from python.org
home page
---
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 a0f37c530..d50c96422 100644
--- a/docs/starting/install/win.rst
+++ b/docs/starting/install/win.rst
@@ -5,7 +5,7 @@ Installing Python on Windows
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
+up-to-date version, click the Downloads > Windows link from the home page of the
`Python.org web site `_ .
The Windows version is provided as an MSI package. To install it manually, just
From 6e4eb1f9a659a1875e6582fdd9bb5341ebaa5f14 Mon Sep 17 00:00:00 2001
From: Thomas Levine <_@thomaslevine.com>
Date: Wed, 4 Nov 2015 20:00:59 -0500
Subject: [PATCH 008/572] use .content in lxml
This can also be thought of as a bug in lxml.
It just occurred to me that maybe I should fix that.
---
docs/scenarios/scrape.rst | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst
index 65560d3da..0728d2592 100644
--- a/docs/scenarios/scrape.rst
+++ b/docs/scenarios/scrape.rst
@@ -38,7 +38,10 @@ parse it using the ``html`` module and save the results in ``tree``:
.. code-block:: python
page = requests.get('http://econpy.pythonanywhere.com/ex/001.html')
- tree = html.fromstring(page.text)
+ tree = html.fromstring(page.content)
+
+(We need to use ``page.content`` rather than ``page.text`` because
+``html.fromstring`` implicitly expects ``bytes`` as input.)
``tree`` now contains the whole HTML file in a nice tree structure which
we can go over two different ways: XPath and CSSSelect. In this example, we
From baf4158b138dd5fb9c38a80c7a525b0d604b601e Mon Sep 17 00:00:00 2001
From: Britta Gustafson
Date: Tue, 17 Nov 2015 15:48:52 -0800
Subject: [PATCH 009/572] Link to internal Virtual Environments page from
install pages
---
docs/dev/virtualenvs.rst | 2 ++
docs/starting/install/linux.rst | 2 +-
docs/starting/install/osx.rst | 2 +-
docs/starting/install/win.rst | 2 +-
4 files changed, 5 insertions(+), 3 deletions(-)
diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
index 266faeb72..bb3f9487c 100644
--- a/docs/dev/virtualenvs.rst
+++ b/docs/dev/virtualenvs.rst
@@ -1,3 +1,5 @@
+.. _virtualenvironments-ref:
+
Virtual Environments
====================
diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst
index a42106de0..e68c5d0d5 100644
--- a/docs/starting/install/linux.rst
+++ b/docs/starting/install/linux.rst
@@ -58,7 +58,7 @@ 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 this and see more information: :ref:`Virtual Environments ` docs.
You can also use :ref:`virtualenvwrapper ` to make it easier to
manage your virtual environments.
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
index 0de724f1d..cb0062cc7 100644
--- a/docs/starting/install/osx.rst
+++ b/docs/starting/install/osx.rst
@@ -92,7 +92,7 @@ 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 this and see more information: :ref:`Virtual Environments ` docs.
--------------------------------
diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst
index a0f37c530..140c84205 100644
--- a/docs/starting/install/win.rst
+++ b/docs/starting/install/win.rst
@@ -77,7 +77,7 @@ 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 this and see more information: :ref:`Virtual Environments ` docs.
--------------------------------
From 560391d0ce331a47b8498a1a3d57adeaeee269fc Mon Sep 17 00:00:00 2001
From: Britta
Date: Thu, 19 Nov 2015 14:40:01 -0800
Subject: [PATCH 010/572] Updating "Gittip" to "Gratipay" in text and links
Gittip changed its name to Gratipay more than a year ago.
---
docs/_templates/sidebarintro.html | 4 ++--
docs/_templates/sidebarlogo.html | 6 +++---
2 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
index 65ca51e33..8a958d9a6 100644
--- a/docs/_templates/sidebarintro.html
+++ b/docs/_templates/sidebarintro.html
@@ -10,11 +10,11 @@
Get Updates
Donate
- If you enjoy this guide, consider supporting the author on Gittip:
+ If you enjoy this guide, consider supporting the author on Gratipay:
- If you enjoy this guide, consider supporting the author on Gratipay:
-
-
-
-
-
Contributors
This guide is the result of the collaboration of
diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html
index cfe41fc12..6372b3f31 100644
--- a/docs/_templates/sidebarlogo.html
+++ b/docs/_templates/sidebarlogo.html
@@ -7,13 +7,3 @@
Get Updates
Receive updates on new releases and upcoming projects.
- If you enjoy this guide, consider supporting the author on Gratipay:
-
-
-
-
From b05b43090b26d49661d3b648f93001a8b1b82c96 Mon Sep 17 00:00:00 2001
From: Saurav Sachidanand
Date: Thu, 3 Dec 2015 11:59:53 +0530
Subject: [PATCH 012/572] Updated PyInstaller section for OS X
Added explanation and examples for PyInstaller for OS X.
---
docs/shipping/freezing.rst | 44 ++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 8b01d647e..eff9ead36 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -117,6 +117,50 @@ py2app
PyInstaller
~~~~~~~~~~~
+PyInstaller can be used to build Unix executables and windowed apps on Mac OS X 10.6 (Snow Leopard) or newer.
+
+- To install PyInstaller, use pip:
+
+ .. code-block:: console
+
+ $ pip install pyinstaller
+
+- To create a standard Unix executable, from say :code:`script.py`, use:
+
+ .. code-block:: console
+
+ $ pyinstaller script.py
+
+ This creates,
+
+ - a :code:`script.spec` file, analogous to a :code:`make` file
+ - a :code:`build` folder, that holds some log files
+ - a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries,
+
+ all in the same folder as :code:`script.py`. PyInstaller puts all the Python libraries used in :code:`script.py` into the :code:`dist` folder, so when distributing the executable, distribute the whole :code:`dist` folder.
+
+- The :code:`script.spec` file can be edited to `customise the build `_, with options such as
+
+ - bundling data files with the executable
+ - including run-time libraries (:code:`.dll` or :code:`.so` files) that PyInstaller can't infer automatically
+ - adding Python run-time options to the executable,
+
+ Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :code:`script.py` again):
+
+ .. code-block:: console
+
+ $ pyinstaller script.spec
+
+- To create a standalone windowed OS X application, use the :code:`--windowed` option
+
+ .. code-block:: console
+
+ $ pyinstaller --windowed script.spec
+
+ This creates a :code:`script.app` in the :code:`dist` folder. Make sure to use GUI packages in your Python code, like `PyQt `_ or `PySide `_, to control the graphical parts of the app.
+
+ There are several options in :code:`script.spec` related to Mac OS X app bundles `here `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option.
+
Linux
-----
From c9035bd548941b3d2d586b3c43cc3c988a61b4c5 Mon Sep 17 00:00:00 2001
From: Saurav Sachidanand
Date: Thu, 3 Dec 2015 12:04:41 +0530
Subject: [PATCH 013/572] Updated formatting in PyInstaller for OS X section
---
docs/shipping/freezing.rst | 46 +++++++++++++++++++-------------------
1 file changed, 23 insertions(+), 23 deletions(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index eff9ead36..7664ad30e 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -119,47 +119,47 @@ PyInstaller
PyInstaller can be used to build Unix executables and windowed apps on Mac OS X 10.6 (Snow Leopard) or newer.
-- To install PyInstaller, use pip:
+To install PyInstaller, use pip:
- .. code-block:: console
+.. code-block:: console
- $ pip install pyinstaller
+ $ pip install pyinstaller
-- To create a standard Unix executable, from say :code:`script.py`, use:
+To create a standard Unix executable, from say :code:`script.py`, use:
- .. code-block:: console
+.. code-block:: console
- $ pyinstaller script.py
+ $ pyinstaller script.py
- This creates,
+This creates,
- - a :code:`script.spec` file, analogous to a :code:`make` file
- - a :code:`build` folder, that holds some log files
- - a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries,
+- a :code:`script.spec` file, analogous to a :code:`make` file
+- a :code:`build` folder, that holds some log files
+- a :code:`dist` folder, that holds the main executable :code:`script`, and some dependent Python libraries,
- all in the same folder as :code:`script.py`. PyInstaller puts all the Python libraries used in :code:`script.py` into the :code:`dist` folder, so when distributing the executable, distribute the whole :code:`dist` folder.
+all in the same folder as :code:`script.py`. PyInstaller puts all the Python libraries used in :code:`script.py` into the :code:`dist` folder, so when distributing the executable, distribute the whole :code:`dist` folder.
-- The :code:`script.spec` file can be edited to `customise the build `_, with options such as
+The :code:`script.spec` file can be edited to `customise the build `_, with options such as
- - bundling data files with the executable
- - including run-time libraries (:code:`.dll` or :code:`.so` files) that PyInstaller can't infer automatically
- - adding Python run-time options to the executable,
+- bundling data files with the executable
+- including run-time libraries (:code:`.dll` or :code:`.so` files) that PyInstaller can't infer automatically
+- adding Python run-time options to the executable,
- Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :code:`script.py` again):
+Now :code:`script.spec` can be run with :code:`pyinstaller` (instead of using :code:`script.py` again):
- .. code-block:: console
+.. code-block:: console
- $ pyinstaller script.spec
+ $ pyinstaller script.spec
-- To create a standalone windowed OS X application, use the :code:`--windowed` option
+To create a standalone windowed OS X application, use the :code:`--windowed` option
- .. code-block:: console
+.. code-block:: console
- $ pyinstaller --windowed script.spec
+ $ pyinstaller --windowed script.spec
- This creates a :code:`script.app` in the :code:`dist` folder. Make sure to use GUI packages in your Python code, like `PyQt `_ or `PySide `_, to control the graphical parts of the app.
+This creates a :code:`script.app` in the :code:`dist` folder. Make sure to use GUI packages in your Python code, like `PyQt `_ or `PySide `_, to control the graphical parts of the app.
- There are several options in :code:`script.spec` related to Mac OS X app bundles `here `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option.
+There are several options in :code:`script.spec` related to Mac OS X app bundles `here `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option.
Linux
From 6a0e1787d72bddcf8dd7a224d7086c3811d03e1e Mon Sep 17 00:00:00 2001
From: Sourav Singh
Date: Wed, 16 Dec 2015 10:36:45 +0530
Subject: [PATCH 014/572] Some Corrections in README
Some small correction in README.
---
Readme.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Readme.rst b/Readme.rst
index 540740df6..bccb651b0 100644
--- a/Readme.rst
+++ b/Readme.rst
@@ -19,7 +19,7 @@ Topics include:
- Platform- and version-specific installations
- Py2app, Py2exe, bbfreeze, pyInstaller
- Pip
-- Numpy, scipy, statpy, pylot, matlib
+- Numpy, scipy, statpy, pyplot, matplotlib
- Virtualenv
- Fabric
- Exhaustive module recommendations, grouped by topic/purpose
From aa8bf18b871c1d46a7d8a53938c60971f193d16f Mon Sep 17 00:00:00 2001
From: Taranjeet
Date: Sun, 27 Dec 2015 18:02:49 +0530
Subject: [PATCH 015/572] removes repeating web.py from docs/scenarios
---
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 60ba2afba..493996a8c 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -80,7 +80,7 @@ email to flask@librelist.com and reply to the confirmation email.
Web.py
------
-`Web.py `_ web.py is a web framework for Python that is as
+`Web.py `_ is a web framework for Python that is as
simple as it is powerful. You won't find wizards or boilerplate websites
in Web.py and will have to build from scratch. Web.py provides no administration
utility. Web.py is the brainchild of Aaron Swartz, who developed it while working
From 59ca0c71d580c30c0de0dcb40b4ff897ccb51bc5 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Fri, 15 Jan 2016 17:57:14 -0500
Subject: [PATCH 016/572] Update conf.py
---
docs/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/conf.py b/docs/conf.py
index d0f218ae6..811579743 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -46,7 +46,7 @@
# General information about the project.
project = u'pythonguide'
-copyright = u'2014. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0'
+copyright = u'2016. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
From bad3c407e7f3bb4cd072c14c40ce9bae90557da2 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Fri, 15 Jan 2016 18:02:12 -0500
Subject: [PATCH 017/572] Update .travis.yml
---
.travis.yml | 1 -
1 file changed, 1 deletion(-)
diff --git a/.travis.yml b/.travis.yml
index b107f1293..b540badc2 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -4,4 +4,3 @@ install: pip install sphinx
script:
- make doctest
- make html
-- sphinx-build -E -W -c docs -b html docs docs/_build/html
From 9379b625ba49c28e0679421c944c1cfb919081b7 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Fri, 15 Jan 2016 18:07:14 -0500
Subject: [PATCH 018/572] Update learning.rst
---
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 67a19aa29..6b28bb03e 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -143,7 +143,7 @@ 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.
-This course also features a built in interpreter for receiving instant feedback on your learning.
+This course also features a built-in interpreter for receiving instant feedback on your learning.
`Learn to Program in Python with Codeacademy `_
From c0dfe512bf8db035b7ba3437f1ce7fbb38693ec6 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Fri, 15 Jan 2016 18:10:42 -0500
Subject: [PATCH 019/572] Update contents.rst.inc
---
docs/contents.rst.inc | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index 59bc39ad3..e7660c061 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -60,6 +60,7 @@ different scenarios.
scenarios/speed
scenarios/scientific
scenarios/imaging
+ scenarios/serialization
scenarios/xml
scenarios/json
scenarios/crypto
From c843060d6daf6277ecf5ff05ff25464629d91d42 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Fri, 15 Jan 2016 18:15:24 -0500
Subject: [PATCH 020/572] updates to context managers
---
docs/writing/structure.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index 7d9a06274..a78b7cb61 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -320,10 +320,10 @@ Context Managers
----------------
A context manager is a Python object that provides extra contextual information
-to an action. This extra information takes the form of running a function upon
-initiating the context using the ``with`` statement as well as running a function
+to an action. This extra information takes the form of running a callable upon
+initiating the context using the ``with`` statement, as well as running a callable
upon completing all the code inside the ``with`` block. The most well known
-example of using a context manager is operating on a file:
+example of using a context manager is shown here, opening on a file:
.. code-block:: python
@@ -332,7 +332,7 @@ example of using a context manager is operating on a file:
Anyone familiar with this pattern knows that invoking ``open`` in this fashion
ensures that ``f``'s ``close`` method will be called at some point. This reduces
-a developer's cognitive load and makes code easier to read.
+a developer's cognitive load and makes the code easier to read.
There are two easy ways to implement this functionality yourself: using a class
or using a generator. Let's implement the above functionality ourselves, starting
@@ -359,7 +359,7 @@ by the ``with`` statement. CustomOpen is first instantiated and then its
``f`` in the ``as f`` part of the statement. When the contents of the ``with`` block
is finished executing, the ``__exit__`` method is then called.
-And now the generator approach using Python's own
+And now the generator approach using Python's own
`contextlib `_:
.. code-block:: python
From 128891585f20bea4f01c8fcda906b57253ab4940 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Fri, 15 Jan 2016 18:19:40 -0500
Subject: [PATCH 021/572] intermediate books section
---
docs/intro/learning.rst | 33 +++++++++++++++++++--------------
1 file changed, 19 insertions(+), 14 deletions(-)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index f0725495d..2eb88d90d 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -30,14 +30,14 @@ 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 `_
-
+
Online Python Tutor
~~~~~~~~~~~~~~~~~~~
-Online Python Tutor gives you a visual step by step
+Online Python Tutor gives you a visual step by step
representation of how your program runs. Python Tutor
helps people overcome a fundamental barrier to learning
-programming by understanding what happens as the computer
+programming by understanding what happens as the computer
executes each line of a program's source code.
`Online Python Tutor `_
@@ -148,18 +148,23 @@ This course also features a built-in interpreter for receiving instant feedback
`Learn to Program in Python with Codeacademy `_
-Advanced
---------
+Intermediate
+------------
+
Effective Python
~~~~~~~~~~~~~~~~
-This book contains 59 specific ways to improve writing Pythonic code. At 227
-pages, it is a very brief overview of some of the most commons adapations
-programmers need to make to become efficient intermediate level Python
+This book contains 59 specific ways to improve writing Pythonic code. At 227
+pages, it is a very brief overview of some of the most commons adapations
+programmers need to make to become efficient intermediate level Python
programmers.
`Effective Python `_
+
+Advanced
+--------
+
Pro Python
~~~~~~~~~~
@@ -239,12 +244,12 @@ formal, but rather focuses on explaining the underlying intuition and shows
how to implement the algorithms in Python.
`Programming Collective Intelligence `_
-
-
+
+
Transforming Code into Beautiful, Idiomatic Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Transforming Code into Beautiful, Idiomatic Python is a video by Raymond Hettinger.
+Transforming Code into Beautiful, Idiomatic Python is a video by Raymond Hettinger.
Learn to take better advantage of Python's best features and improve existing code
through a series of code transformations, "When you see this, do that instead."
@@ -255,7 +260,7 @@ Fullstack Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Fullstack Python offers a complete top-to-bottom resource for web development
-using Python.
+using Python.
From setting up the webserver, to designing the front-end, choosing a database,
optimizing/scaling, etc.
@@ -294,7 +299,7 @@ the core language, with descriptions of commonly used modules and toolkits. It
covers Python 3 and 2.6 versions.
`Python Pocket Reference `_
-
+
Python Cookbook
~~~~~~~~~~~~~~~
@@ -315,5 +320,5 @@ 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+ `_
-
+
`For Python 3.3+ `_
From e6fb422d4563f9d018e235442c517a3bf58bfd26 Mon Sep 17 00:00:00 2001
From: Kuldeep Singh
Date: Mon, 25 Jan 2016 22:28:46 +0530
Subject: [PATCH 022/572] Changed xrange to range
Since xrange no longer works in python3
---
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 111206f30..cb2e03086 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -349,7 +349,7 @@ Instead, use a list comprehension:
.. code-block:: python
- four_lists = [[] for __ in xrange(4)]
+ four_lists = [[] for __ in range(4)]
Create a string from a list
~~~~~~~~~~~~~~~~~~~~~~~~~~~
From 7aca6814e24abc97ab76bb75e6dadcf58f6aad7d Mon Sep 17 00:00:00 2001
From: Kuldeep Singh
Date: Mon, 25 Jan 2016 23:09:42 +0530
Subject: [PATCH 023/572] Added Note for xrange
Python 3 does not have xrange(). Uses range() instead.
---
docs/writing/style.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index cb2e03086..042bdce2e 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -349,7 +349,9 @@ Instead, use a list comprehension:
.. code-block:: python
- four_lists = [[] for __ in range(4)]
+ four_lists = [[] for __ in xrange(4)]
+
+Note: Use range() instead of xrange() in Python 3
Create a string from a list
~~~~~~~~~~~~~~~~~~~~~~~~~~~
From c48ec0657a3c1029dad951f2accf7cff56ccf2a6 Mon Sep 17 00:00:00 2001
From: Tridev
Date: Tue, 26 Jan 2016 09:39:49 +0530
Subject: [PATCH 024/572] Update conf.py
update at line 49 to the issue #646
---
docs/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/conf.py b/docs/conf.py
index 811579743..f8ad7113b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -46,7 +46,7 @@
# General information about the project.
project = u'pythonguide'
-copyright = u'2016. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0'
+copyright = u'2016. A Kenneth Reitz Project. Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported (by-nc-sa)'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
From abab81deb7b8aacf4d8329f4de1c51acbe7f10a1 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Tue, 26 Jan 2016 18:02:52 -0500
Subject: [PATCH 025/572] Update conf.py
---
docs/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/conf.py b/docs/conf.py
index f8ad7113b..e86da8d0d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -46,7 +46,7 @@
# General information about the project.
project = u'pythonguide'
-copyright = u'2016. A Kenneth Reitz Project. Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported (by-nc-sa)'
+copyright = u'2016. A Kenneth Reitz Project. Creative Commons'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
From 13bf0aefa0456b6405cf7f4b131e9fc9ec422632 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Tue, 26 Jan 2016 18:04:22 -0500
Subject: [PATCH 026/572] Update conf.py
---
docs/conf.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index e86da8d0d..a56a4607a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -46,7 +46,7 @@
# General information about the project.
project = u'pythonguide'
-copyright = u'2016. A Kenneth Reitz Project. Creative Commons'
+copyright = u'2016. A Kenneth Reitz Project. CC BY-NC-SA 3.0'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -234,7 +234,7 @@
epub_title = u'pythonguide'
epub_author = u'Kenneth Reitz'
epub_publisher = u'Kenneth Reitz'
-epub_copyright = u'2014, Kenneth Reitz'
+epub_copyright = u'2016, Kenneth Reitz'
# The language of the text. It defaults to the language option
# or en if the language is not set.
From b3ce58c58e24b31f33cd55f57dccc7398057c605 Mon Sep 17 00:00:00 2001
From: Shichao An
Date: Tue, 26 Jan 2016 15:28:48 -0800
Subject: [PATCH 027/572] Added Python Essential Reference to learning.rst
---
docs/intro/learning.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
index 2eb88d90d..d7266b87c 100644
--- a/docs/intro/learning.rst
+++ b/docs/intro/learning.rst
@@ -291,6 +291,15 @@ of the language.
`The Python Language Reference `_
+Python Essential Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python Essential Reference, written by David Beazley, is the definitive reference
+guide to Python. It concisely explains both the core language and the most essential
+parts of the standard library. It covers Python 3 and 2.6 versions.
+
+ `Python Essential Reference `_
+
Python Pocket Reference
~~~~~~~~~~~~~~~~~~~~~~~
From 5a2374d093b0bb8f26d3d9bfb8f29b5d28b5da29 Mon Sep 17 00:00:00 2001
From: Romain Catajar
Date: Wed, 27 Jan 2016 17:52:53 +0100
Subject: [PATCH 028/572] Fix varibable name in XML parsing scenario
In the xmltodict example, the xml is loaded in the variable obj but is later referenced as doc.
Fixed by renaming obj to doc
---
docs/scenarios/xml.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst
index 7484413a9..0cc3cdc4c 100644
--- a/docs/scenarios/xml.rst
+++ b/docs/scenarios/xml.rst
@@ -59,7 +59,7 @@ can be loaded into a Python dict like this:
import xmltodict
with open('path/to/file.xml') as fd:
- obj = xmltodict.parse(fd.read())
+ doc = xmltodict.parse(fd.read())
and then you can access elements, attributes and values like this:
From 4e5b195371d6ddeddd573f19cdd11bcaa530e9a1 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Sat, 13 Feb 2016 03:39:06 -0500
Subject: [PATCH 029/572] Update freezing.rst
---
docs/shipping/freezing.rst | 30 +++++++++++++++++-------------
1 file changed, 17 insertions(+), 13 deletions(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 7664ad30e..6c0e30cc3 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -4,21 +4,25 @@
Freezing Your Code
==================
-To 'Freeze' your code is to distribute to end-users as an executable which
-includes a bundled Python interpreter.
+'Freezing' your code is creating a single-file executable file to distribute
+to end-users, that contains all of your application code as well as the
+Python interpreter.
-Applications such as 'Dropbox', BitTorrent clients, 'Eve Online' and
-'Civilisation IV' do this.
+Applications such as 'Dropbox', 'Eve Online', 'Civilisation IV', and
+BitTorrent clients do this.
-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
+The advantage of distributing this way is that your application will "just work",
+even if the user doesn't already have the required version of Python installed.
+On Windows, and even on many Linux distributions and OS X, 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 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.
+Besides, end-user software should always be in an executable format. Files
+ending in ``.py`` are for software engineers and system administrators.
+
+One disadvantage of freezing is that it will increase the size of your
+distribution by about 2–12MB. Also, you will be responsible for shipping
+updated versions of your application when security vulnerabilities to
+Python are patched.
Alternatives to Freezing
------------------------
@@ -33,8 +37,8 @@ On Linux, an alternative to freezing is to
.. todo:: Fill in "Freezing Your Code" stub
-Comparison
-----------
+Comparison of Freezing Tools
+----------------------------
Solutions and platforms/features supported:
From c2c49f08fc721789a5dc17365f7d3d97f3339eb8 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Sat, 13 Feb 2016 03:39:21 -0500
Subject: [PATCH 030/572] Update freezing.rst
---
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 6c0e30cc3..346816b0c 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -4,7 +4,7 @@
Freezing Your Code
==================
-'Freezing' your code is creating a single-file executable file to distribute
+"Freezing" your code is creating a single-file executable file to distribute
to end-users, that contains all of your application code as well as the
Python interpreter.
From 2b44ee34c89714c7a1f58e5139c7971a8063bc24 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Sat, 13 Feb 2016 03:39:54 -0500
Subject: [PATCH 031/572] Update freezing.rst
---
docs/shipping/freezing.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
index 346816b0c..d42f2d61b 100644
--- a/docs/shipping/freezing.rst
+++ b/docs/shipping/freezing.rst
@@ -12,8 +12,8 @@ Applications such as 'Dropbox', 'Eve Online', 'Civilisation IV', and
BitTorrent clients do this.
The advantage of distributing this way is that your application will "just work",
-even if the user doesn't already have the required version of Python installed.
-On Windows, and even on many Linux distributions and OS X, the right
+even if the user doesn't already have the required version of Python (or any)
+installed. On Windows, and even on many Linux distributions and OS X, the right
version of Python will not already be installed.
Besides, end-user software should always be in an executable format. Files
From 2c849a96ff61d8f5b9e7f251ee811370df8378bd Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Sat, 13 Feb 2016 09:48:54 -0500
Subject: [PATCH 032/572] Structure of the Repository
---
docs/writing/structure.rst | 293 ++++++++++++++++++++++++++++++++++++-
1 file changed, 291 insertions(+), 2 deletions(-)
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
index a78b7cb61..35e9d030d 100644
--- a/docs/writing/structure.rst
+++ b/docs/writing/structure.rst
@@ -19,8 +19,297 @@ project. We then discuss various perspectives on how to build code which
can be extended and tested reliably.
-Structure is Key
-----------------
+
+Structure of the Repository
+---------------------------
+
+It's Important.
+:::::::::::::::
+
+Just as Code Style, API Design, and Automation are essential for a
+healthy development cycle, Repository structure is a crucial part of
+your project's
+`architecture `__.
+
+When a potential user or contributor lands on your repository's page,
+they see a few things:
+
+- Project Name
+- Project Description
+- Bunch O' Files
+
+Only when they scroll below the fold will the user see your project's
+README.
+
+If your repo is a massive dump of files or a nested mess of directories,
+they might look elsewhere before even reading your beautiful
+documentation.
+
+ Dress for the job you want, not the job you have.
+
+Of course, first impressions aren't everything. You and your colleagues
+will spend countless hours working with this repository, eventually
+becoming intimately familiar with every nook and cranny. The layout of
+it is important.
+
+Sample Repository
+:::::::::::::::::
+
+**tl;dr**: This is what `Kenneth Reitz `_ recommends.
+
+This repository is `available on
+GitHub `__.
+
+::
+
+ README.rst
+ LICENSE
+ setup.py
+ requirements.txt
+ sample/__init__.py
+ sample/core.py
+ sample/helpers.py
+ docs/conf.py
+ docs/index.rst
+ tests/test_basic.py
+ tests/test_advanced.py
+
+Let's get into some specifics.
+
+The Actual Module
+:::::::::::::::::
+
+.. csv-table::
+ :widths: 20, 40
+
+ "Location", "``./sample/`` or ``./sample.py``"
+ "Purpose", "The code of interest"
+
+
+Your module package is the core focus of the repository. It should not
+be tucked away:
+
+::
+
+ ./sample/
+
+If your module consists of only a single file, you can place it directly
+in the root of your repository:
+
+::
+
+ ./sample.py
+
+Your library does not belong in an ambiguous src or python subdirectory.
+
+License
+:::::::
+
+
+.. csv-table::
+ :widths: 20, 40
+
+ "Location", "``./LICENSE``"
+ "Purpose", "Lawyering up."
+
+
+This is arguably the most important part of your repository, aside from
+the source code itself. The full license text and copyright claims
+should exist in this file.
+
+If you aren't sure which license you should use for your project, check
+out `choosealicense.com `_.
+
+Of course, you are also free to publish code without a license, but this
+would prevent many people from potentially using your code.
+
+Setup.py
+::::::::
+
+.. csv-table::
+ :widths: 20, 40
+
+ "Location", "``./setup.py``"
+ "Purpose", "Package and distribution management."
+
+
+If your module package is at the root of your repository, this should
+obviously be at the root as well.
+
+Requirements File
+:::::::::::::::::
+
+.. csv-table::
+ :widths: 20, 40
+
+ "Location", "``./requirements.txt``"
+ "Purpose", "Development dependencies."
+
+
+A `pip requirements
+file `__
+should be placed at the root of the repository. It should specify the
+dependencies required to contribute to the project: testing, building,
+and generating documentation.
+
+If your project has no development dependencies, or you prefer
+development environment setup via ``setup.py``, this file may be
+unnecessary.
+
+Documentation
+:::::::::::::
+
+
+.. csv-table::
+ :widths: 20, 40
+
+ "Location", "``./docs/``"
+ "Purpose", "Package reference documentation."
+
+There is little reason for this to exist elsewhere.
+
+Test Suite
+::::::::::
+
+
+.. csv-table::
+ :widths: 20, 40
+
+ "Location", "``./test_sample.py`` or ``./tests``"
+ "Purpose", "Package integration and unit tests."
+
+Starting out, a small test suite will often exist in a single file:
+
+::
+
+ ./test_sample.py
+
+Once a test suite grows, you can move your tests to a directory, like
+so:
+
+::
+
+ tests/test_basic.py
+ tests/test_advanced.py
+
+Obviously, these test modules must import your packaged module to test
+it. You can do this a few ways:
+
+- Expect the package to be installed in site-packages.
+- Use a simple (but *explicit*) path modification to resolve the
+ package properly.
+
+I highly recommend the latter. Requiring a developer to run
+`setup.py `__ develop to test an actively changing
+codebase also requires them to have an isolated environment setup for
+each instance of the codebase.
+
+To give the individual tests import context, create a tests/context.py
+file:
+
+::
+
+ import os
+ import sys
+ sys.path.insert(0, os.path.abspath('..'))
+
+ import sample
+
+Then, within the individual test modules, import the module like so:
+
+::
+
+ from .context import sample
+
+This will always work as expected, regardless of installation method.
+
+Some people will assert that you should distribute your tests within
+your module itself -- I disagree. It often increases complexity for your
+users; many test suites often require additional dependencies and
+runtime contexts.
+
+Makefile
+::::::::
+
+
+.. csv-table::
+ :widths: 20, 40
+
+ "Location", "``./Makefile``"
+ "Purpose", "Generic management tasks."
+
+
+If you look at most of my projects or any Pocoo project, you'll notice a
+Makefile laying around. Why? These projects aren't written in C... In
+short, make is a incredibly useful tool for defining generic tasks for
+your project.
+
+**Sample Makefile:**
+
+::
+
+ init:
+ pip install -r requirements.txt
+
+ test:
+ py.test tests
+
+Other generic management scripts (e.g. ``manage.py``
+or ``fabfile.py``) belong at the root of the repository as well.
+
+Regarding Django Applications
+:::::::::::::::::::::::::::::
+
+I've noticed a new trend in Django applications since the release of
+Django 1.4. Many developers are structuring their repositories poorly
+due to the new bundled application templates.
+
+How? Well, they go to their bare and fresh repository and run the
+following, as they always have:
+
+::
+
+ $ django-admin.py start-project samplesite
+
+The resulting repository structure looks like this:
+
+::
+
+ README.rst
+ samplesite/manage.py
+ samplesite/samplesite/settings.py
+ samplesite/samplesite/wsgi.py
+ samplesite/samplesite/sampleapp/models.py
+
+Don't do this.
+
+Repetitive paths are confusing for both your tools and your developers.
+Unnecessary nesting doesn't help anybody (unless they're nostalgic for
+monolithic SVN repos).
+
+Let's do it properly:
+
+::
+
+ $ django-admin.py start-project samplesite .
+
+Note the "``.``".
+
+The resulting structure:
+
+::
+
+ README.rst
+ manage.py
+ samplesite/settings.py
+ samplesite/wsgi.py
+ samplesite/sampleapp/models.py
+
+
+
+
+Structure of Code is Key
+------------------------
Thanks to the way imports and modules are handled in Python, it is
relatively easy to structure a Python project. Easy, here, means
From 7938a99f2e66c2bd1daf8a23709998c62abf2a5c Mon Sep 17 00:00:00 2001
From: Ryan Malecky
Date: Sun, 21 Feb 2016 13:54:15 -0500
Subject: [PATCH 033/572] Updated documentation.rst - pycco homepage moved
---
docs/writing/documentation.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
index 8b5701f1b..c6905e334 100644
--- a/docs/writing/documentation.rst
+++ b/docs/writing/documentation.rst
@@ -154,7 +154,7 @@ Pycco_
and is a port of the node.js Docco_. It makes code into a
side-by-side HTML code and documentation.
-.. _Pycco: http://fitzgen.github.com/pycco
+.. _Pycco: https://pycco-docs.github.io/pycco/
.. _Docco: http://jashkenas.github.com/docco
Ronn_
From c4b0ab67317b2af56f6742a93396eb18842c6f26 Mon Sep 17 00:00:00 2001
From: Kenneth Reitz
Date: Sun, 21 Feb 2016 18:26:40 -0500
Subject: [PATCH 034/572] remove old theme
---
docs/_themes/README.rst | 25 -
docs/_themes/kr/layout.html | 50 --
docs/_themes/kr/relations.html | 19 -
docs/_themes/kr/static/flasky.css_t | 535 ----------------------
docs/_themes/kr/static/small_flask.css | 70 ---
docs/_themes/kr/theme.conf | 7 -
docs/_themes/kr_small/layout.html | 22 -
docs/_themes/kr_small/static/flasky.css_t | 287 ------------
docs/_themes/kr_small/theme.conf | 10 -
9 files changed, 1025 deletions(-)
delete mode 100644 docs/_themes/README.rst
delete mode 100644 docs/_themes/kr/layout.html
delete mode 100644 docs/_themes/kr/relations.html
delete mode 100644 docs/_themes/kr/static/flasky.css_t
delete mode 100644 docs/_themes/kr/static/small_flask.css
delete mode 100644 docs/_themes/kr/theme.conf
delete mode 100644 docs/_themes/kr_small/layout.html
delete mode 100644 docs/_themes/kr_small/static/flasky.css_t
delete mode 100644 docs/_themes/kr_small/theme.conf
diff --git a/docs/_themes/README.rst b/docs/_themes/README.rst
deleted file mode 100644
index ac398041a..000000000
--- a/docs/_themes/README.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-krTheme Sphinx Style
-====================
-
-This repository contains sphinx styles Kenneth Reitz uses in most of
-his projects. It is a derivative of Mitsuhiko's themes for Flask and Flask related
-projects. To use this style in your Sphinx documentation, follow
-this guide:
-
-1. put this folder as _themes into your docs folder. Alternatively
- you can also use git submodules to check out the contents there.
-
-2. add this to your :file:`conf.py`: ::
-
- sys.path.append(os.path.abspath('_themes'))
- html_theme_path = ['_themes']
- html_theme = 'flask'
-
-The following themes exist:
-
-**kr**
- the standard flask documentation theme for large projects
-
-**kr_small**
- small one-page theme. Intended to be used by very small addon libraries.
-
diff --git a/docs/_themes/kr/layout.html b/docs/_themes/kr/layout.html
deleted file mode 100644
index 54f270d0b..000000000
--- a/docs/_themes/kr/layout.html
+++ /dev/null
@@ -1,50 +0,0 @@
-{%- extends "basic/layout.html" %}
-{%- block extrahead %}
- {{ super() }}
- {% if theme_touch_icon %}
-
- {% endif %}
-
-{% endblock %}
-{%- block relbar2 %}{% endblock %}
-{%- block footer %}
-
-
-
-
-
-
-
-
-
-
-
-{%- endblock %}
diff --git a/docs/_themes/kr/relations.html b/docs/_themes/kr/relations.html
deleted file mode 100644
index 3bbcde85b..000000000
--- a/docs/_themes/kr/relations.html
+++ /dev/null
@@ -1,19 +0,0 @@
-