From 4e1b3771e5a12eeb4c250db28357d016121e9204 Mon Sep 17 00:00:00 2001 From: kuyan Date: Mon, 14 Oct 2013 15:20:29 -0700 Subject: [PATCH 01/63] Link to `fpm` (see #328) --- docs/shipping/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index e91bb33..466665a 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -78,5 +78,5 @@ For Linux Distributions Useful Tools ------------ -- epm +- `fpm `_ - alien From eb950d52c96a4a0a468e5db3b143a0644646e70f Mon Sep 17 00:00:00 2001 From: Jens Rantil Date: Mon, 28 Oct 2013 23:15:38 +0100 Subject: [PATCH 02/63] Link to `alien` This fully fixes #328. --- docs/shipping/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 466665a..ef7df67 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -79,4 +79,4 @@ Useful Tools ------------ - `fpm `_ -- alien +- `alien `_ From 00619354b8f742d2e9c0b86f92640a571a260069 Mon Sep 17 00:00:00 2001 From: Pengkui Luo Date: Sat, 2 Nov 2013 05:56:54 -0500 Subject: [PATCH 03/63] PyPy recently released beta support to Python 3. --- docs/starting/which-python.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 2fc8525..0413a89 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -51,7 +51,7 @@ that rely on C extensions for their functionality (e.g. numpy) then CPython is your only choice. Being the reference implementation, all versions of the Python language are -available as CPython. Python 3 is only available as a CPython implementation. +available as CPython. PyPy ---- @@ -67,7 +67,8 @@ If you are looking to squeeze more performance out of your Python code, it's worth giving PyPy a try. On a suite of benchmarks, it's currently `over 5 times faster than CPython `_. -Currently PyPy supports Python 2.7. [#pypy_ver]_ +Currently PyPy supports Python 2.7. PyPy3 which targets Python 3 was recently +available as a beta release. [#pypy_ver]_ Jython ------ From 12fe8d779bbec515aeb359a4e3e3be329fe433fe Mon Sep 17 00:00:00 2001 From: Pengkui Luo Date: Sat, 2 Nov 2013 06:19:19 -0500 Subject: [PATCH 04/63] python-2.7.5 is available. --- 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 bdfa3f0..a05893b 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -3,7 +3,7 @@ Installing Python on Windows ============================ -First, download the `latest version `_ +First, download the `latest version `_ of Python 2.7 from the official Website. If you want to be sure you are installing a fully up-to-date version then use the "Windows Installer" link from the home page of the `Python.org web site `_ . From 83630edf35b468dbf96815f02fd25db70141204f Mon Sep 17 00:00:00 2001 From: Pengkui Luo Date: Sat, 2 Nov 2013 06:19:56 -0500 Subject: [PATCH 05/63] typos --- docs/starting/install/win.rst | 2 +- docs/starting/which-python.rst | 4 ++-- docs/writing/structure.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index a05893b..f1d9386 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -80,7 +80,7 @@ project. This is particularly important for Web development, where each framework and application will have many dependencies. -To set up a new Python environment, change the working directory to where ever +To set up a new Python environment, change the working directory to wherever you want to store the environment, and run the virtualenv utility in your project's directory diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 0413a89..cc79c36 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -47,7 +47,7 @@ level of compatibility with Python packages and C extension modules. If you are writing open-source Python code and want to reach the widest possible audience, targeting CPython is your best bet. If you need to use any packages -that rely on C extensions for their functionality (e.g. numpy) then CPython +that rely on C extensions for their functionality (e.g., numpy) then CPython is your only choice. Being the reference implementation, all versions of the Python language are @@ -74,7 +74,7 @@ Jython ------ `Jython `_ is a Python implementation that compiles -Python code to Java byte code that is then executed in a JVM. It has the additional +Python code to Java bytecode that is then executed in a JVM. It has the additional advantage of being able to import and use any Java class like a Python module. diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 9bb685c..0529b21 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -14,7 +14,7 @@ isolated? By answering questions like these you can begin to plan, in a broad sense, what your finished product will look like. In this section we take a closer look at Python's module and import -systems as they are the central element to enforcing structure in your +systems as they are the central elements to enforcing structure in your project. We then discuss various perspectives on how to build code which can be extended and tested reliably. From b3c7bd1ae2dd6f2879426e9fbc1a219d5caf34ea Mon Sep 17 00:00:00 2001 From: Paul Hallett Date: Wed, 6 Nov 2013 12:03:52 +0000 Subject: [PATCH 06/63] Added link to the python packaging guide. --- docs/shipping/packaging.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index e91bb33..7dd2753 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -5,6 +5,8 @@ Packaging your code is important. You'll need to package your code first before sharing it with other developers. +The `Python Packaging Guide `_ provides an extensive guide on creating and maintaining Python packages. + For Python Developers ::::::::::::::::::::: From 387170572a07af5847c09165f09f1ca281a663c5 Mon Sep 17 00:00:00 2001 From: Mher Movsisyan Date: Sat, 9 Nov 2013 18:02:41 +0300 Subject: [PATCH 07/63] The latest OSX version is Mavericks --- docs/starting/install/osx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index dc66767..fa41f8c 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -3,7 +3,7 @@ Installing Python on Mac OS X ============================= -The latest version of Mac OS X, Mountain Lion, **comes with Python 2.7 out of the box**. +The latest version of Mac OS X, Mavericks, **comes with Python 2.7 out of the box**. You do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries From 3f7fb5e75648b059b1fceb5e379aa12c73285eca Mon Sep 17 00:00:00 2001 From: ugurthemaster Date: Mon, 18 Nov 2013 11:16:29 +0200 Subject: [PATCH 08/63] Update learning.rst "Python Pocket Reference" has been added. --- docs/intro/learning.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index b8e31c4..c3c0a22 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -169,3 +169,12 @@ This is Python's reference manual, it covers the syntax and the core semantics o language. `The Python Language Reference `_ + +Python Pocket Reference +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Python Pocket Reference, written by Mark Lutz, is an easy to use reference to the +core language, with descriptions of commonly used modules and toolkits. It covers +Python 3 and 2.6 versions. + + `Python Pocket Reference `_ From 203b92ce617411ed65f9ad4a7c475c14690b83e0 Mon Sep 17 00:00:00 2001 From: ugurthemaster Date: Mon, 25 Nov 2013 11:05:54 +0200 Subject: [PATCH 09/63] Update documentation.rst --- docs/writing/documentation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index d543f53..7793af4 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -94,7 +94,9 @@ Reference`_ should help you familiarize yourself with its syntax. Code Documentation Advice ------------------------- -Comments clarify code and begin with a hash (``#``). +Comments clarify the code and they are added with purpose of making the +code easier to understand. In Python, comments begin with a hash +(number sign) (``#``). .. _docstring-ref: From 83a99468b7ce9c4fd3126984b0df6a2c3db2adbd Mon Sep 17 00:00:00 2001 From: Pengkui Luo Date: Tue, 26 Nov 2013 01:21:26 -0600 Subject: [PATCH 10/63] python-2.7.6 --- 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 f1d9386..b71b882 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -3,7 +3,7 @@ Installing Python on Windows ============================ -First, download the `latest version `_ +First, download the `latest version `_ of Python 2.7 from the official Website. If you want to be sure you are installing a fully up-to-date version then use the "Windows Installer" link from the home page of the `Python.org web site `_ . From bd7147401280c4d079c6b50162d4d5f7f130edf1 Mon Sep 17 00:00:00 2001 From: ugurthemaster Date: Tue, 26 Nov 2013 09:30:18 +0200 Subject: [PATCH 11/63] Update cli.rst Information about Clint has been added. --- docs/scenarios/cli.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 546eae0..933b0f0 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -6,11 +6,14 @@ Command Line Applications Clint ----- -.. todo:: Write about Clint +`clint `_ is a python module which is +filled with very useful tools for developing commandline applications. +It supports features such as; CLI Colors and Indents, Simple and Powerful +Column Printer, Iterator based progress bar and Implicit argument handling. docopt ------ `docopt `_ is a lightweight, highly Pythonic package that allows creating command line interfaces easily and intuitively, by parsing -POSIX-style usage instructions. \ No newline at end of file +POSIX-style usage instructions. From 78016d6cf9b3fdf187719840e2a93392f41be5f4 Mon Sep 17 00:00:00 2001 From: Matt Hughes Date: Mon, 2 Dec 2013 10:50:53 -0500 Subject: [PATCH 12/63] Added instructions for s3-hosted PyPi repo Adapted from an awesome article by @jsutlovic --- docs/shipping/packaging.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index e91bb33..7ffc5ba 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -67,6 +67,36 @@ Chishop written in django which allows you to register/upload with distutils and install with easy_install/pip. +S3-Hosted PyPi +++++++++++++++ + +One simple option for a personal PyPi server is to use Amazon S3. A prerequisite for this is that you have an Amazon AWS account with an S3 bucket. + +1. **Install all your requirements from PyPi or another source** +2. **Install pip2pi** + +* :code:`pip install git+https://github.com/wolever/pip2pi.git` + +3. **Follow pip2pi README for pip2tgz and dir2pi commands** + +* :code:`pip2tgz packages/ YourPackage` (or :code:`pip2tgz packages/ -r requirements.txt`) +* :code:`dir2pi packages/` + +4. **Upload the new files** + +* Use a client like Cyberduck to sync the entire :code:`packages` folder to your s3 bucket +* Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories + +5. **Fix new file permissions** + +* By default, when you upload new files to the S3 bucket, they will have the wrong permissions set. +* Use the Amazon web console to set the READ permission of the files to EVERYONE. +* If you get HTTP 403 when trying to install a package, make sure you've set the permissions correctly. + +6. **All done** + +* You can now your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage` + For Linux Distributions :::::::::::::::::::::::: From 6dfc9ae9530ccebdecd361d7d66a40ca2f8bb5c3 Mon Sep 17 00:00:00 2001 From: Natan L Date: Mon, 2 Dec 2013 22:58:17 -0800 Subject: [PATCH 13/63] Fix broken link --- 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 33339ff..262d734 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -434,7 +434,7 @@ Check if variable equals a constant ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You don't need to explicitly compare a value to True, or None, or 0 - you can -just add it to the if statement. See :ref:`Truth Value Testing +just add it to the if statement. See `Truth Value Testing `_ for a list of what is considered false. From f0d1b23750a8260e1fc68cacad516b9275e551eb Mon Sep 17 00:00:00 2001 From: Han Su Kim Date: Thu, 5 Dec 2013 15:16:11 -0500 Subject: [PATCH 14/63] Added Ansible to the list Ansible is a tool written in Python for IT automation and orchestration. --- docs/scenarios/admin.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 4bdfe68..7f20dcd 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -176,6 +176,15 @@ Here is an example to be aware of some server overload. In case of some failed t A full terminal application like a widely extended top which is based on psutil and with the ability of a client-server monitoring is `glance `_. +Ansible +Chef +---- + +.. todo:: Write about Ansible + + `Ansible Documentation + `_ + Chef ---- From 26f94e45db5354a809397963490efaa9be946cc9 Mon Sep 17 00:00:00 2001 From: justinhorner Date: Thu, 2 Jan 2014 18:00:43 -0700 Subject: [PATCH 15/63] Update env.rst trailing slash in link caused 404, removed to fix link --- docs/dev/env.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 81da462..7097ee5 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -130,7 +130,7 @@ PyCharm / IntelliJ IDEA `PyCharm `_ is developed by JetBrains, also known for IntelliJ IDEA. Both share the same code base and most of PyCharm's -features can be brought to IntelliJ with the free `Python Plug-In `_. +features can be brought to IntelliJ with the free `Python Plug-In `_. Eclipse From 919884c45ccf8b9f10f011826a82d1e39a6e8d88 Mon Sep 17 00:00:00 2001 From: Lyndsy Simon Date: Tue, 14 Jan 2014 14:41:14 -0500 Subject: [PATCH 16/63] Adds recommendation to add /usr/local/sbin to /usr/local/bin:/usr/local/sbin:/usr/local/bin:/Users/lyndsy/.bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/local/MacGPG2/bin in OSX --- docs/starting/install/osx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index fa41f8c..8017bfb 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -50,7 +50,7 @@ line at the bottom of your ``~/.bashrc`` file .. code-block:: console - export PATH=/usr/local/bin:$PATH + export PATH=/usr/local/bin:/usr/local/sbin:$PATH Now, we can install Python 2.7: :: From 5156f9011ab775bd9e34ae45fb108f7cbe16329d Mon Sep 17 00:00:00 2001 From: Jonathan Steinmann Date: Thu, 16 Jan 2014 23:04:10 -0500 Subject: [PATCH 17/63] update db.rst expand on Django ORM basics --- docs/scenarios/db.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index 6d6d6ce..787f0ef 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -33,3 +33,11 @@ to provide database access. It's based on the idea of `models `_, an abstraction that makes it easier to manipulate data in Python. +The basics: + +- Each model is a Python class that subclasses django.db.models.Model. +- Each attribute of the model represents a database field. +- Django gives you an automatically-generated database-access API; see `Making queries `__. +to provide database access. + + From db5bcf53749a9617c6c33c105d88c05bf9c540ab Mon Sep 17 00:00:00 2001 From: Jeff Paine Date: Sat, 18 Jan 2014 08:33:56 -0500 Subject: [PATCH 18/63] Remove python 2.5 from example travis config Travis does not support python <2.6 --- docs/scenarios/ci.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 6e2025d..3d67f78 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -65,7 +65,6 @@ example content:: language: python python: - - "2.5" - "2.6" - "2.7" - "3.1" From ed74bde2337388f5ba8545bd2f59f43f409e2ce4 Mon Sep 17 00:00:00 2001 From: Jeff Paine Date: Sat, 18 Jan 2014 15:48:35 -0500 Subject: [PATCH 19/63] Remove python 3.1, add python 3.3 --- docs/scenarios/ci.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 3d67f78..e5dd565 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -67,8 +67,8 @@ example content:: python: - "2.6" - "2.7" - - "3.1" - "3.2" + - "3.3" # command to install dependencies script: python tests/test_all_of_the_units.py branches: From 494e80504da660eeecb64b8e338f2503e9e3781c Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 21:27:08 -0600 Subject: [PATCH 20/63] Updated capitalization in admin.rst Updated capitalization of fabric and salt to Fabric and Salt --- docs/scenarios/admin.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 7f20dcd..84c98da 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -6,7 +6,7 @@ Fabric `Fabric `_ is a library for simplifying system administration tasks. While Chef and Puppet tend to focus on managing servers -and system libraries, fabric is more focused on application level tasks such +and system libraries, Fabric is more focused on application level tasks such as deployment. Install Fabric: @@ -77,7 +77,7 @@ It supports remote command execution from a central point (master host) to multi hosts (minions). It also supports system states which can be used to configure multiple servers using simple template files. -Salt supports python versions 2.6 and 2.7 and can be installed via pip: +Salt supports Python versions 2.6 and 2.7 and can be installed via pip: .. code-block:: console @@ -95,7 +95,7 @@ The following command lists all available minion hosts, using the ping module. The host filtering is accomplished by matching the minion id, or using the grains system. The `grains `_ system uses static host information like the operating system version or the CPU architecture to -provide a host taxonomy for the salt modules. +provide a host taxonomy for the Salt modules. The following command lists all available minions running CentOS using the grains system: @@ -119,7 +119,7 @@ and start the Apache server: - require: - pkg: apache -State files can be written using YAML, the Jinja2 template system or pure python. +State files can be written using YAML, the Jinja2 template system or pure Python. `Salt Documentation `_ From afa61148f0215f445a831b6a8ade1dfc84d015dd Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 21:31:10 -0600 Subject: [PATCH 21/63] Hyphenation in ci.rst Replaced frontend with front-end --- docs/scenarios/ci.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 6e2025d..5a36bfb 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -47,7 +47,7 @@ which provides the following features: interpreters * Running tests in each of the environments, configuring your test tool of choice -* Acting as a frontend to Continuous Integration servers, reducing boilerplate +* Acting as a front-end to Continuous Integration servers, reducing boilerplate and merging CI and shell-based testing. From 3918f6b62aec0c75772246baa419056b8961dcfa Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 21:41:34 -0600 Subject: [PATCH 22/63] Spelling and capitalization in scientific.rst Changed python to Python and corrected some spelling --- docs/scenarios/scientific.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index a95f986..0d45807 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -9,7 +9,7 @@ Python is frequently used for high-performance scientific applications. Python is widely used in academia and scientific projects because it is easy to write, and it performs really well. -Due to its high performance nature, scientific computing in python often refers +Due to its high performance nature, scientific computing in Python often refers to external libraries, typically written in faster languages (like C, or FORTRAN for matrix operations). The main libraries used are `NumPy`_, `SciPy`_ and `Matplotlib`_. Going into detail about these libraries is beyond the scope @@ -24,11 +24,11 @@ Tools IPython ------- -`IPytthon `_ is an enhanced version of Python interpreter. +`IPython `_ is an enhanced version of Python interpreter. The features it provides are of great interest for the scientists. The `inline mode` allow graphics and plots to be displayed in the terminal (Qt based version). Moreover the `notebook` mode supports literate programming and reproducible science -generating a web-based python notebook. This notebook allowing to store chunk of +generating a web-based Python notebook. This notebook allowing to store chunk of Python code along side to the results and additional comments (HTML, LaTeX, Markdown). The notebook could be shared and exported in various file formats. @@ -64,7 +64,7 @@ SciPy `SciPy `_ is a library that uses Numpy for more mathematical functions. SciPy uses NumPy arrays as the basic data structure. SciPy comes -with modules for various commonly used tasks in scientific programing, for +with modules for various commonly used tasks in scientific programming, for example: linear algebra, integration (calculus), ordinary differential equation solvers and signal processing. @@ -86,7 +86,7 @@ based on Numpy and which provides many useful functions for accessing, indexing, merging and grouping data easily. The main data structure (DataFrame) is close to what could be found in the R statistical package, that is an heterogeneous data tables with name indexing, time series operations -and auto-alignement of data. +and auto-alignment of data. Rpy2 ---- @@ -120,7 +120,7 @@ Many people who do scientific computing are on Windows. And yet many of the scientific computing packages are notoriously difficult to build and install. `Christoph Gohlke `_ however, has compiled a list of Windows binaries for many useful Python packages. The list -of packages has grown from a mainly scientific python resource to a more +of packages has grown from a mainly scientific Python resource to a more general list. It might be a good idea to check it out if you're on Windows. Enthought Python Distribution (EPD) From 1f61583f10c421720ce14195b5f433fbcd069f3f Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 21:47:45 -0600 Subject: [PATCH 23/63] Capitalization in xml.rst replaced: * xml to XML * python to Python * json to JSON --- docs/scenarios/xml.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index 1f8db9c..ee97e2d 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -8,7 +8,7 @@ untangle an XML document and returns a Python object which mirrors the nodes and attributes in its structure. -For example, an xml file like this: +For example, an XML file like this: .. code-block:: xml @@ -36,9 +36,9 @@ xmltodict --------- `xmltodict `_ is another simple -library that aims at making xml feel like working with json. +library that aims at making XML feel like working with JSON. -An xml file like this: +An XML file like this: .. code-block:: xml @@ -52,7 +52,7 @@ An xml file like this: -can be loaded into a python dict like this: +can be loaded into a Python dict like this: .. code-block:: python @@ -68,6 +68,6 @@ and then you can access elements, attributes and values like this: doc['mydocument']['plus']['@a'] # == u'complex' doc['mydocument']['plus']['#text'] # == u'element as well' -xmltodict also lets you roundtrip back to xml with the unparse function, +xmltodict also lets you roundtrip back to XML with the unparse function, has a streaming mode suitable for handling files that don't fit in memory and supports namespaces. From 065f69d219d3b34e3d2e6648dc54f27ee99e6bee Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 21:51:42 -0600 Subject: [PATCH 24/63] Capitalization in packaging.rst Replaced python with Python --- docs/shipping/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 100ae91..54d72b0 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -46,7 +46,7 @@ Go to your command prompt and type: $ python -m SimpleHTTPServer 9000 This runs a simple http server running on port 9000 and will list all packages -(like **MyPackage**). Now you can install **MyPackage** using any python +(like **MyPackage**). Now you can install **MyPackage** using any Python package installer. Using Pip, you would do it like: .. code-block:: console From 5444d703d5253688e93f3f54fdfbd72fa7106d0b Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 21:58:43 -0600 Subject: [PATCH 25/63] Capitalization in env.rst Replaced python with Python --- docs/dev/env.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 7097ee5..e2e628c 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -64,7 +64,7 @@ to do that which also shows status and warning messages in the statusbar would b Python-mode ^^^^^^^^^^^ -Python-mode_ is a complex solution in VIM for working with python code. +Python-mode_ is a complex solution in VIM for working with Python code. It has: - Asynchronous Python code checking (pylint, pyflakes, pep8, mccabe) in any combination @@ -94,7 +94,7 @@ Emacs is a powerful text editor. It's fully programmable (lisp), but it can be some work to wire up correctly. A good start if you're already an Emacs user is `Python Programming in Emacs`_ at EmacsWiki. -1. Emacs itself comes with a python mode. +1. Emacs itself comes with a Python mode. 2. Python ships with an alternate version: `python-mode.el `_ 3. Fabián Ezequiel Gallina's `python.el `_ From f828b185d9cd4079e9297d3ca193f998a8a8918f Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 22:12:07 -0600 Subject: [PATCH 26/63] Update learning.rst Changed choosen to chosen Replaced python with Python --- docs/intro/learning.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index c3c0a22..b7633f9 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -7,9 +7,9 @@ Beginner Learn Python Interactive Tutorial ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Learnpython.org is an easy non-intimidating way to get introduced to python. +Learnpython.org is an easy non-intimidating way to get introduced to Python. The website takes the same approach used on the popular `Try Ruby `_ -website, it has an interactive python interpreter built into the site that +website, it has an interactive Python interpreter built into the site that allows you to go through the lessons without having to install Python locally. `Learn Python `_ @@ -52,11 +52,11 @@ Think Python: How to Think Like a Computer Scientist ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Think Python attempts to give an introduction to basic concepts in computer -science through the use of the python language. The focus was to create a book +science through the use of the Python language. The focus was to create a book with plenty of exercises, minimal jargon and a section in each chapter devoted to the subject of debugging. -While exploring the various features available in the python language the +While exploring the various features available in the Python language the author weaves in various design patterns and best practices. The book also includes several case studies which have the reader explore the @@ -72,11 +72,11 @@ Python Koans Python Koans is a port of Edgecase's Ruby Koans. It uses a test-driven approach, q.v. TEST DRIVEN DESIGN SECTION to provide an interactive tutorial -teaching basic python concepts. By fixing assertion statements that fail in a -test script, this provides sequential steps to learning python. +teaching basic Python concepts. By fixing assertion statements that fail in a +test script, this provides sequential steps to learning Python. For those used to languages and figuring out puzzles on their own, this can be -a fun, attractive option. For those new to python and programming, having an +a fun, attractive option. For those new to Python and programming, having an additional resource or reference will be helpful. `Python Koans `_ @@ -88,7 +88,7 @@ More information about test driven development can be found at these resources: A Byte of Python ~~~~~~~~~~~~~~~~ -A free introductory book that teaches python at the beginner level, it assumes no +A free introductory book that teaches Python at the beginner level, it assumes no previous programming experience. `A Byte of Python for Python 2.x `_ @@ -137,8 +137,8 @@ A Primer on Scientific Programming with Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A Primer on Scientific Programming with Python, written by Hans Petter Langtangen, -mainly covers python's usage in scientific field. In the book, examples are -choosen from mathematics and the natural sciences. +mainly covers Python's usage in scientific field. In the book, examples are +chosen from mathematics and the natural sciences. `A Primer on Scientific Programming with Python `_ @@ -146,7 +146,7 @@ Numerical Methods in Engineering with Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Numerical Methods in Engineering with Python,written by Jaan Kiusalaas, attempts to -emphasis on numerical methods and how to implement them in python. +emphasis on numerical methods and how to implement them in Python. `Numerical Methods in Engineering with Python `_ @@ -157,7 +157,7 @@ Python in a Nutshell ~~~~~~~~~~~~~~~~~~~~ Python in a Nutshell, written by Alex Martelli, covers most cross-platform -python's usage, from its syntax to built-in libraries to advanced topics such +Python's usage, from its syntax to built-in libraries to advanced topics such as writing C extensions. `Python in a Nutshell `_ From 74b6d1d61273748e2c8e49f57b86b0099fd0e97d Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 22:15:30 -0600 Subject: [PATCH 27/63] Replaced "python" with "Python" --- docs/intro/news.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro/news.rst b/docs/intro/news.rst index ec829f4..433f907 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -19,7 +19,7 @@ Python-related news. Pycoder's Weekly ~~~~~~~~~~~~~~~~ -Pycoder's Weekly is a free weekly python newsletter for Python developers +Pycoder's Weekly is a free weekly Python newsletter for Python developers by Python developers (Project, Articles, News, and Jobs). `Pycoder's Weekly `_ From cdd31908faf4ea8383339ec66cb638c8a370afe2 Mon Sep 17 00:00:00 2001 From: smithandrewl Date: Sat, 18 Jan 2014 22:27:06 -0600 Subject: [PATCH 28/63] Capitalization changes in web.rst Replaced: * python with Python * javascript with JavaScript --- docs/scenarios/web.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 4574096..d2178f1 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -271,10 +271,10 @@ and to the templates themselves. templates. This convenience can lead to uncontrolled increase in complexity, and often harder to find bugs. -- It is often necessary to mix javascript templates with +- It is often necessary to mix JavaScript templates with HTML templates. A sane approach to this design is to isolate the parts where the HTML template passes some variable content - to the javascript code. + to the JavaScript code. @@ -370,7 +370,7 @@ The `base.html` file can be used as base for all site pages which are for exampl -The next listing is our site page (`site.html`) loaded in the python app which extends `base.html`. The content block is +The next listing is our site page (`site.html`) loaded in the Python app which extends `base.html`. The content block is automatically set into the corresponding block in the base.html page. .. code-block:: html From 21d8f91ac6e5228780736c527b6821be3814d7a4 Mon Sep 17 00:00:00 2001 From: imranghory Date: Sat, 25 Jan 2014 14:37:18 +0000 Subject: [PATCH 29/63] Make explicit whats being referred to --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 0529b21..6ebd5d8 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -94,7 +94,7 @@ be sure to avoid using special symbols like the dot (.) or question mark (?). So a file name like `my.spam.py` is one you should avoid! Naming this way will interfere with the way python looks for modules. -In this example python expects to find a "spam.py" file in a folder named "my" +In the case of `my.spam.py` python expects to find a "spam.py" file in a folder named "my" which is not the case. There is an `example `_ of how the dot notation should be used in the python docs. From 020339f000433455d7812fd4f734e839ce94237e Mon Sep 17 00:00:00 2001 From: zachcp Date: Tue, 28 Jan 2014 12:28:31 -0500 Subject: [PATCH 30/63] Update Scientific Python Link --- 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 b7633f9..2e463ed 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -140,7 +140,7 @@ A Primer on Scientific Programming with Python, written by Hans Petter Langtange mainly covers Python's usage in scientific field. In the book, examples are chosen from mathematics and the natural sciences. - `A Primer on Scientific Programming with Python `_ + `A Primer on Scientific Programming with Python `_ Numerical Methods in Engineering with Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 852c5b1498c9c9dfad6c7ecc373b260fad27f9e6 Mon Sep 17 00:00:00 2001 From: Dhia Abbassi Date: Wed, 5 Feb 2014 15:30:12 +0100 Subject: [PATCH 31/63] Plac module Added Plac module description --- docs/scenarios/cli.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 933b0f0..5af149e 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -17,3 +17,14 @@ docopt `docopt `_ is a lightweight, highly Pythonic package that allows creating command line interfaces easily and intuitively, by parsing POSIX-style usage instructions. + +Plac +------ + +`Plac `_ is a python module that allows developing command line applications. In fact +plac is a simple wrapper over the python standard library `argparse `_, it hides most of its +complexity by using a declarative interface: the argument parser is inferred +rather than written down by imperatively. It is targetting especially unsophisticated +users, programmers, sys-admins, scientists and in general people writing throw-away +scripts for themselves, choosing the command-line interface because it is quick +and simple. From ccf93af642d77e7fd1501c189b528146f4736360 Mon Sep 17 00:00:00 2001 From: Jason Harmon Date: Thu, 6 Feb 2014 10:04:23 -0800 Subject: [PATCH 32/63] Updating links for brew --- docs/starting/install/osx.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 8017bfb..0f95e73 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -33,14 +33,14 @@ package. While Lion comes with a large number of UNIX utilities, those familiar with Linux systems will notice one key component missing: a decent package manager. -`Homebrew `_ fills this void. +`Homebrew `_ fills this void. -To `install Homebrew `_, +To `install Homebrew `_, simply run .. code-block:: console - $ ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)" + $ ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)" The script will explain what changes it will make and prompt you before the installation begins. From 1a5235309787f349728185b23b3eb013852d2e17 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Thu, 6 Feb 2014 15:44:48 -0800 Subject: [PATCH 33/63] Switch from Chishop to pypiserver --- docs/shipping/packaging.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 54d72b0..6d4aa5b 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -62,12 +62,14 @@ you can still install MyPackage using: $ pip install http://127.0.0.1:9000/MyPackage.tar.gz -Chishop -+++++++ +pypiserver +++++++++++ + +`Pypiserver `_ is a minimal PyPI compatible server. +It can be used to serve a set of packages to easy_install or pip. It includes helpful +features like an administrative command (``-U``) which will update all its packages to their +latest versions found on PyPI. -`Chishop `_ is a simple PyPI server -written in django which allows you to register/upload with distutils and -install with easy_install/pip. S3-Hosted PyPi ++++++++++++++ From 2017f0226504c6b5493b05b6e6626252eda3a413 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Thu, 6 Feb 2014 21:10:56 -0500 Subject: [PATCH 34/63] update "env.rst" --- docs/dev/env.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index e2e628c..8739a36 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -17,7 +17,7 @@ or icons. There exist a couple of plugins and settings for the VIM editor to aid Python development. If you only develop in Python, a good start is to set the default settings for indentation and line-wrapping to values compliant with :pep:`8`. In your home directory, open a file called `.vimrc` and add the -following lines::: +following lines:: set textwidth=79 " lines longer than 79 columns will be broken set shiftwidth=4 " operation >> indents 4 columns; << unindents 4 columns @@ -118,7 +118,7 @@ Sublime Text extraordinary features and amazing performance. Sublime Text has excellent support for editing Python code and uses Python for -its plugin API. It also has plugins a diverse variety of plugins, `some of which `_ +its plugin API. It also has a diverse variety of plugins, `some of which `_ allow for in-editor PEP8 checking and code "linting". From bdf516bb240f850b780e89cb10de62b0c5df6b66 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Thu, 6 Feb 2014 21:30:51 -0500 Subject: [PATCH 35/63] add comma --- docs/dev/virtualenvs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index c08f111..cf2b285 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -140,7 +140,7 @@ Other useful commands autoenv ------- -When you ``cd`` into a directory containing a ``.env`` `autoenv `_ +When you ``cd`` into a directory containing a ``.env``, `autoenv `_ automagically activates the environment. Install it on Mac OS X using ``brew``: From 832f69841002a71edad95db78777fa8324eb5243 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Mon, 10 Feb 2014 22:52:16 -0800 Subject: [PATCH 36/63] update intro section: add Pro Python link --- docs/intro/community.rst | 2 +- docs/intro/learning.rst | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/intro/community.rst b/docs/intro/community.rst index 05cd148..f54caff 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -75,7 +75,7 @@ The major events for the Python community are developer conferences. The two most notable conferences are PyCon, which is held in the US, and its European sibling, EuroPython. -A comprehensive list of conferences is maintained `at pycon.org `_. +A comprehensive list of conferences is maintained at `pycon.org `_. Python User Groups diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 2e463ed..bd2ca6d 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -104,6 +104,8 @@ Pro Python This book is for intermediate to advanced Python programmers who are looking to understand how and why Python works the way it does and how they can take their code to the next level. + `Pro Python `_ + Expert Python Programming ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -145,7 +147,7 @@ chosen from mathematics and the natural sciences. Numerical Methods in Engineering with Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Numerical Methods in Engineering with Python,written by Jaan Kiusalaas, attempts to +Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, attempts to emphasis on numerical methods and how to implement them in Python. `Numerical Methods in Engineering with Python `_ From dcaa25d0a6193ef16df32c68eba3776b5ff5d449 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Tue, 11 Feb 2014 21:49:35 -0800 Subject: [PATCH 37/63] remote duplicate Chef in admin.rst --- docs/scenarios/admin.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 84c98da..fd46454 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -177,7 +177,6 @@ A full terminal application like a widely extended top which is based on psutil monitoring is `glance `_. Ansible -Chef ---- .. todo:: Write about Ansible From 2b78a936f3ed924961731d607260383b65882f73 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Tue, 11 Feb 2014 22:11:12 -0800 Subject: [PATCH 38/63] add link to Numba --- docs/scenarios/scientific.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 0d45807..e955065 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -53,10 +53,11 @@ NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+. Numba ----- -Numba is an Numpy aware Python compiler (just-in-time (JIT) specializing -compiler) which compiles annotated Python (and Numpy) code to LLVM (Low Level -Virtual Machine) (through special decorators). -Briefly, Numba using system that compiles Python code with LLVM to code which + +`Numba `_ is an Numpy aware Python compiler +(just-in-time (JIT) specializing compiler) which compiles annotated Python (and +Numpy) code to LLVM (Low Level Virtual Machine) (through special decorators). +Briefly, Numba using system that compiles Python code with LLVM to code which can be natively executed at runtime. SciPy From a8e7b57758fa296df206675283c5059d04f9a173 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Tue, 11 Feb 2014 22:19:21 -0800 Subject: [PATCH 39/63] update untangle link --- docs/scenarios/xml.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index ee97e2d..3e01b2f 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -4,8 +4,8 @@ XML parsing untangle -------- -`untangle `_ is a simple library which takes -an XML document and returns a Python object which mirrors the nodes and +`untangle `_ is a simple library which +takes an XML document and returns a Python object which mirrors the nodes and attributes in its structure. For example, an XML file like this: From 04718556af6597a2d6163e5f11eac1c3a4fe2d03 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Tue, 11 Feb 2014 22:28:38 -0800 Subject: [PATCH 40/63] update Ubuntu Python packaging docs link --- docs/shipping/packaging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 6d4aa5b..d2757f0 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -99,12 +99,12 @@ One simple option for a personal PyPi server is to use Amazon S3. A prerequisite 6. **All done** -* You can now your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage` +* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage` For Linux Distributions :::::::::::::::::::::::: -* `Ubuntu `_ +* `Ubuntu `_ * `Fedora `_ * `Debian `_ * `Arch `_ From 2f5ae1786e68013b4cb84b2b2d685d3c5321310d Mon Sep 17 00:00:00 2001 From: anatoly techtonik Date: Wed, 12 Feb 2014 12:12:36 +0300 Subject: [PATCH 41/63] Update make files with versions from Sphinx 1.2 --- docs/Makefile | 53 +++++++++++++++++++++++++++++-- docs/make.bat | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+), 3 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index d8dd1f4..5c60d18 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,12 +7,19 @@ SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @@ -27,14 +34,20 @@ help: @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" @echo " text to make text files" @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: - -rm -rf $(BUILDDIR)/* + rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @@ -100,7 +113,13 @@ latex: latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: @@ -113,6 +132,24 @@ man: @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @@ -128,3 +165,13 @@ doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/make.bat b/docs/make.bat index 39f2a68..d77abb0 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,8 +7,10 @@ if "%SPHINXBUILD%" == "" ( ) set BUILDDIR=_build set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% ) if "%1" == "" goto help @@ -28,7 +30,11 @@ if "%1" == "help" ( echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter echo. text to make text files echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes echo. linkcheck to check all external links for integrity echo. doctest to run all doctests embedded in the documentation if enabled goto end @@ -40,8 +46,23 @@ if "%1" == "clean" ( goto end ) + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end @@ -49,6 +70,7 @@ if "%1" == "html" ( if "%1" == "dirhtml" ( %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. goto end @@ -56,6 +78,7 @@ if "%1" == "dirhtml" ( if "%1" == "singlehtml" ( %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. goto end @@ -63,6 +86,7 @@ if "%1" == "singlehtml" ( if "%1" == "pickle" ( %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the pickle files. goto end @@ -70,6 +94,7 @@ if "%1" == "pickle" ( if "%1" == "json" ( %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the JSON files. goto end @@ -77,6 +102,7 @@ if "%1" == "json" ( if "%1" == "htmlhelp" ( %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run HTML Help Workshop with the ^ .hhp project file in %BUILDDIR%/htmlhelp. @@ -85,6 +111,7 @@ if "%1" == "htmlhelp" ( if "%1" == "qthelp" ( %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: @@ -96,6 +123,7 @@ if "%1" == "qthelp" ( if "%1" == "devhelp" ( %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 echo. echo.Build finished. goto end @@ -103,6 +131,7 @@ if "%1" == "devhelp" ( if "%1" == "epub" ( %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 echo. echo.Build finished. The epub file is in %BUILDDIR%/epub. goto end @@ -110,13 +139,35 @@ if "%1" == "epub" ( if "%1" == "latex" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 echo. echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. goto end ) +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + if "%1" == "text" ( %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 echo. echo.Build finished. The text files are in %BUILDDIR%/text. goto end @@ -124,13 +175,31 @@ if "%1" == "text" ( if "%1" == "man" ( %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 echo. echo.Build finished. The manual pages are in %BUILDDIR%/man. goto end ) +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + if "%1" == "changes" ( %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 echo. echo.The overview file is in %BUILDDIR%/changes. goto end @@ -138,6 +207,7 @@ if "%1" == "changes" ( if "%1" == "linkcheck" ( %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 echo. echo.Link check complete; look for any errors in the above output ^ or in %BUILDDIR%/linkcheck/output.txt. @@ -146,10 +216,27 @@ or in %BUILDDIR%/linkcheck/output.txt. if "%1" == "doctest" ( %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 echo. echo.Testing of doctests in the sources finished, look at the ^ results in %BUILDDIR%/doctest/output.txt. goto end ) +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + :end From ee36d451036b43501a3a76671e1dad6709ba2427 Mon Sep 17 00:00:00 2001 From: anatoly techtonik Date: Wed, 12 Feb 2014 12:18:28 +0300 Subject: [PATCH 42/63] Fix project name in generated files (osxpython -> pythonguide) --- docs/Makefile | 8 ++++---- docs/index.rst | 2 +- docs/make.bat | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 5c60d18..40b479e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -85,17 +85,17 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/osxpython.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pythonguide.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/osxpython.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pythonguide.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/osxpython" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/osxpython" + @echo "# mkdir -p $$HOME/.local/share/devhelp/pythonguide" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pythonguide" @echo "# devhelp" epub: diff --git a/docs/index.rst b/docs/index.rst index 19e1672..1779f2f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -.. osxpython documentation master file, created by +.. pythonguide documentation master file, created by sphinx-quickstart on Wed Aug 4 22:51:11 2010. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. diff --git a/docs/make.bat b/docs/make.bat index d77abb0..c2cdfb6 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -115,9 +115,9 @@ if "%1" == "qthelp" ( echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\osxpython.qhcp + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\pythonguide.qhcp echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\osxpython.ghc + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\pythonguide.ghc goto end ) From c0fc5c18f3819b33a9d05b1059fb062891adf41e Mon Sep 17 00:00:00 2001 From: anatoly techtonik Date: Wed, 12 Feb 2014 13:17:29 +0300 Subject: [PATCH 43/63] make.bat: Try Sphinx installed in Python when sphinx-build is not in PATH --- docs/make.bat | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/make.bat b/docs/make.bat index c2cdfb6..b1533bc 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -47,6 +47,14 @@ if "%1" == "clean" ( ) +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 2> nul +if errorlevel 9009 goto sphinx_python +goto spinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ %SPHINXBUILD% 2> nul if errorlevel 9009 ( echo. @@ -60,6 +68,9 @@ if errorlevel 9009 ( exit /b 1 ) +:sphinx_ok + + if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html if errorlevel 1 exit /b 1 From f9dc281c9d17c2139f599fd624d0d2edf7770f15 Mon Sep 17 00:00:00 2001 From: anatoly techtonik Date: Wed, 12 Feb 2014 13:41:55 +0300 Subject: [PATCH 44/63] Fix typo --- docs/make.bat | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/make.bat b/docs/make.bat index b1533bc..115651a 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -50,7 +50,7 @@ if "%1" == "clean" ( REM Check if sphinx-build is available and fallback to Python version if any %SPHINXBUILD% 2> nul if errorlevel 9009 goto sphinx_python -goto spinx_ok +goto sphinx_ok :sphinx_python From 78f2b9e6ad6d44e461efad22cc9053a87f23e198 Mon Sep 17 00:00:00 2001 From: Chen Liu Date: Wed, 12 Feb 2014 09:03:21 -0800 Subject: [PATCH 45/63] expand "-" belongs to "Ansible" --- 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 fd46454..5fca65f 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -177,7 +177,7 @@ A full terminal application like a widely extended top which is based on psutil monitoring is `glance `_. Ansible ----- +------- .. todo:: Write about Ansible From 6d2d731a9d6c106c5788c01e6658e5062bc37c31 Mon Sep 17 00:00:00 2001 From: Andy Visser Date: Wed, 12 Feb 2014 15:45:03 -0500 Subject: [PATCH 46/63] "where ever" => "wherever" --- docs/starting/install/osx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 0f95e73..cada3bb 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -96,7 +96,7 @@ habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. -To set up a new Python environment, change the working directory to where ever +To set up a new Python environment, change the working directory to wherever you want to store the environment, and run the virtualenv utility in your project's directory From 29a3643ab485171cf4d3ede567628a4dbc91e9fd Mon Sep 17 00:00:00 2001 From: tommy3001 Date: Sat, 15 Feb 2014 13:08:42 +0100 Subject: [PATCH 47/63] Cython example added for strong typing --- docs/scenarios/speed.rst | 118 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 6aaa96b..af8f355 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -68,6 +68,124 @@ C Extensions Cython ------ +With `Cython `_ you are able to write C and C++ modules for Python. It implements a superset of the Python language. +With Cython you are also able to call C-functions and realize strong typing of variables and functions like float +(floating point numbers) or int (integer) definition of variables. Here is an example of strong typing with Cython: + +.. code-block:: python + + def primes(int kmax): + cdef int n, k, i + cdef int p[1000] + result = [] + if kmax > 1000: + kmax = 1000 + k = 0 + n = 2 + while k < kmax: + i = 0 + while i < k and n % p[i] != 0: + i = i + 1 + if i == k: + p[k] = n + k = k + 1 + result.append(n) + n = n + 1 + return result + +This implementation of an algorithm to find prime numbers has some additional commands instead of the next one, which is implemented in pure Python: + +.. code-block:: python + + def primes( kmax): + p= range(1000) + result = [] + if kmax > 1000: + kmax = 1000 + k = 0 + n = 2 + while k < kmax: + i = 0 + while i < k and n % p[i] != 0: + i = i + 1 + if i == k: + p[k] = n + k = k + 1 + result.append(n) + n = n + 1 + return result + + +The only difference between the both algorithm is this part: + +Strong typing with Cython: + +.. code-block:: python + + #primes function with additional Cython code: + def primes(int kmax): + cdef int n, k, i + cdef int p[1000] + result = [] + + +Normal variable definition in Python: + +.. code-block:: python + + #primes in standard Python syntax: + def primes( kmax): + p= range(1000) + result = [] + + +What is the difference? In the upper Cython version you can see the definitions of the variable types like in standard C. +For example `cdef int n,k,i` in line 3. This additional type definition (e.g. integer) allows the Cython compiler to generate +more efficient C code from this Cython code. While standard Python code is saved in `*.py` files, the Cython code is saved in `*.pyx` files. + +And what is with the speed? So lets try it! + +.. code-block:: python + + import time + #activate pyx compiler + import pyximport; pyximport.install() + #primes implemented with Cython + import primesCy + #primes implemented with Python + import primes + + print "Cython:" + t1= time.time() + print primesCy.primes(500) + t2= time.time() + print "Cython time: %s" %(t2-t1) + print "" + print "Python" + t1= time.time() + print primes.primes(500) + t2= time.time() + print "Python time: %s" %(t2-t1) + + +Where is the magic? Here it is: + +.. code-block:: python + + import pyximport; pyximport.install() + + +With the module `pyximport` you are able to import Cython `*.pyx` files, in this case `primesCy.pyx`, with the Cython +version of the primes function. +The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code, +which is automatically compiled to a `*.so` C-library. ... and Cython is able to import this library for you in your Python-code. +Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 (!) prime numbers. + +Here is the output of an embedded `ARM beaglebone `_ machine: + +Cython time: 0.0196 seconds + +Python time: 0.3302 seconds Pyrex ----- From a30b491b5624a7be6f49352659ae18bc48c1c106 Mon Sep 17 00:00:00 2001 From: tommy3001 Date: Sat, 15 Feb 2014 17:58:40 +0100 Subject: [PATCH 48/63] indentation fixed --- docs/scenarios/speed.rst | 84 ++++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index af8f355..5056086 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -74,46 +74,48 @@ With Cython you are also able to call C-functions and realize strong typing of v .. code-block:: python - def primes(int kmax): - cdef int n, k, i - cdef int p[1000] - result = [] - if kmax > 1000: - kmax = 1000 - k = 0 - n = 2 - while k < kmax: - i = 0 - while i < k and n % p[i] != 0: - i = i + 1 - if i == k: - p[k] = n - k = k + 1 - result.append(n) - n = n + 1 - return result + def primes(int kmax): + cdef int n, k, i + cdef int p[1000] + result = [] + if kmax > 1000: + kmax = 1000 + k = 0 + n = 2 + while k < kmax: + i = 0 + while i < k and n % p[i] != 0: + i = i + 1 + if i == k: + p[k] = n + k = k + 1 + result.append(n) + n = n + 1 + return result + This implementation of an algorithm to find prime numbers has some additional commands instead of the next one, which is implemented in pure Python: .. code-block:: python - def primes( kmax): - p= range(1000) - result = [] - if kmax > 1000: - kmax = 1000 - k = 0 - n = 2 - while k < kmax: - i = 0 - while i < k and n % p[i] != 0: - i = i + 1 - if i == k: - p[k] = n - k = k + 1 - result.append(n) - n = n + 1 - return result + def primes( kmax): + p= range(1000) + result = [] + if kmax > 1000: + kmax = 1000 + k = 0 + n = 2 + while k < kmax: + i = 0 + while i < k and n % p[i] != 0: + i = i + 1 + if i == k: + p[k] = n + k = k + 1 + result.append(n) + n = n + 1 + return result + The only difference between the both algorithm is this part: @@ -124,10 +126,9 @@ Strong typing with Cython: #primes function with additional Cython code: def primes(int kmax): - cdef int n, k, i - cdef int p[1000] - result = [] - + cdef int n, k, i + cdef int p[1000] + result = [] Normal variable definition in Python: @@ -135,9 +136,8 @@ Normal variable definition in Python: #primes in standard Python syntax: def primes( kmax): - p= range(1000) - result = [] - + p= range(1000) + result = [] What is the difference? In the upper Cython version you can see the definitions of the variable types like in standard C. For example `cdef int n,k,i` in line 3. This additional type definition (e.g. integer) allows the Cython compiler to generate From 7ef55e755f8c8e714ade2f1ebbf21ebab585e7dd Mon Sep 17 00:00:00 2001 From: tommy3001 Date: Sat, 15 Feb 2014 18:38:43 +0100 Subject: [PATCH 49/63] minor changes (indentation fixed) --- docs/scenarios/speed.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 5056086..f8a37c9 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -124,8 +124,8 @@ Strong typing with Cython: .. code-block:: python - #primes function with additional Cython code: - def primes(int kmax): + #primes function with additional Cython code: + def primes(int kmax): cdef int n, k, i cdef int p[1000] result = [] @@ -135,7 +135,7 @@ Normal variable definition in Python: .. code-block:: python #primes in standard Python syntax: - def primes( kmax): + def primes( kmax): p= range(1000) result = [] @@ -149,7 +149,8 @@ And what is with the speed? So lets try it! import time #activate pyx compiler - import pyximport; pyximport.install() + import pyximport + pyximport.install() #primes implemented with Cython import primesCy #primes implemented with Python @@ -172,14 +173,15 @@ Where is the magic? Here it is: .. code-block:: python - import pyximport; pyximport.install() + import pyximport + pyximport.install() With the module `pyximport` you are able to import Cython `*.pyx` files, in this case `primesCy.pyx`, with the Cython version of the primes function. The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code, which is automatically compiled to a `*.so` C-library. ... and Cython is able to import this library for you in your Python-code. -Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 (!) prime numbers. +Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers. Here is the output of an embedded `ARM beaglebone `_ machine: From d30830009a5df0c10019ced46f036478dcdc5807 Mon Sep 17 00:00:00 2001 From: tommy3001 Date: Sat, 15 Feb 2014 19:33:00 +0100 Subject: [PATCH 50/63] Cython: additional benchmark for standard CPU --- docs/scenarios/speed.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index f8a37c9..7a2ef88 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -183,7 +183,13 @@ The `pyximport.install()` command allows the Python interpreter to start the Cyt which is automatically compiled to a `*.so` C-library. ... and Cython is able to import this library for you in your Python-code. Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers. -Here is the output of an embedded `ARM beaglebone `_ machine: +On a standard notebook (dualcore AMD E-450 1,6 GHz) the measured values are: + +Cython time: 0.0054 seconds + +Python time: 0.0566 seconds + +And here the output of an embedded `ARM beaglebone `_ machine: Cython time: 0.0196 seconds From 33b428b8a5c352f9c6d902c352f3d477bb1f7bf2 Mon Sep 17 00:00:00 2001 From: tommy3001 Date: Sun, 16 Feb 2014 17:50:07 +0100 Subject: [PATCH 51/63] misspelling in description --- docs/scenarios/speed.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 7a2ef88..308d27c 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -181,7 +181,7 @@ With the module `pyximport` you are able to import Cython `*.pyx` files, in this version of the primes function. The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code, which is automatically compiled to a `*.so` C-library. ... and Cython is able to import this library for you in your Python-code. -Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers. +Very easy and very efficient. With the `time.time()` function you are able to compare the time between these 2 different calls to find 500 prime numbers. On a standard notebook (dualcore AMD E-450 1,6 GHz) the measured values are: From 87ec12d320426076a23fe8886e5cba2205357623 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Gr=C3=B6ger?= Date: Mon, 17 Feb 2014 20:52:21 +0100 Subject: [PATCH 52/63] Included tldrlegal.com tl;drLegal is a great place to look up what a particular license is all about. The website can be found here: https://tldrlegal.com/ --- docs/writing/license.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/license.rst b/docs/writing/license.rst index 6f0df77..1fbd09a 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -48,5 +48,5 @@ To help you choose one for your project, there's a `license chooser `_. From c8bda6892f7802763bb36b2e2512505a06c4d158 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Gr=C3=B6ger?= Date: Mon, 17 Feb 2014 21:03:36 +0100 Subject: [PATCH 53/63] Added oxford comma. --- docs/writing/license.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/license.rst b/docs/writing/license.rst index 1fbd09a..9dd7c86 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -48,5 +48,5 @@ To help you choose one for your project, there's a `license chooser `_. +A good overview of licenses with explanations of what one can, cannot, and must do using a particular software can be found at `tl;drLegal `_. From 1be68ba74976dba31230432f672108b26af2d2d5 Mon Sep 17 00:00:00 2001 From: Dhia Abbassi Date: Wed, 19 Feb 2014 21:15:16 +0100 Subject: [PATCH 54/63] Update cli.rst Added Cliff module description. --- docs/scenarios/cli.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 5af149e..217d06f 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -28,3 +28,10 @@ rather than written down by imperatively. It is targetting especially unsophisti users, programmers, sys-admins, scientists and in general people writing throw-away scripts for themselves, choosing the command-line interface because it is quick and simple. + +Cliff +------ +`Cliff `_ is a framework for building command line programs. +It uses setuptools entry points to provide subcommands, output formatters, and other extensions. The framework +is meant to be used to create multi-level commands such as subversion and git, where the main program handles +some basic argument parsing and then invokes a sub-command to do the work. From c46965911652c00b7368423c59ecc4ea3a71d53d Mon Sep 17 00:00:00 2001 From: Dhia Abbassi Date: Thu, 20 Feb 2014 09:25:27 +0100 Subject: [PATCH 55/63] Update cli.rst Blank line added after the title Cliff. --- docs/scenarios/cli.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 217d06f..cee4872 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -31,6 +31,7 @@ and simple. Cliff ------ + `Cliff `_ is a framework for building command line programs. It uses setuptools entry points to provide subcommands, output formatters, and other extensions. The framework is meant to be used to create multi-level commands such as subversion and git, where the main program handles From ca240c247921a47062d764f625c024d86b1c5b6f Mon Sep 17 00:00:00 2001 From: Jeff Hammerbacher Date: Sat, 22 Feb 2014 18:59:01 -0500 Subject: [PATCH 56/63] "faster on tracks" => "back on track faster" --- docs/writing/tests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 4e87491..05faace 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -40,7 +40,7 @@ Some general rules of testing: - If you are in the middle of a development session and have to interrupt your work, it is a good idea to write a broken unit test about what you want to develop next. When coming back to work, you will have a pointer to where you were and get - faster on tracks. + back on track faster. - The first step when you are debugging your code is to write a new test pinpointing the bug. While it is not always possible to do, those bug From b8f99234165cd520cdda5f2e440b6066492fa772 Mon Sep 17 00:00:00 2001 From: tommy3001 Date: Sun, 23 Feb 2014 23:32:13 +0100 Subject: [PATCH 57/63] Improvements of description. Thanks to sigmavirus24 --- docs/scenarios/speed.rst | 40 +++++++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 308d27c..05130c8 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -69,12 +69,14 @@ Cython ------ With `Cython `_ you are able to write C and C++ modules for Python. It implements a superset of the Python language. -With Cython you are also able to call C-functions and realize strong typing of variables and functions like float -(floating point numbers) or int (integer) definition of variables. Here is an example of strong typing with Cython: +You are also able to call C-functions and realize declaration of variables and functions like in C. Here is an example: .. code-block:: python def primes(int kmax): + """Calculation of prime numbers with additional + Cython keywords""" + cdef int n, k, i cdef int p[1000] result = [] @@ -94,11 +96,14 @@ With Cython you are also able to call C-functions and realize strong typing of v return result -This implementation of an algorithm to find prime numbers has some additional commands instead of the next one, which is implemented in pure Python: +This implementation of an algorithm to find prime numbers has some additional keywords instead of the next one, which is implemented in pure Python: .. code-block:: python - def primes( kmax): + + def primes(kmax): + """Calculation of prime numbers in standard Python syntax""" + p= range(1000) result = [] if kmax > 1000: @@ -120,28 +125,30 @@ This implementation of an algorithm to find prime numbers has some additional co The only difference between the both algorithm is this part: -Strong typing with Cython: .. code-block:: python - #primes function with additional Cython code: def primes(int kmax): + """Calculation of prime numbers with additional + Cython keywords""" + cdef int n, k, i cdef int p[1000] result = [] -Normal variable definition in Python: .. code-block:: python - #primes in standard Python syntax: - def primes( kmax): + def primes(kmax): + """Calculation of prime numbers in standard Python syntax""" + p= range(1000) result = [] -What is the difference? In the upper Cython version you can see the definitions of the variable types like in standard C. -For example `cdef int n,k,i` in line 3. This additional type definition (e.g. integer) allows the Cython compiler to generate -more efficient C code from this Cython code. While standard Python code is saved in `*.py` files, the Cython code is saved in `*.pyx` files. +What is the difference? In the upper Cython version you can see the declaration of the variable types and the integer array +in a similar way like in standard C. For example `cdef int n,k,i` in line 3. This additional type declaration (e.g. integer) +allows the Cython compiler to generate more efficient C code from the second code. While standard Python code is saved in `*.py` files, +Cython code is saved in `*.pyx` files. And what is with the speed? So lets try it! @@ -169,7 +176,7 @@ And what is with the speed? So lets try it! print "Python time: %s" %(t2-t1) -Where is the magic? Here it is: +These both lines need a remark: .. code-block:: python @@ -177,11 +184,10 @@ Where is the magic? Here it is: pyximport.install() -With the module `pyximport` you are able to import Cython `*.pyx` files, in this case `primesCy.pyx`, with the Cython -version of the primes function. +The `pyximport` module allows you to import `pyx` files (e.g., `primesCy.pyx`) with the Cython-compiled version of the `primes` function. The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code, -which is automatically compiled to a `*.so` C-library. ... and Cython is able to import this library for you in your Python-code. -Very easy and very efficient. With the `time.time()` function you are able to compare the time between these 2 different calls to find 500 prime numbers. +which is automatically compiled to a `*.so` C-library. Cython is able to import this library for you in your Python-code. +Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers. On a standard notebook (dualcore AMD E-450 1,6 GHz) the measured values are: From 8330e78359976140bea06ea3fde9425505d5c7c8 Mon Sep 17 00:00:00 2001 From: eet6646 Date: Sun, 23 Feb 2014 22:24:12 -0400 Subject: [PATCH 58/63] Issue #361 - Link to PDF --- docs/_templates/sidebarintro.html | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 58c71b0..096524c 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -31,4 +31,5 @@
  • The Guide Website
  • The Guide @ GitHub
  • Issue Tracker
    • +
  • PDF Download
    • From a2da09a6c594ce0ee4de9643ad0fdfa199a1588c Mon Sep 17 00:00:00 2001 From: eet6646 Date: Mon, 24 Feb 2014 15:07:24 -0400 Subject: [PATCH 59/63] Wording fix --- docs/_templates/sidebarintro.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 096524c..a8c525a 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -31,5 +31,5 @@
  • The Guide Website
  • The Guide @ GitHub
  • Issue Tracker
    • -
  • PDF Download
    • +
  • The Guide as a PDF
    • From 6edbe902661be39b961a44ef4d6f60dc499f4c8d Mon Sep 17 00:00:00 2001 From: "Leonardo.Z" Date: Mon, 3 Mar 2014 14:17:51 +0800 Subject: [PATCH 60/63] Add a new documentation tool: MkDocs MkDocs is a new and popular documentation tool written in Python. It's supported by ReadTheDoc.org. --- docs/writing/documentation.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 7793af4..fc9cea5 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -162,3 +162,8 @@ Epydoc_ Epydoc is discontinued. Use :ref:`sphinx-ref` instead. .. _Epydoc: http://epydoc.sourceforge.net + +MkDocs_ + MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation with Markdown. + +.. _MkDocs: http://www.mkdocs.org/ From f52704926c6728892d5ea66133d1e77060b55b6a Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Mon, 3 Mar 2014 06:49:26 -0600 Subject: [PATCH 61/63] Keep it neutral --- docs/writing/documentation.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index fc9cea5..3f4d0b9 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -164,6 +164,7 @@ Epydoc_ .. _Epydoc: http://epydoc.sourceforge.net MkDocs_ - MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation with Markdown. + MkDocs is a fast and simple static site generator that's geared towards + building project documentation with Markdown. .. _MkDocs: http://www.mkdocs.org/ From 2d6521e3e46a63e6a602b287a07814d31ee63850 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Wed, 5 Mar 2014 19:52:13 -0600 Subject: [PATCH 62/63] Make this one sentence simpler --- docs/starting/install/osx.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index cada3bb..69b7444 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -96,9 +96,9 @@ habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. -To set up a new Python environment, change the working directory to wherever -you want to store the environment, and run the virtualenv utility in your -project's directory +To set up a new Python environment, move into the directory where you would +like to store the environment, and use the ``virtualenv`` utility to create +the new environment. .. code-block:: console From 456660cd3c96fce1c5104fb7effe861d6562aeef Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Wed, 5 Mar 2014 19:57:12 -0600 Subject: [PATCH 63/63] Last bit of unhandled PR review from #370 --- docs/scenarios/speed.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 05130c8..0219cf3 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -68,8 +68,11 @@ C Extensions Cython ------ -With `Cython `_ you are able to write C and C++ modules for Python. It implements a superset of the Python language. -You are also able to call C-functions and realize declaration of variables and functions like in C. Here is an example: +`Cython `_ implements a superset of the Python language +with which you are able to write C and C++ modules for Python. Cython also +allows you to call functions from compiled C libraries. Using Cython allows +you to take advantage of Python's strong typing of variables and operations. +Here is an example of strong typing with Cython: .. code-block:: python @@ -121,9 +124,8 @@ This implementation of an algorithm to find prime numbers has some additional ke n = n + 1 return result - - -The only difference between the both algorithm is this part: +Notice that in the Cython version you declare integers and integer arrays for +to be compiled into C types while also creating a Python list: .. code-block:: python