From c95f0d010b64570203c9e57bc54ffd5d5ac4c791 Mon Sep 17 00:00:00 2001
From: Mahan Marwat
Date: Sat, 3 Oct 2015 10:38:14 +0500
Subject: [PATCH 001/586] 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/586] 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 a5510abc65fdd41d5e6851ba54132dc47c7a8f31 Mon Sep 17 00:00:00 2001
From: Sidhant Bhavnani
Date: Thu, 22 Oct 2015 21:27:36 +0530
Subject: [PATCH 003/586] Added Web.py and Web2py
---
docs/scenarios/web.rst | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
index 9a5c7603b..29093d9a6 100644
--- a/docs/scenarios/web.rst
+++ b/docs/scenarios/web.rst
@@ -78,6 +78,22 @@ already exist to suit your needs.
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
+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
+on Reddit.com.
+
+
+Web2py
+------
+A full stack web framework and platform focused in the ease of use. It focuses on
+rapid development, favors convention over configuration approach and follows a
+model–view–controller (MVC) architectural pattern.
+
+
Werkzeug
--------
From 5ce9c8a445c60f3f1da21bd340ab99857d3f0a31 Mon Sep 17 00:00:00 2001
From: Gordon Senesac Jr
Date: Thu, 22 Oct 2015 20:22:57 -0500
Subject: [PATCH 004/586] 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 005/586] 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 006/586] 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 44ca0b19a64e2ad9d591a62bd156790e5761cb8e Mon Sep 17 00:00:00 2001
From: aaron
Date: Mon, 26 Oct 2015 23:42:56 -0500
Subject: [PATCH 007/586] Added clib interface file; populated ctypes
---
docs/scenarios/clibs.rst | 42 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 42 insertions(+)
create mode 100644 docs/scenarios/clibs.rst
diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
new file mode 100644
index 000000000..b3d80bead
--- /dev/null
+++ b/docs/scenarios/clibs.rst
@@ -0,0 +1,42 @@
+Interfacing with C/C++ Libraries
+================================
+
+
+ctypes
+------
+
+`ctypes `_ is the de facto
+library for interfacing with C/C++, and it provides not only full access to
+the native C interface of most major operating systems (e.g., kernel32 on
+Windows, or libc on *nix), but also provides support for loading and
+interfacing with dynamic libraries, such as DLLs or shared objects at runtime.
+It does bring along with it a whole host of types for interacting with system
+APIs, and allows you to rather easily define your own complex types, such
+as structs and unions, and allows you to modify things such as padding and
+alignment, if needed. It can be a bit crufty to use, but in conjunction with
+the `struct `_ module, you
+are essentially provided full control over how your data types get translated
+into something something usable by a C(++).
+
+Struct Equivalents
+~~~~~~~~~~~~~~~~~~
+
+:file:`MyStruct.h`
+
+.. code-block:: c
+ :linenos:
+
+ struct my_struct {
+ int a;
+ int b;
+ };
+
+:file:`MyStruct.py`
+
+.. code-block:: python
+ :linenos:
+
+ import ctypes
+ class my_struct(ctypes.Structure):
+ _fields_ = [("a", c_int),
+ ("b", c_int)]
From 2dea4bc5eecd603ac6332d45eb711078a0fbf767 Mon Sep 17 00:00:00 2001
From: aaron
Date: Mon, 26 Oct 2015 23:45:11 -0500
Subject: [PATCH 008/586] Added sections for SWIG and boost.python
---
docs/scenarios/clibs.rst | 64 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 64 insertions(+)
diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
index b3d80bead..f2e75d3ef 100644
--- a/docs/scenarios/clibs.rst
+++ b/docs/scenarios/clibs.rst
@@ -40,3 +40,67 @@ Struct Equivalents
class my_struct(ctypes.Structure):
_fields_ = [("a", c_int),
("b", c_int)]
+
+SWIG
+----
+
+`SWIG `_, though not strictly Python focused (it supports a
+large number of scripting languages), is a tool for generating bindings for
+interpreted languages from C/C++ header files. It is extremely simple to use:
+the consumer simply needs to define an interface file (detailed in the
+tutorial and documentations), include the requisite C/C++ headers, and run
+the build tool against them. While it does have some limits, (it currently
+seems to have issues with a small subset of newer C++ features, and getting
+template-heavy code to work can be a bit verbose), it provides a great deal
+of power and exposes lots of features to Python with little effort.
+Additionally, you can easily extend the bindings SWIG creates (in the
+interface file) to overload operators and built-in methods, effectively re-
+cast C++ exceptions to be catchable by Python, etc.
+
+Example: Overloading __repr__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:file:`MyClass.h`
+
+.. code-block:: c++
+ :linenos:
+
+ #include
+ class MyClass {
+ private:
+ std::string name;
+ public:
+ std::string getName();
+ };
+
+:file:`myclass.i`
+
+.. code-block:: c++
+ :linenos:
+
+ %include "string.i"
+
+ %module myclass
+ %{
+ #include
+ #include "MyClass.h"
+ %}
+
+ %extend MyClass {
+ std::string __repr__()
+ {
+ return $self->getName();
+ }
+ }
+
+ %include "MyClass.h"
+
+
+Boost.Python
+------------
+
+`Boost.Python `_
+requires a bit more manual work to expose C++ object functionality, but
+it is capable of providing all the same features SWIG does, and then some,
+to include providing wrappers to access PyObjects in C++, extracting SWIG-
+wrapper objects, and even embedding bits of Python into your C++ code.
From b1b5f95cdf20f0f912088dc1a824912c80a2d66f Mon Sep 17 00:00:00 2001
From: aaron
Date: Mon, 26 Oct 2015 23:46:19 -0500
Subject: [PATCH 009/586] Added new file to list of scenarios
---
docs/contents.rst.inc | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index b312ee3e6..17cf00346 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -62,6 +62,7 @@ different scenarios.
scenarios/xml
scenarios/json
scenarios/crypto
+ scenarios/clibs
Shipping Great Code
From 599200c023b59fbe86a364ff4d450b1113426563 Mon Sep 17 00:00:00 2001
From: aaron
Date: Mon, 26 Oct 2015 23:52:03 -0500
Subject: [PATCH 010/586] Edited for typos
---
docs/scenarios/clibs.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
index f2e75d3ef..5d20fa481 100644
--- a/docs/scenarios/clibs.rst
+++ b/docs/scenarios/clibs.rst
@@ -16,7 +16,7 @@ as structs and unions, and allows you to modify things such as padding and
alignment, if needed. It can be a bit crufty to use, but in conjunction with
the `struct `_ module, you
are essentially provided full control over how your data types get translated
-into something something usable by a C(++).
+into something usable by a pure C(++) method.
Struct Equivalents
~~~~~~~~~~~~~~~~~~
@@ -101,6 +101,6 @@ Boost.Python
`Boost.Python `_
requires a bit more manual work to expose C++ object functionality, but
-it is capable of providing all the same features SWIG does, and then some,
+it is capable of providing all the same features SWIG does and then some,
to include providing wrappers to access PyObjects in C++, extracting SWIG-
wrapper objects, and even embedding bits of Python into your C++ code.
From 7c6848beb6575790a5f28d7be83ca3ddc9269f8a Mon Sep 17 00:00:00 2001
From: Steven Bock
Date: Tue, 27 Oct 2015 21:53:06 -0700
Subject: [PATCH 011/586] 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 012/586] 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 2527b7c5e56b75b4b0803c94908d69246023dbc8 Mon Sep 17 00:00:00 2001
From: Navdeep Singh
Date: Sat, 24 Oct 2015 19:53:48 +0530
Subject: [PATCH 013/586] Add space missing between operating and system
---
docs/scenarios/admin.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
index 954e1f6ad..8ca87e2af 100644
--- a/docs/scenarios/admin.rst
+++ b/docs/scenarios/admin.rst
@@ -290,7 +290,7 @@ 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
+Here is another example with system based logic. Note how the operating system
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``
From fd846d8820b1a2390a698d464a0974dc88d7fb35 Mon Sep 17 00:00:00 2001
From: Navdeep Singh
Date: Mon, 26 Oct 2015 02:15:36 +0530
Subject: [PATCH 014/586] Add short description of Buildout
---
docs/conf.py | 2 +-
docs/scenarios/admin.rst | 11 ++++++++---
2 files changed, 9 insertions(+), 4 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index b4d183314..99c1c59a8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -251,7 +251,7 @@
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
-# HTML files shat should be inserted after the pages created by sphinx.
+# HTML files that should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
index 8ca87e2af..28520baa1 100644
--- a/docs/scenarios/admin.rst
+++ b/docs/scenarios/admin.rst
@@ -345,7 +345,12 @@ Blueprint
Buildout
--------
-.. todo:: Write about Buildout
-
- `Buildout Website `_
+`Buildout `_ is an open source software build tool.
+Buildout is created using the Python programming language. It implements a
+principle of separation of configuration from the scripts that do the setting up.
+Buildout is primarily used to download and set up dependencies in Python eggs
+format of the software being developed or deployed. Recipes for build tasks in any
+environment can be created, and many are already available.
+
+Buidout is written in Python.
From 5714d409e3dfc4cc0cc66a4f735e95e73cbcee07 Mon Sep 17 00:00:00 2001
From: Shiven Mian
Date: Mon, 26 Oct 2015 16:05:01 +0530
Subject: [PATCH 015/586] Added OpenCV to Image Processing
---
docs/scenarios/imaging.rst | 51 +++++++++++++++++++++++++++++++++++++-
1 file changed, 50 insertions(+), 1 deletion(-)
diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst
index 7ae952d37..4b517b79a 100644
--- a/docs/scenarios/imaging.rst
+++ b/docs/scenarios/imaging.rst
@@ -5,11 +5,16 @@ Image Manipulation
.. todo::
Add introduction about image manipulation and its Python libraries.
+Most image processing and manipulation techniques can be carried out effectively using
+two libraries: Python Imaging Library (PIL) and OpenSource Computer Vision (OpenCV).
+
+A brief description of both is given below.
+
Python Imaging Library
----------------------
The `Python Imaging Library `_, or PIL
-for short, is *the* library for image manipulation in Python. Unfortunately,
+for short, is one of the core libraries 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
@@ -55,3 +60,47 @@ Example
There are more examples of the Pillow library in the
`Pillow tutorial `_.
+
+
+OpenSource Computer Vision
+---------------------------
+
+OpenSource Computer Vision, or OpenCV in short, is a slightly more advanced and useful
+image manipulation and processing software than PIL. It has been implemented in several
+languages and is very widely used.
+
+Installation
+~~~~~~~~~~~~~
+
+In Python, image processing using OpenCV is implemented using the **cv2** and **NumPy** modules.
+Check the installation instructions for OpenCV `here `_.
+
+NumPy can be easily downloaded from the Python Package Index(PyPI):
+
+.. code-block:: console
+
+ $ pip install numpy
+
+Example
+~~~~~~~~
+
+.. code-block:: python
+
+ from cv2 import *
+ import numpy as np
+ #Read Image
+ img = cv2.imread('testimg.jpg')
+ #Display Image
+ cv2.imshow('image',img)
+ cv2.waitKey(0)
+ cv2.destroyAllWindows()
+
+ #Applying Grayscale filter to image
+ gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+ #Saving filtered image to new file
+ cv2.imwrite('graytest.jpg',gray)
+
+There are more examples of OpenCV in the documentation
+`here `_.
+
From 6d7c9897b939d737c057d6817715d537edf6a6a8 Mon Sep 17 00:00:00 2001
From: Shiven Mian
Date: Mon, 26 Oct 2015 16:23:13 +0530
Subject: [PATCH 016/586] Updated OpenCV
---
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 4b517b79a..4b04859e1 100644
--- a/docs/scenarios/imaging.rst
+++ b/docs/scenarios/imaging.rst
@@ -65,7 +65,7 @@ There are more examples of the Pillow library in the
OpenSource Computer Vision
---------------------------
-OpenSource Computer Vision, or OpenCV in short, is a slightly more advanced and useful
+OpenSource Computer Vision, or OpenCV in short, is a more advanced and useful
image manipulation and processing software than PIL. It has been implemented in several
languages and is very widely used.
From dff8f0d9437b60a1d624704545dc96b4439e5559 Mon Sep 17 00:00:00 2001
From: Shiven Mian
Date: Sat, 31 Oct 2015 20:21:50 +0530
Subject: [PATCH 017/586] Fixed duplicate target name
Address review comments on content of additions and match section title
styling of the rest of the guide.
---
docs/scenarios/imaging.rst | 21 ++++++++++-----------
1 file changed, 10 insertions(+), 11 deletions(-)
diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst
index 4b04859e1..4dbe4274a 100644
--- a/docs/scenarios/imaging.rst
+++ b/docs/scenarios/imaging.rst
@@ -63,26 +63,26 @@ There are more examples of the Pillow library in the
OpenSource Computer Vision
----------------------------
+--------------------------
-OpenSource Computer Vision, or OpenCV in short, is a more advanced and useful
-image manipulation and processing software than PIL. It has been implemented in several
-languages and is very widely used.
+OpenSource Computer Vision, more commonly known as OpenCV, is a more advanced image manipulation and processing software than PIL. It has been implemented in several
+languages and is widely used.
Installation
-~~~~~~~~~~~~~
+~~~~~~~~~~~~
-In Python, image processing using OpenCV is implemented using the **cv2** and **NumPy** modules.
-Check the installation instructions for OpenCV `here `_.
+In Python, image processing using OpenCV is implemented using the ``cv2`` and ``NumPy`` modules.
+The `installation instructions for OpenCV `_ should guide you through configuring the project for yourself.
-NumPy can be easily downloaded from the Python Package Index(PyPI):
+NumPy can be downloaded from the Python Package Index(PyPI):
.. code-block:: console
$ pip install numpy
+
Example
-~~~~~~~~
+~~~~~~~
.. code-block:: python
@@ -101,6 +101,5 @@ Example
#Saving filtered image to new file
cv2.imwrite('graytest.jpg',gray)
-There are more examples of OpenCV in the documentation
-`here `_.
+There are more Python-implemented examples of OpenCV in this `collection of tutorials `_.
From de12022fc3ff559f6a9325ef1bb915bb70897f32 Mon Sep 17 00:00:00 2001
From: Ian Cordasco
Date: Sat, 31 Oct 2015 10:55:15 -0500
Subject: [PATCH 018/586] Fix line wrapping from #625
Strip trailing whitespace
(cherry picked from commit 932a66a78bac5b41f723758ba6dd6489c1346215)
---
docs/scenarios/imaging.rst | 64 ++++++++++++++++++++------------------
1 file changed, 33 insertions(+), 31 deletions(-)
diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst
index 4dbe4274a..23ecece49 100644
--- a/docs/scenarios/imaging.rst
+++ b/docs/scenarios/imaging.rst
@@ -2,11 +2,9 @@
Image Manipulation
==================
-.. todo::
- Add introduction about image manipulation and its Python libraries.
-
-Most image processing and manipulation techniques can be carried out effectively using
-two libraries: Python Imaging Library (PIL) and OpenSource Computer Vision (OpenCV).
+Most image processing and manipulation techniques can be carried out
+effectively using two libraries: Python Imaging Library (PIL) and OpenSource
+Computer Vision (OpenCV).
A brief description of both is given below.
@@ -39,24 +37,24 @@ Example
.. code-block:: python
- from PIL import Image, ImageFilter
- #Read image
- im = Image.open( 'image.jpg' )
- #Display image
- im.show()
+ from PIL import Image, ImageFilter
+ #Read image
+ im = Image.open( 'image.jpg' )
+ #Display image
+ im.show()
- #Applying a filter to the image
- im_sharp = im.filter( ImageFilter.SHARPEN )
- #Saving the filtered image to a new file
- im_sharp.save( 'image_sharpened.jpg', 'JPEG' )
+ #Applying a filter to the image
+ im_sharp = im.filter( ImageFilter.SHARPEN )
+ #Saving the filtered image to a new file
+ im_sharp.save( 'image_sharpened.jpg', 'JPEG' )
- #Splitting the image into its respective bands, i.e. Red, Green,
- #and Blue for RGB
- r,g,b = im_sharp.split()
+ #Splitting the image into its respective bands, i.e. Red, Green,
+ #and Blue for RGB
+ r,g,b = im_sharp.split()
- #Viewing EXIF data embedded in image
- exif_data = im._getexif()
- exif_data
+ #Viewing EXIF data embedded in image
+ exif_data = im._getexif()
+ exif_data
There are more examples of the Pillow library in the
`Pillow tutorial `_.
@@ -65,20 +63,23 @@ There are more examples of the Pillow library in the
OpenSource Computer Vision
--------------------------
-OpenSource Computer Vision, more commonly known as OpenCV, is a more advanced image manipulation and processing software than PIL. It has been implemented in several
-languages and is widely used.
+OpenSource Computer Vision, more commonly known as OpenCV, is a more advanced
+image manipulation and processing software than PIL. It has been implemented
+in several languages and is widely used.
Installation
~~~~~~~~~~~~
-In Python, image processing using OpenCV is implemented using the ``cv2`` and ``NumPy`` modules.
-The `installation instructions for OpenCV `_ should guide you through configuring the project for yourself.
+In Python, image processing using OpenCV is implemented using the ``cv2`` and
+``NumPy`` modules. The `installation instructions for OpenCV
+`_
+should guide you through configuring the project for yourself.
NumPy can be downloaded from the Python Package Index(PyPI):
.. code-block:: console
-
- $ pip install numpy
+
+ $ pip install numpy
Example
@@ -87,7 +88,7 @@ Example
.. code-block:: python
from cv2 import *
- import numpy as np
+ import numpy as np
#Read Image
img = cv2.imread('testimg.jpg')
#Display Image
@@ -97,9 +98,10 @@ Example
#Applying Grayscale filter to image
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
-
- #Saving filtered image to new file
- cv2.imwrite('graytest.jpg',gray)
-There are more Python-implemented examples of OpenCV in this `collection of tutorials `_.
+ #Saving filtered image to new file
+ cv2.imwrite('graytest.jpg',gray)
+There are more Python-implemented examples of OpenCV in this `collection of
+tutorials
+`_.
From 7d0139a2483bdd68811de8669daac07e9fd8d125 Mon Sep 17 00:00:00 2001
From: aaron
Date: Sun, 1 Nov 2015 08:41:27 -0600
Subject: [PATCH 019/586] Modified ctypes entry for clarity
---
docs/scenarios/clibs.rst | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
index 5d20fa481..3f92627d5 100644
--- a/docs/scenarios/clibs.rst
+++ b/docs/scenarios/clibs.rst
@@ -5,18 +5,18 @@ Interfacing with C/C++ Libraries
ctypes
------
-`ctypes `_ is the de facto
-library for interfacing with C/C++, and it provides not only full access to
-the native C interface of most major operating systems (e.g., kernel32 on
-Windows, or libc on *nix), but also provides support for loading and
-interfacing with dynamic libraries, such as DLLs or shared objects at runtime.
-It does bring along with it a whole host of types for interacting with system
-APIs, and allows you to rather easily define your own complex types, such
-as structs and unions, and allows you to modify things such as padding and
-alignment, if needed. It can be a bit crufty to use, but in conjunction with
-the `struct `_ module, you
-are essentially provided full control over how your data types get translated
-into something usable by a pure C(++) method.
+`ctypes `_ is the CPython
+included library for interfacing with C/C++, and it provides not only full
+access to the native C interface of most major operating systems (e.g.,
+kernel32 on Windows, or libc on *nix), but also provides support for loading
+and interfacing with dynamic libraries, such as DLLs or shared objects at
+runtime. It does bring along with it a whole host of types for interacting
+with system APIs, and allows you to rather easily define your own complex
+types, such as structs and unions, and allows you to modify things such as
+padding and alignment, if needed. It can be a bit crufty to use, but in
+conjunction with the `struct `_
+module, you are essentially provided full control over how your data types get
+translated into something something usable by a C(++).
Struct Equivalents
~~~~~~~~~~~~~~~~~~
From fc092a1a98bec97de52ba671aa177069a513fa38 Mon Sep 17 00:00:00 2001
From: aaron
Date: Sun, 1 Nov 2015 11:40:05 -0600
Subject: [PATCH 020/586] Added CFFI section
---
docs/scenarios/clibs.rst | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
index 3f92627d5..c4d4110d7 100644
--- a/docs/scenarios/clibs.rst
+++ b/docs/scenarios/clibs.rst
@@ -1,6 +1,29 @@
Interfacing with C/C++ Libraries
================================
+C Foreign Function Interface
+----------------------------
+
+`CFFI `_ provides a simple to use
+mechanism for interfacing with C from both CPython and PyPy. It supports two
+modes: an inline ABI compatibility mode (example provided below), which allows
+you to dynamically load and run functions from executable modules (essentially
+exposing the same functionality as LoadLibrary or dlopen), and an API mode,
+which allows you to build C extension modules.
+
+ABI Interaction
+~~~~~~~~~~~~~~~
+
+.. code-block:: python
+ :linenos:
+
+ from cffi import FFI
+ ffi = FFI()
+ ffi.cdef("size_t strlen(const char*);")
+ clib = ffi.dlopen(None)
+ length = clib.strlen("String to be evaluated.")
+ # prints: 23
+ print("{}".format(length))
ctypes
------
From 3f0508403e12dcae6e7eb7a995957ca0f1f1c0a2 Mon Sep 17 00:00:00 2001
From: aaron
Date: Sun, 1 Nov 2015 13:33:47 -0600
Subject: [PATCH 021/586] Fixed a formatting issue introduced in ctypes
---
docs/scenarios/clibs.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
index c4d4110d7..290638e73 100644
--- a/docs/scenarios/clibs.rst
+++ b/docs/scenarios/clibs.rst
@@ -28,10 +28,10 @@ ABI Interaction
ctypes
------
-`ctypes `_ is the CPython
-included library for interfacing with C/C++, and it provides not only full
-access to the native C interface of most major operating systems (e.g.,
-kernel32 on Windows, or libc on *nix), but also provides support for loading
+`ctypes `_ is the de facto
+library for interfacing with C/C++ from CPython, and it provides not only
+full access to the native C interface of most major operating systems (e.g.,
+kernel32 on Windows, or libc on \*nix), but also provides support for loading
and interfacing with dynamic libraries, such as DLLs or shared objects at
runtime. It does bring along with it a whole host of types for interacting
with system APIs, and allows you to rather easily define your own complex
@@ -39,7 +39,7 @@ types, such as structs and unions, and allows you to modify things such as
padding and alignment, if needed. It can be a bit crufty to use, but in
conjunction with the `struct `_
module, you are essentially provided full control over how your data types get
-translated into something something usable by a C(++).
+translated into something something usable by a pure C(++) method.
Struct Equivalents
~~~~~~~~~~~~~~~~~~
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 022/586] 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 023/586] 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 024/586] 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 026/586] 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 027/586] 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 028/586] 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 029/586] 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 030/586] 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 031/586] 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 032/586] 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 033/586] 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 034/586] 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 035/586] 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 036/586] 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 037/586] 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 038/586] 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 039/586] 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 040/586] 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 041/586] 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 042/586] 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 043/586] 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 044/586] 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 045/586] 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 046/586] 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 047/586] 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 048/586] 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 @@
-