mirror of
https://github.com/kennethreitz/python-guide.git
synced 2026-06-05 23:00:18 +00:00
Merge remote-tracking branch 'origin/master'
This commit is contained in:
Kenneth Reitz
@@ -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
|
||||
|
||||
@@ -223,6 +223,17 @@ IPython
|
||||
BPython
|
||||
-------
|
||||
|
||||
`bpython <http://bpython-interpreter.org/>`_ 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
|
||||
|
||||
+116
-3
@@ -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 <http://pypi.python.org/pypi/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 <http://www.doughellmann.com/projects/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 <http://www.doughellmann.com/docs/virtualenvwrapper/#introduction>`_.)
|
||||
|
||||
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 <http://www.doughellmann.com/docs/virtualenvwrapper/command_ref.html#managing-environments>`_.
|
||||
|
||||
@@ -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 <http://www.python.org/dev/peps/pep-0001/>`_):
|
||||
|
||||
@@ -70,4 +70,4 @@ A comprehensive list of conferences is maintained `at pycon.org <http://www.pyco
|
||||
Python User Groups
|
||||
--------------------------
|
||||
|
||||
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 <http://wiki.python.org/moin/LocalUserGroups>`_.
|
||||
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 <http://wiki.python.org/moin/LocalUserGroups>`_.
|
||||
|
||||
@@ -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 <http://greenteapress.com/thinkpython/html/index.html>`_
|
||||
|
||||
+2
-2
@@ -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 <http://www.pythonweekly.com/>`_
|
||||
|
||||
@@ -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
|
||||
@@ -7,7 +7,7 @@ Why?
|
||||
|
||||
Martin Fowler, who first wrote about `Continuous Integration <http://martinfowler.com/articles/continuousIntegration.html>`_ (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 <http://codespeak.net/~hpk/tox/>`_
|
||||
`tox <https://bitbucket.org/hpk42/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.
|
||||
+21
-3
@@ -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
|
||||
::
|
||||
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 <http://www.tkdocs.com/tutorial/index.html>`_. There's more information
|
||||
available on the `Python Wiki <http://wiki.python.org/moin/TkInter>`_.
|
||||
|
||||
@@ -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
|
||||
.. _`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
|
||||
|
||||
+14
-3
@@ -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 <http://groups.google.com/group/webpy>`_ .
|
||||
|
||||
|
||||
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
|
||||
<http://devcenter.heroku.com/articles/python>`_ 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
|
||||
<http://docs.dotcloud.com/services/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
|
||||
<https://www.ep.io/docs/quickstart/>`_ 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 <http://docs.webfaction.com/user-guide/>`_
|
||||
and specific stack (`Django <http://docs.webfaction.com/software/django/index.html> `_, `Pylons <http://docs.webfaction.com/software/pylons.html>`_,
|
||||
and specific stack (`Django <http://docs.webfaction.com/software/django/index.html>`_, `Pylons <http://docs.webfaction.com/software/pylons.html>`_,
|
||||
`Pyramid <http://docs.webfaction.com/software/pyramid.html>`_, `TurboGears <http://docs.webfaction.com/software/turbogears.html>`_
|
||||
and `vanilla python <http://docs.webfaction.com/software/python.html>`_) guides.
|
||||
It also has a stack-overflow style `community <http://community.webfaction.com/>`_ that is quite useful.
|
||||
@@ -312,4 +323,4 @@ Node.js.
|
||||
|
||||
.. [1] `The mod_python project is now officially dead <http://blog.dscpl.com.au/2010/06/modpython-project-is-now-officially.html>`_
|
||||
.. [2] `mod_wsgi vs mod_python <http://www.modpython.org/pipermail/mod_python/2007-July/024080.html>`_
|
||||
.. [3] `Benchmark of Python WSGI Servers <http://nichol.as/benchmark-of-python-web-servers>`_
|
||||
.. [3] `Benchmark of Python WSGI Servers <http://nichol.as/benchmark-of-python-web-servers>`_
|
||||
|
||||
@@ -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:
|
||||
<http://python-distribute.org/distribute_setup.py>
|
||||
|
||||
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)
|
||||
|
||||
@@ -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
|
||||
----
|
||||
----
|
||||
|
||||
Reference in New Issue
Block a user