From d139b348a3f9a8683c140feba240b339b892ff1c Mon Sep 17 00:00:00 2001 From: Ryan Day Date: Fri, 30 Dec 2011 00:50:36 -0500 Subject: [PATCH 01/26] Add links to understand the GIL --- docs/scenarios/speed.rst | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 5a4bd13..025352a 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -11,7 +11,13 @@ Context The GIL ------- +`The GIL`_ (Global Interpreter Lock) is how Python allows multiple threads to operate at the same time. Python's +memory management isn't entirely thread-safe, so the GIL is requried to prevents multiple threads from running +the same Python code at once. +David Beazley has a great `guide`_ on how the GIL operates. He also covers the `new GIL`_ in Python 3.2. His +results show that maximizing performance in a Python application requires a strong understanding of the GIL, +how it affects your specific application, how many cores you have, and where your application bottlenecks are. C Extentions ------------ @@ -20,8 +26,8 @@ C Extentions The GIL ------- - - +`Special care`_ must be taken when writing C extensions to make sure you register your threads +with the interpreter. C Extentions :::::::::::: @@ -56,4 +62,8 @@ Multiprocessing --------------- -.. _`PyPy`: http://pypy.org \ No newline at end of file +.. _`PyPy`: http://pypy.org +.. _`The GIL`: http://wiki.python.org/moin/GlobalInterpreterLock +.. _`Understanding GIL`: http://www.dabeaz.com/python/UnderstandingGIL.pdf +.. _`New GIL`: http://www.dabeaz.com/python/NewGIL.pdf +.. _`Thread State`: http://docs.python.org/c-api/init.html#threads \ No newline at end of file From 13a98300706e27ede09e0212dab37eb84c6a144a Mon Sep 17 00:00:00 2001 From: Ryan Day Date: Fri, 30 Dec 2011 00:52:03 -0500 Subject: [PATCH 02/26] fix link markup --- docs/scenarios/speed.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 025352a..00aa5d5 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -64,6 +64,6 @@ Multiprocessing .. _`PyPy`: http://pypy.org .. _`The GIL`: http://wiki.python.org/moin/GlobalInterpreterLock -.. _`Understanding GIL`: http://www.dabeaz.com/python/UnderstandingGIL.pdf +.. _`guide`: http://www.dabeaz.com/python/UnderstandingGIL.pdf .. _`New GIL`: http://www.dabeaz.com/python/NewGIL.pdf -.. _`Thread State`: http://docs.python.org/c-api/init.html#threads \ No newline at end of file +.. _`Special care`: http://docs.python.org/c-api/init.html#threads \ No newline at end of file From 06c6063e59665e0a80aea0e2dbd9a58fd2287ede Mon Sep 17 00:00:00 2001 From: mrshu Date: Sat, 31 Dec 2011 20:41:34 +0000 Subject: [PATCH 03/26] Removed unnecessary part of CI definition. --- 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 15166a2..285e522 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -7,7 +7,7 @@ Why? Martin Fowler, who first wrote about `Continuous Integration `_ (short: CI) together with Kent Beck, describes the CI as follows: - Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. This article is a quick overview of Continuous Integration summarizing the technique and its current usage. + Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. Jenkins ------- From f29b0284b92efb7e9fa27f80fc707fce948cf231 Mon Sep 17 00:00:00 2001 From: John Del Rosario Date: Sun, 1 Jan 2012 23:36:22 +0800 Subject: [PATCH 04/26] Flesh out virtualenvs section. --- docs/dev/virtualenvs.rst | 83 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 3 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 385fe94..cf96007 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -1,15 +1,92 @@ Virtual Environments ==================== -.. todo:: Explain "Virtual Environments" +A Virtual Environment, put simply, is an isolated working copy of Python which allows you to work on a specific project without worry of affecting other projects. + +For example, you can work on a project which requires Django 1.3 at the same time with a project which requires Django 1.0. + virtualenv ---------- -.. todo:: Write about virtualenv +`virtualenv `_ is a tool to create isolated Python environments. + +Install it via pip:: + + $ pip install virtualenv + +Basic Usage +~~~~~~~~~~~ + +1. Create a virtual environment:: + + $ virtualenv ENVIRONMENT_NAME + +This creates a copy of Python in whichever directory you ran the command in, placing it in a folder named ``ENVIRONMENT_NAME``. + +2. To begin using the virtual environment, it needs to be activated:: + + $ source ENVIRONMENT_NAME/bin/activate + +You can then begin installing any new modules without affecting the system default Python or other virtual environments. + +3. If you are done working in the virtual environment for the moment, you can deactivate it:: + + $ deactivate + +This puts you back to the system's default Python interpreter with all its installed libraries. + +To delete a virtual environment, just delete its folder. virtualenvwrapper ----------------- -.. todo:: Write about virtualenvwrapper +`virtualenvwrapper `_ provides a set of commands which makes working with virtual environments much more pleasant. It also places all your virtual environments into one place. +To install (make sure virtualenv is already installed):: + + $ pip install virtualenvwrapper + $ export WORKON_HOME=~/Envs + $ source /usr/local/bin/virtualenvwrapper.sh + +(Full instructions `here `_.) + +Basic Usage +~~~~~~~~~~~ + +1. Create a virtual environment:: + + $ mkvirtualenv ENVIRONMENT_NAME + +This creates the ``ENVIRONMENT_NAME`` folder inside ``~/Envs``. + +2. Work on a virtual environment:: + + $ workon ENVIRONMENT_NAME + +**virtualenvwrapper** provides tab-completion on environment names. It really helps when you have a lot of environments and have trouble remembering their names. +``workon`` also deactivates whatever environment you are currently in, so you can quickly switch between environments. + +3. Deactivating is still the same:: + + $ deactivate + +4. To delete:: + + $ rmvirtualenv ENVIRONMENT_NAME + +Other nifty commands include: + +``lsvirtualenv`` + List all of the environments. + +``cdvirtualenv`` + Navigate into the directory of the currently activated virtual environment, so you can browse its ``site-packages``, for example. + +``cdsitepackages`` + Like the above, but directly into ``site-packages`` directory. + +``lssitepackages`` + Shows contents of ``site-packages`` directory. + +Full list of commands can be found `here `_. From f4918a569cfef0fcf1adedd446762a4f7c4e3cf2 Mon Sep 17 00:00:00 2001 From: Kamil Kisiel Date: Mon, 2 Jan 2012 06:10:17 -0800 Subject: [PATCH 05/26] Fixed "web servers" heading --- docs/scenarios/web.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 67f240f..294c205 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -88,6 +88,8 @@ The premise of web.py is that it is flexible - code your webapp any way you want web.py comes with some nifty tools built in, like database connection tools and a mini http server. **Support** for web.py is quite sparse, but you can look for support in the `mailing list `_ . + + Web Servers ::::::::::: @@ -312,4 +314,4 @@ Node.js. .. [1] `The mod_python project is now officially dead `_ .. [2] `mod_wsgi vs mod_python `_ -.. [3] `Benchmark of Python WSGI Servers `_ \ No newline at end of file +.. [3] `Benchmark of Python WSGI Servers `_ From 8a8a6c794fe33cd262a13d7b4fb5e6d67fc35323 Mon Sep 17 00:00:00 2001 From: Kamil Kisiel Date: Mon, 2 Jan 2012 06:26:12 -0800 Subject: [PATCH 06/26] A variety of build error fixes --- docs/contents.rst.inc | 3 ++- docs/notes/contribute.rst | 2 -- docs/scenarios/gui.rst | 6 ++++-- docs/starting/installation.rst | 4 ---- docs/starting/next.rst | 0 docs/writing/documentation.rst | 11 ++++++++--- 6 files changed, 14 insertions(+), 12 deletions(-) delete mode 100644 docs/starting/next.rst diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index de51208..3f6f60a 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -24,7 +24,6 @@ This part of the guide focuses on setting up your Python environment. starting/which-python starting/installation - starting/next Development Environment @@ -80,6 +79,7 @@ different scenarios. scenarios/admin scenarios/ci scenarios/speed + scenarios/scientific Additional Notes @@ -92,3 +92,4 @@ Contibution notes and legal information are here (for those interested). notes/contribute notes/license + notes/styleguide diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index 3caf758..0d709f2 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -25,5 +25,3 @@ If you'd like to contribute, there's plenty to do. Here's a short todo_ list. .. _GitHub: http://github.com/kennethreitz/python-guide/ .. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst - -.. include:: ../../AUTHORS.rst \ No newline at end of file diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 8572f7b..037c641 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -26,12 +26,14 @@ PyObjC WXPython :::::::: + + Install (Stable) ----- +---------------- *Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.* Gtk ::: tk -:: \ No newline at end of file +:: diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index ace753f..e4890e3 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -65,10 +65,6 @@ If you have homebrew: :: $ easy_install pip - - -To install ``pip``: :: - Hopefully you'll never have to use **easy_install** again. diff --git a/docs/starting/next.rst b/docs/starting/next.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index d1c4658..6824665 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -11,6 +11,7 @@ The Basics Code Comments ------------- + Information regarding code comments is taken from PEP 008 (http://www.python.org/dev/peps/pep-0008/). Block comment styling should be used when commenting out multiple lines of code.: :: @@ -34,9 +35,11 @@ Inline comments are used for individual lines and should be used sparingly.: :: Doc Strings ----------- + PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/) -|There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory. -|One-line docstrings: :: + +There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory. +One-line docstrings: :: def kos_root(): """Return the pathname of the KOS root directory.""" @@ -59,6 +62,7 @@ Multi-line docstrings: :: Sphinx ------ + Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text. .. note:: This Guide is built with Sphinx_ @@ -67,6 +71,7 @@ Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref .. _restructuredtext-ref: + reStructuredText ---------------- @@ -84,4 +89,4 @@ pocco / docco / shocco ---------------------- Ronn ----- \ No newline at end of file +---- From 291ab64150212b26b004ac0f4a0cae8eac2524ff Mon Sep 17 00:00:00 2001 From: John Louis Del Rosario Date: Mon, 2 Jan 2012 22:48:37 +0800 Subject: [PATCH 07/26] Wrap virtualenvs to 80 chars. --- docs/dev/virtualenvs.rst | 41 ++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index cf96007..942406e 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -1,15 +1,18 @@ Virtual Environments ==================== -A Virtual Environment, put simply, is an isolated working copy of Python which allows you to work on a specific project without worry of affecting other projects. - -For example, you can work on a project which requires Django 1.3 at the same time with a project which requires Django 1.0. +A Virtual Environment, put simply, is an isolated working copy of Python which +allows you to work on a specific project without worry of affecting other +projects. +For example, you can work on a project which requires Django 1.3 while also +maintaining a project which requires Django 1.0. virtualenv ---------- -`virtualenv `_ is a tool to create isolated Python environments. +`virtualenv `_ is a tool to create +isolated Python environments. Install it via pip:: @@ -22,28 +25,34 @@ Basic Usage $ virtualenv ENVIRONMENT_NAME -This creates a copy of Python in whichever directory you ran the command in, placing it in a folder named ``ENVIRONMENT_NAME``. +This creates a copy of Python in whichever directory you ran the command in, +placing it in a folder named ``ENVIRONMENT_NAME``. 2. To begin using the virtual environment, it needs to be activated:: $ source ENVIRONMENT_NAME/bin/activate -You can then begin installing any new modules without affecting the system default Python or other virtual environments. +You can then begin installing any new modules without affecting the system +default Python or other virtual environments. -3. If you are done working in the virtual environment for the moment, you can deactivate it:: +3. If you are done working in the virtual environment for the moment, you can + deactivate it:: $ deactivate -This puts you back to the system's default Python interpreter with all its installed libraries. +This puts you back to the system's default Python interpreter with all its +installed libraries. To delete a virtual environment, just delete its folder. virtualenvwrapper ----------------- -`virtualenvwrapper `_ provides a set of commands which makes working with virtual environments much more pleasant. It also places all your virtual environments into one place. +`virtualenvwrapper `_ +provides a set of commands which makes working with virtual environments much +more pleasant. It also places all your virtual environments into one place. -To install (make sure virtualenv is already installed):: +To install (make sure **virtualenv** is already installed):: $ pip install virtualenvwrapper $ export WORKON_HOME=~/Envs @@ -64,8 +73,11 @@ This creates the ``ENVIRONMENT_NAME`` folder inside ``~/Envs``. $ workon ENVIRONMENT_NAME -**virtualenvwrapper** provides tab-completion on environment names. It really helps when you have a lot of environments and have trouble remembering their names. -``workon`` also deactivates whatever environment you are currently in, so you can quickly switch between environments. +**virtualenvwrapper** provides tab-completion on environment names. It really +helps when you have a lot of environments and have trouble remembering their +names. +``workon`` also deactivates whatever environment you are currently in, so you +can quickly switch between environments. 3. Deactivating is still the same:: @@ -81,7 +93,8 @@ Other nifty commands include: List all of the environments. ``cdvirtualenv`` - Navigate into the directory of the currently activated virtual environment, so you can browse its ``site-packages``, for example. + Navigate into the directory of the currently activated virtual environment, + so you can browse its ``site-packages``, for example. ``cdsitepackages`` Like the above, but directly into ``site-packages`` directory. @@ -89,4 +102,4 @@ Other nifty commands include: ``lssitepackages`` Shows contents of ``site-packages`` directory. -Full list of commands can be found `here `_. +A full list of commands can be found `here `_. From 36e0ea967a13770d7bdd98997e64670696521178 Mon Sep 17 00:00:00 2001 From: Ori Avtalion Date: Wed, 4 Jan 2012 21:27:11 +0200 Subject: [PATCH 08/26] Fix typos, wording --- docs/intro/community.rst | 4 ++-- docs/intro/learning.rst | 2 +- docs/intro/news.rst | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/intro/community.rst b/docs/intro/community.rst index 74b3720..be1176e 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -19,7 +19,7 @@ The mission of the Python Software Foundation is to promote, protect, and advanc PEPs ---- -PEPs are *Python Enhancement Proposals*. They are define change to Python itself, or the standards around it. +PEPs are *Python Enhancement Proposals*. They describe changes to Python itself, or the standards around it. There are three different types of PEPs (as defined by `PEP1 `_): @@ -70,4 +70,4 @@ A comprehensive list of conferences is maintained `at pycon.org `_. \ No newline at end of file +User Groups are where a bunch of Python developers meet to present or talk about Python topics of interest. A list of local user groups is maintained at the `Python Software Foundation Wiki `_. diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 01870fd..ecf3829 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -47,7 +47,7 @@ While exploring the various features available in the python language the author patterns and best practices. The book also includes several case studies which have the reader explore the topics discussed in the book -in greater detail by applying those topics to real-world examples. Case studies include assingments in GUI +in greater detail by applying those topics to real-world examples. Case studies include assignments in GUI and Markov Analysis. `Think Python `_ diff --git a/docs/intro/news.rst b/docs/intro/news.rst index 209ac1a..b24fa93 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -19,7 +19,7 @@ Python-related news. Python Weekly ~~~~~~~~~~~~~ -Python Weekly is a free weekly newsletter featureing curated news, articles, -new releases, jobs etc related to Python. +Python Weekly is a free weekly newsletter featuring curated news, articles, +new releases, jobs, etc. related to Python. `Python Weekly `_ From 96521d2d02d2468fc34a387f68aaabbbfdcdfee1 Mon Sep 17 00:00:00 2001 From: Ryan Day Date: Wed, 4 Jan 2012 23:00:09 -0500 Subject: [PATCH 09/26] Add benchmarks --- docs/scenarios/speed.rst | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 9a559fe..8e18b5b 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -3,7 +3,28 @@ Speed CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. `PyPy`_ is fast. -.. todo:: Fill in stub for Speed comparisons +Using a slightly modified version of `David Beazleys`_ CPU bound test code(added loop for multiple tests), you can see the difference between CPython and PyPy's processing. + +.. pypy:: + $ ./pypy -V + Python 2.7.1 (7773f8fc4223, Nov 18 2011, 18:47:10) + [PyPy 1.7.0 with GCC 4.4.3] + $ ./pypy measure2.py + 0.0683999061584 + 0.0483210086823 + 0.0388588905334 + 0.0440690517426 + 0.0695300102234 + +.. python:: + $ ./python -V + Python 2.7.1 + $ ./python measure2.py + 1.06774401665 + 1.45412397385 + 1.51485204697 + 1.54693889618 + 1.60109114647 Context ::::::: @@ -67,4 +88,5 @@ Multiprocessing .. _`The GIL`: http://wiki.python.org/moin/GlobalInterpreterLock .. _`guide`: http://www.dabeaz.com/python/UnderstandingGIL.pdf .. _`New GIL`: http://www.dabeaz.com/python/NewGIL.pdf -.. _`Special care`: http://docs.python.org/c-api/init.html#threads \ No newline at end of file +.. _`Special care`: http://docs.python.org/c-api/init.html#threads +.. _`David Beazleys`: http://www.dabeaz.com/GIL/gilvis/measure2.py From 211106071220bbd55c538d8063f9c45d0bdba0d8 Mon Sep 17 00:00:00 2001 From: Ryan Day Date: Wed, 4 Jan 2012 23:06:19 -0500 Subject: [PATCH 10/26] Fix formatting --- docs/scenarios/speed.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 8e18b5b..bd83cde 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -5,7 +5,9 @@ CPython, the most commonly used implementation of Python, is slow for CPU bound Using a slightly modified version of `David Beazleys`_ CPU bound test code(added loop for multiple tests), you can see the difference between CPython and PyPy's processing. -.. pypy:: +:: + + PyPy $ ./pypy -V Python 2.7.1 (7773f8fc4223, Nov 18 2011, 18:47:10) [PyPy 1.7.0 with GCC 4.4.3] @@ -16,7 +18,9 @@ Using a slightly modified version of `David Beazleys`_ CPU bound test code(added 0.0440690517426 0.0695300102234 -.. python:: +:: + + CPython $ ./python -V Python 2.7.1 $ ./python measure2.py From 7e3b364d0ff7971f62adbc160e93ea0410205a96 Mon Sep 17 00:00:00 2001 From: John Del Rosario Date: Thu, 5 Jan 2012 15:06:24 +0800 Subject: [PATCH 11/26] Make virtualenvs conform to the style guide a bit more. Plus some additional changes --- docs/dev/virtualenvs.rst | 63 +++++++++++++++++++++++++++------------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 942406e..9def09b 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -14,29 +14,37 @@ virtualenv `virtualenv `_ is a tool to create isolated Python environments. -Install it via pip:: +Install it via pip: + +.. code-block:: console $ pip install virtualenv Basic Usage ~~~~~~~~~~~ -1. Create a virtual environment:: +1. Create a virtual environment: - $ virtualenv ENVIRONMENT_NAME +.. code-block:: console + + $ virtualenv venv This creates a copy of Python in whichever directory you ran the command in, -placing it in a folder named ``ENVIRONMENT_NAME``. +placing it in a folder named ``venv``. -2. To begin using the virtual environment, it needs to be activated:: +2. To begin using the virtual environment, it needs to be activated: - $ source ENVIRONMENT_NAME/bin/activate +.. code-block:: console + + $ source venv/bin/activate You can then begin installing any new modules without affecting the system default Python or other virtual environments. 3. If you are done working in the virtual environment for the moment, you can - deactivate it:: + deactivate it: + +.. code-block:: console $ deactivate @@ -45,33 +53,43 @@ installed libraries. To delete a virtual environment, just delete its folder. +After a while, though, you might end up with a lot of virtual environments +littered across your system, and its possible you'll forget their names or +where they were placed. + virtualenvwrapper ----------------- `virtualenvwrapper `_ provides a set of commands which makes working with virtual environments much -more pleasant. It also places all your virtual environments into one place. +more pleasant. It also places all your virtual environments in one place. -To install (make sure **virtualenv** is already installed):: +To install (make sure **virtualenv** is already installed): + +.. code-block:: console $ pip install virtualenvwrapper $ export WORKON_HOME=~/Envs $ source /usr/local/bin/virtualenvwrapper.sh -(Full instructions `here `_.) +(`Full virtualenvwrapper install instructions `_.) Basic Usage ~~~~~~~~~~~ -1. Create a virtual environment:: +1. Create a virtual environment: - $ mkvirtualenv ENVIRONMENT_NAME +.. code-block:: console -This creates the ``ENVIRONMENT_NAME`` folder inside ``~/Envs``. + $ mkvirtualenv venv -2. Work on a virtual environment:: +This creates the ``venv`` folder inside ``~/Envs``. - $ workon ENVIRONMENT_NAME +2. Work on a virtual environment: + +.. code-block:: console + + $ workon venv **virtualenvwrapper** provides tab-completion on environment names. It really helps when you have a lot of environments and have trouble remembering their @@ -79,15 +97,20 @@ names. ``workon`` also deactivates whatever environment you are currently in, so you can quickly switch between environments. -3. Deactivating is still the same:: +3. Deactivating is still the same: + +.. code-block:: console $ deactivate -4. To delete:: +4. To delete: - $ rmvirtualenv ENVIRONMENT_NAME +.. code-block:: console -Other nifty commands include: + $ rmvirtualenv venv + +Other useful commands +~~~~~~~~~~~~~~~~~~~~~ ``lsvirtualenv`` List all of the environments. @@ -102,4 +125,4 @@ Other nifty commands include: ``lssitepackages`` Shows contents of ``site-packages`` directory. -A full list of commands can be found `here `_. +`Full list of virtualenvwrapper commands `_. From b99d3e2ceadf585d3e7bb98ba023349dddb685eb Mon Sep 17 00:00:00 2001 From: Georges Dubus Date: Thu, 5 Jan 2012 12:10:42 +0100 Subject: [PATCH 12/26] Added a word about free plans for hosting --- docs/scenarios/web.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 294c205..affa629 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -255,6 +255,9 @@ DotCloud uses a custom command-line API client which can work with applications managed in git repositories or any other version control system. +DotCloud has a free plan with limited database size, and without extra +services (caching…). + See the `DotCloud documentation on Python `_ for more information and help getting started. @@ -267,6 +270,10 @@ ep.io applications. It supports Python versions 2.6 and 2.7, and has Pythonic integrations with a variety of services. +ep.io has a free plan with bandwidth and disk space limitations. Also, in the +free plan, the web process is only loaded when needed. This means that the +first request after some inactivity may take up to 15 seconds. + ep.io publishes `step-by-step instructions `_ on how to get started with their platform and how to deploy Django, Flask, or generic WSGI applications. From 1cb7d0fa1f0fb1fabdcf06c7f7b593d6cfcf1e4a Mon Sep 17 00:00:00 2001 From: Natan L Date: Tue, 10 Jan 2012 19:24:40 -0800 Subject: [PATCH 13/26] Tuned a todo typo. --- 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 294c205..5a8402a 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -78,7 +78,7 @@ flask@librelist.com and reply to the confirmation email. Pyramid ------- -.. todo:: Explian Pyramid +.. todo:: Explain Pyramid Web.py ------ From af511e356a1c96bbb840e96cfa10ad793d525326 Mon Sep 17 00:00:00 2001 From: Georges Dubus Date: Sun, 15 Jan 2012 14:21:54 +0100 Subject: [PATCH 14/26] Free plan for heroku --- docs/scenarios/web.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 43d3b06..b01287c 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -236,6 +236,8 @@ Heroku applications at some point. Heroku uses a git-based workflow, so it is well-suited for use with applications whose source control is managed in a git repository. +Heroku has a free plan with one web process and limited database space. + Heroku publishes `step-by-step instructions `_ on how to set up your first application for use in Heroku, and maintains a list of `example applications From b22fbd4416dc25aa5972759b0c1239447e7aaf84 Mon Sep 17 00:00:00 2001 From: Seyi Ogunyemi Date: Sun, 15 Jan 2012 15:37:34 +0000 Subject: [PATCH 15/26] Update docs/scenarios/gui.rst --- docs/scenarios/gui.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 037c641..08ee3b4 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -34,6 +34,8 @@ Install (Stable) Gtk ::: +PyGTK proveds Python bindings for the GTK+ toolkit. Like the GTK+ library itself, it is currently licensed under the GNU LGPL. It is worth noting that PyGTK only currenty supports the Gtk-2.X API (NOT Gtk-3.0). It is currently recommended that PyGTK is not used for new projects and existing applications be ported from PyGTK to PyGObject. tk :: +Tkinter is a thin object-oriented layer on top of Tcl/Tk. Both Tk and Tkinter are available on most Unix platforms, as well as on Windows and Macintosh systems. Starting with the 8.0 release, Tk offers native look and feel on all platforms. \ No newline at end of file From 7af86a2eaf2d66d4d9e3cf5ca5f323fa65b8602c Mon Sep 17 00:00:00 2001 From: Seyi Ogunyemi Date: Sun, 15 Jan 2012 15:49:21 +0000 Subject: [PATCH 16/26] Update docs/dev/env.rst --- docs/dev/env.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 14904ba..99ccf7b 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -223,6 +223,17 @@ IPython BPython ------- +`bpython `_ is an alternative interface to the Python interpreter for Unix-like operating systems. It has the following features: + +* In-line syntax highlighting. +* Readline-like autocomplete with suggestions displayed as you type. +* Expected parameter list for any Python function. +* "Rewind" function to pop the last line of code from memory and re-evaluate. +* Send entered code off to a pastebin. +* Save entered code to a file. +* Auto-indentation. +* Python 3 support. + :: $ pip install bpython From 9450609a313e9d5c19a018cc5e18f2a5abc2620c Mon Sep 17 00:00:00 2001 From: Seyi Ogunyemi Date: Sun, 15 Jan 2012 15:55:57 +0000 Subject: [PATCH 17/26] Update docs/scenarios/ci.rst --- docs/scenarios/ci.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 285e522..d2abfa9 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -29,4 +29,9 @@ Mule? Tox --- -.. todo:: Write about `Tox `_ +`tox `_ is an automation tool providing packaging, testing and deployment of Python software right from the console or CI server. +It is a generic virtualenv management and test command line tool which provides the following features: + +* Checking that packages install correctly with different Python versions and interpreters +* Running tests in each of the environments, configuring your test tool of choice +* Acting as a frontend to Continuous Integration servers, reducing boilerplate and merging CI and shell-based testing. \ No newline at end of file From d473519d1d82ee5158fdd9397ab8c21cf2a4547b Mon Sep 17 00:00:00 2001 From: Boryslav Date: Sun, 15 Jan 2012 18:47:38 +0200 Subject: [PATCH 18/26] Fixed broken link to Django docs --- 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 b01287c..c10ad8d 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -308,7 +308,7 @@ In fact it used to be called python-hosting.com. Webfaction supports Python vers as well as Python 3 versions. Webfaction has a very extensive `user guide `_ -and specific stack (`Django `_, `Pylons `_, +and specific stack (`Django `_, `Pylons `_, `Pyramid `_, `TurboGears `_ and `vanilla python `_) guides. It also has a stack-overflow style `community `_ that is quite useful. From eecd35785b91a6cd596e62938686e4da4d6b073f Mon Sep 17 00:00:00 2001 From: Kamil Kisiel Date: Tue, 17 Jan 2012 20:24:57 -0800 Subject: [PATCH 19/26] Added links to Tk tutorials --- docs/scenarios/gui.rst | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 08ee3b4..2490d98 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -34,8 +34,22 @@ Install (Stable) Gtk ::: -PyGTK proveds Python bindings for the GTK+ toolkit. Like the GTK+ library itself, it is currently licensed under the GNU LGPL. It is worth noting that PyGTK only currenty supports the Gtk-2.X API (NOT Gtk-3.0). It is currently recommended that PyGTK is not used for new projects and existing applications be ported from PyGTK to PyGObject. +PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library +itself, it is currently licensed under the GNU LGPL. It is worth noting that +PyGTK only currenty supports the Gtk-2.X API (NOT Gtk-3.0). It is currently +recommended that PyGTK is not used for new projects and existing applications be +ported from PyGTK to PyGObject. -tk +Tk :: -Tkinter is a thin object-oriented layer on top of Tcl/Tk. Both Tk and Tkinter are available on most Unix platforms, as well as on Windows and Macintosh systems. Starting with the 8.0 release, Tk offers native look and feel on all platforms. \ No newline at end of file +Tkinter is a thin object-oriented layer on top of Tcl/Tk. It has the advantage +of being included with the Python standard library, making it the most +convenient and compatible toolkit to program with. + +Both Tk and Tkinter are available on most Unix platforms, as well as on Windows +and Macintosh systems. Starting with the 8.0 release, Tk offers native look and +feel on all platforms. + +There's a good multi-language Tk tutorial with Python examples at +`TkDocs `_. There's more information +available on the `Python Wiki `_. From b468b2e8fbc896fc3e186f8ee25b5b5b242d1ae9 Mon Sep 17 00:00:00 2001 From: Brian Painter Date: Wed, 18 Jan 2012 00:10:10 -0500 Subject: [PATCH 20/26] Added Windows installation steps Put more detailed information on setting PATH as step one and changed pip install to look like windows command line syntax --- docs/starting/installation.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index e4890e3..f567f38 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -89,7 +89,18 @@ Prerequisites: * Microsoft Visual Studio -Step 1: Install Distribute & Pip +Step 1: Set PATH variables +-------------------------- +If you haven't set your PATH variables as part of the Python2.7 install, now is the time to do that. Right click on My Computer and select properties. +**Windows 7**: +* Click Advanced System Settings from left hand list +* Click the Environment Variables button at the bottom +* In the System variables section double click on the variable line named Path +* Scroll to the end of the variable value field +* add semicolon (;) if one doesn't exist and then type **C:\Python27\;C:\Python27\Scripts\** + + +Step 2: Install Distribute & Pip -------------------------------- **Distribute** is a fantastic drop-in replacement for **easy_install** and **setuptools**. It allows you to install and manage python packages from PyPi, amongst a few other sources. @@ -97,13 +108,11 @@ Step 1: Install Distribute & Pip To install it, run the python script available here: -Make sure that ```C:\Python27\```, and ```C:\Python27\Scripts``` are in your PATH. - **easy_install** is considered by many to be a deprecated system, so we will install it's replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike setuptool's easy_install. -To install pip, simply run: :: +To install pip, simply open a command prompt and run: :: - $ easy_install pip + > easy_install pip Linux (Ubuntu) From 1c5f7e04f80fc9be35ad8046d98fded1f11db93f Mon Sep 17 00:00:00 2001 From: BrianPainter Date: Wed, 18 Jan 2012 08:26:33 -0500 Subject: [PATCH 21/26] Update docs/starting/installation.rst --- docs/starting/installation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index f567f38..43f729c 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -92,7 +92,9 @@ Prerequisites: Step 1: Set PATH variables -------------------------- If you haven't set your PATH variables as part of the Python2.7 install, now is the time to do that. Right click on My Computer and select properties. -**Windows 7**: + +**Windows 7** + * Click Advanced System Settings from left hand list * Click the Environment Variables button at the bottom * In the System variables section double click on the variable line named Path From e5e124e851358088efb189af98e88e0a59174412 Mon Sep 17 00:00:00 2001 From: BrianPainter Date: Wed, 18 Jan 2012 08:27:34 -0500 Subject: [PATCH 22/26] Update docs/starting/installation.rst --- docs/starting/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 43f729c..2f64d6e 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -99,7 +99,7 @@ If you haven't set your PATH variables as part of the Python2.7 install, now is * Click the Environment Variables button at the bottom * In the System variables section double click on the variable line named Path * Scroll to the end of the variable value field -* add semicolon (;) if one doesn't exist and then type **C:\Python27\;C:\Python27\Scripts\** +* add semicolon (;) if one doesn't exist and then type ``C:\Python27\;C:\Python27\Scripts\`` Step 2: Install Distribute & Pip From 8d48118a5f4a1e855614a8862ba0c7d27c78294a Mon Sep 17 00:00:00 2001 From: BrianPainter Date: Wed, 18 Jan 2012 08:32:16 -0500 Subject: [PATCH 23/26] Update docs/starting/installation.rst --- docs/starting/installation.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 2f64d6e..aa2c9e7 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -93,15 +93,14 @@ Step 1: Set PATH variables -------------------------- If you haven't set your PATH variables as part of the Python2.7 install, now is the time to do that. Right click on My Computer and select properties. -**Windows 7** - -* Click Advanced System Settings from left hand list +* Click Advanced System Settings from left hand list (On Windows XP click the Advanced Tab) * Click the Environment Variables button at the bottom * In the System variables section double click on the variable line named Path * Scroll to the end of the variable value field * add semicolon (;) if one doesn't exist and then type ``C:\Python27\;C:\Python27\Scripts\`` + Step 2: Install Distribute & Pip -------------------------------- From 4c852e31b5bfc893ad591dfeadfbb40b84f7e4a1 Mon Sep 17 00:00:00 2001 From: Brian Painter Date: Wed, 18 Jan 2012 08:49:26 -0500 Subject: [PATCH 24/26] Fixed Style First time using the style --- docs/starting/installation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index f567f38..433a73f 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -92,12 +92,12 @@ Prerequisites: Step 1: Set PATH variables -------------------------- If you haven't set your PATH variables as part of the Python2.7 install, now is the time to do that. Right click on My Computer and select properties. -**Windows 7**: -* Click Advanced System Settings from left hand list +**Windows 7** +* Click Advanced System Settings from left hand list (Advanced Tab on Windows XP) * Click the Environment Variables button at the bottom * In the System variables section double click on the variable line named Path * Scroll to the end of the variable value field -* add semicolon (;) if one doesn't exist and then type **C:\Python27\;C:\Python27\Scripts\** +* add semicolon (;) if one doesn't exist and then type ``C:\Python27\;C:\Python27\Scripts\`` Step 2: Install Distribute & Pip From 8aadcc9f108fcf867ef4846659c817fd1d1f8211 Mon Sep 17 00:00:00 2001 From: Brian Painter Date: Wed, 18 Jan 2012 09:02:26 -0500 Subject: [PATCH 25/26] Fixed formatting First time using this formatting, fixed my errors --- docs/starting/installation.rst | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index c1ab595..545b49c 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -92,22 +92,14 @@ Prerequisites: Step 1: Set PATH variables -------------------------- If you haven't set your PATH variables as part of the Python2.7 install, now is the time to do that. Right click on My Computer and select properties. -<<<<<<< HEAD + **Windows 7** * Click Advanced System Settings from left hand list (Advanced Tab on Windows XP) -======= - * Click Advanced System Settings from left hand list (On Windows XP click the Advanced Tab) ->>>>>>> 8d48118a5f4a1e855614a8862ba0c7d27c78294a * Click the Environment Variables button at the bottom * In the System variables section double click on the variable line named Path * Scroll to the end of the variable value field * add semicolon (;) if one doesn't exist and then type ``C:\Python27\;C:\Python27\Scripts\`` -<<<<<<< HEAD -======= - ->>>>>>> 8d48118a5f4a1e855614a8862ba0c7d27c78294a - Step 2: Install Distribute & Pip -------------------------------- From 7be91a60e6389a808eb074a34d17673ceba10545 Mon Sep 17 00:00:00 2001 From: BrianPainter Date: Wed, 18 Jan 2012 09:05:30 -0500 Subject: [PATCH 26/26] Update docs/starting/installation.rst --- docs/starting/installation.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 545b49c..099dc27 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -93,7 +93,6 @@ Step 1: Set PATH variables -------------------------- If you haven't set your PATH variables as part of the Python2.7 install, now is the time to do that. Right click on My Computer and select properties. -**Windows 7** * Click Advanced System Settings from left hand list (Advanced Tab on Windows XP) * Click Advanced System Settings from left hand list (On Windows XP click the Advanced Tab) * Click the Environment Variables button at the bottom