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/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 diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 385fe94..9def09b 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -1,15 +1,128 @@ 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 while also +maintaining 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: + +.. code-block:: console + + $ pip install virtualenv + +Basic Usage +~~~~~~~~~~~ + +1. Create a virtual environment: + +.. 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 ``venv``. + +2. To begin using the virtual environment, it needs to be activated: + +.. 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: + +.. code-block:: console + + $ 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. + +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 ----------------- -.. 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 in one place. +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 virtualenvwrapper install instructions `_.) + +Basic Usage +~~~~~~~~~~~ + +1. Create a virtual environment: + +.. code-block:: console + + $ mkvirtualenv venv + +This creates the ``venv`` folder inside ``~/Envs``. + +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 +names. +``workon`` also deactivates whatever environment you are currently in, so you +can quickly switch between environments. + +3. Deactivating is still the same: + +.. code-block:: console + + $ deactivate + +4. To delete: + +.. code-block:: console + + $ rmvirtualenv venv + +Other useful commands +~~~~~~~~~~~~~~~~~~~~~ + +``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 virtualenvwrapper commands `_. 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 `_ 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/ci.rst b/docs/scenarios/ci.rst index 15166a2..d2abfa9 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 ------- @@ -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 diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 8572f7b..2490d98 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -26,12 +26,30 @@ PyObjC WXPython :::::::: + + Install (Stable) ----- +---------------- *Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.* Gtk ::: +PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library +itself, it is currently licensed under the GNU LGPL. It is worth noting that +PyGTK only 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 -:: \ No newline at end of file +Tk +:: +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 `_. diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 81e695c..bd83cde 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -3,7 +3,32 @@ 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 + +:: + + CPython + $ ./python -V + Python 2.7.1 + $ ./python measure2.py + 1.06774401665 + 1.45412397385 + 1.51485204697 + 1.54693889618 + 1.60109114647 Context ::::::: @@ -12,7 +37,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 ------------ @@ -21,8 +52,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 :::::::::::: @@ -57,4 +88,9 @@ Multiprocessing --------------- -.. _`PyPy`: http://pypy.org \ No newline at end of file +.. _`PyPy`: http://pypy.org +.. _`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 +.. _`David Beazleys`: http://www.dabeaz.com/GIL/gilvis/measure2.py diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 67f240f..c10ad8d 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 ------ @@ -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 ::::::::::: @@ -234,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 @@ -253,6 +257,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. @@ -265,6 +272,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. @@ -297,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. @@ -312,4 +323,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 `_ diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index ace753f..099dc27 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. @@ -93,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. + +* 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 +* 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. @@ -101,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) 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 +----