mirror of
https://github.com/kennethreitz/python-guide.git
synced 2026-06-05 14:50:19 +00:00
Merge remote branch 'original/master'
This commit is contained in:
Ryan Day
Vendored
+3
-4
@@ -2,17 +2,16 @@
|
||||
{%- block extrahead %}
|
||||
{{ super() }}
|
||||
{% if theme_touch_icon %}
|
||||
<link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
|
||||
<link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
|
||||
{% endif %}
|
||||
<link media="only screen and (max-device-width: 480px)" href="{{
|
||||
pathto('_static/small_flask.css', 1) }}" type= "text/css" rel="stylesheet" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
|
||||
{% endblock %}
|
||||
{%- block relbar2 %}{% endblock %}
|
||||
{%- block footer %}
|
||||
<div class="footer">
|
||||
© Copyright {{ copyright }}.
|
||||
</div>
|
||||
<a href="https://github.com/kennethreitz/python-guide">
|
||||
<a href="https://github.com/kennethreitz/python-guide" class="github">
|
||||
<img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" />
|
||||
</a>
|
||||
|
||||
|
||||
Vendored
+150
-2
@@ -91,8 +91,8 @@ div.sphinxsidebarwrapper {
|
||||
}
|
||||
|
||||
div.sphinxsidebarwrapper p.logo {
|
||||
padding: 0 0 20px 0;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
margin: -10px 0 0 -20px;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
@@ -387,6 +387,148 @@ a:hover tt {
|
||||
}
|
||||
|
||||
|
||||
@media screen and (max-width: 870px) {
|
||||
|
||||
div.sphinxsidebar {
|
||||
display: none;
|
||||
}
|
||||
|
||||
div.document {
|
||||
width: 100%;
|
||||
|
||||
}
|
||||
|
||||
div.documentwrapper {
|
||||
margin-left: 0;
|
||||
margin-top: 0;
|
||||
margin-right: 0;
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
div.bodywrapper {
|
||||
margin-top: 0;
|
||||
margin-right: 0;
|
||||
margin-bottom: 0;
|
||||
margin-left: 0;
|
||||
}
|
||||
|
||||
ul {
|
||||
margin-left: 0;
|
||||
}
|
||||
|
||||
.document {
|
||||
width: auto;
|
||||
}
|
||||
|
||||
.footer {
|
||||
width: auto;
|
||||
}
|
||||
|
||||
.bodywrapper {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.footer {
|
||||
width: auto;
|
||||
}
|
||||
|
||||
.github {
|
||||
display: none;
|
||||
}
|
||||
|
||||
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
||||
@media screen and (max-width: 875px) {
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 20px 30px;
|
||||
}
|
||||
|
||||
div.documentwrapper {
|
||||
float: none;
|
||||
background: white;
|
||||
}
|
||||
|
||||
div.sphinxsidebar {
|
||||
display: block;
|
||||
float: none;
|
||||
width: 102.5%;
|
||||
margin: 50px -30px -20px -30px;
|
||||
padding: 10px 20px;
|
||||
background: #333;
|
||||
color: white;
|
||||
}
|
||||
|
||||
div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
|
||||
div.sphinxsidebar h3 a {
|
||||
color: white;
|
||||
}
|
||||
|
||||
div.sphinxsidebar a {
|
||||
color: #aaa;
|
||||
}
|
||||
|
||||
div.sphinxsidebar p.logo {
|
||||
display: none;
|
||||
}
|
||||
|
||||
div.document {
|
||||
width: 100%;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
div.related {
|
||||
display: block;
|
||||
margin: 0;
|
||||
padding: 10px 0 20px 0;
|
||||
}
|
||||
|
||||
div.related ul,
|
||||
div.related ul li {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
div.footer {
|
||||
display: none;
|
||||
}
|
||||
|
||||
div.bodywrapper {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
div.body {
|
||||
min-height: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.rtd_doc_footer {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.document {
|
||||
width: auto;
|
||||
}
|
||||
|
||||
.footer {
|
||||
width: auto;
|
||||
}
|
||||
|
||||
.footer {
|
||||
width: auto;
|
||||
}
|
||||
|
||||
.github {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/* scrollbars */
|
||||
|
||||
::-webkit-scrollbar {
|
||||
@@ -420,3 +562,9 @@ a:hover tt {
|
||||
background-color: #ccc;
|
||||
-webkit-border-radius: 3px;
|
||||
}
|
||||
|
||||
/* misc. */
|
||||
|
||||
.revsys-inline {
|
||||
display: none!important;
|
||||
}
|
||||
+5
-3
@@ -25,7 +25,7 @@ sys.path.append(os.path.abspath('_themes'))
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = ['sphinx.ext.ifconfig']
|
||||
extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
@@ -41,7 +41,7 @@ master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'pythonguide'
|
||||
copyright = u'2011. A <a href="http://kennethreitz.com/pages/open-projects.html">Kenneth Reitz</a> Project'
|
||||
copyright = u'2012. A <a href="http://kennethreitz.com/pages/open-projects.html">Kenneth Reitz</a> Project'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
@@ -182,7 +182,7 @@ htmlhelp_basename = 'pythonguidedoc'
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'pythonguide.tex', u'Pythong Guide Documentation',
|
||||
('index', 'pythonguide.tex', u'Python Guide Documentation',
|
||||
u'Kenneth Reitz', 'manual'),
|
||||
]
|
||||
|
||||
@@ -258,3 +258,5 @@ epub_copyright = u'2010, Kenneth Reitz'
|
||||
|
||||
# Allow duplicate toc entries.
|
||||
#epub_tocdup = True
|
||||
|
||||
todo_include_todos = True
|
||||
+11
-3
@@ -24,10 +24,17 @@ This part of the guide focuses on setting up your Python environment.
|
||||
|
||||
starting/which-python
|
||||
starting/installation
|
||||
starting/dev-env
|
||||
starting/next
|
||||
|
||||
|
||||
Development Environment
|
||||
-----------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
dev/env
|
||||
dev/virtualenvs
|
||||
|
||||
Writing Great Code
|
||||
------------------
|
||||
|
||||
@@ -72,7 +79,7 @@ different scenarios.
|
||||
scenarios/admin
|
||||
scenarios/ci
|
||||
scenarios/speed
|
||||
|
||||
scenarios/scientific
|
||||
|
||||
|
||||
Additional Notes
|
||||
@@ -85,3 +92,4 @@ Contibution notes and legal information are here (for those interested).
|
||||
|
||||
notes/contribute
|
||||
notes/license
|
||||
notes/styleguide
|
||||
|
||||
@@ -0,0 +1,230 @@
|
||||
Your Development Environment
|
||||
============================
|
||||
|
||||
|
||||
Text Editors
|
||||
::::::::::::
|
||||
|
||||
Just about anything which can edit plain text will work for writing Python code,
|
||||
however, using a more powerful editor may make your life a bit easier.
|
||||
|
||||
|
||||
VIM
|
||||
---
|
||||
|
||||
|
||||
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 linewrapping to values compliant with PEP8::
|
||||
|
||||
set textwidth=79
|
||||
set shiftwidth=4
|
||||
set tabstop=4
|
||||
set expandtab
|
||||
set softtabstop=4
|
||||
set shiftround
|
||||
|
||||
With these settings newlines are inserted after 79 characters and indentation
|
||||
is set to 4 spaces per tab. If you also use VIM for other languages, there is a
|
||||
handy plugin at indent_, which handles indentation settings for python source
|
||||
files.
|
||||
Additionally there is also a handy syntax plugin at syntax_ featuring some
|
||||
improvements over the syntax file included in VIM 6.1.
|
||||
|
||||
These plugins supply you with a basic environment for developing in Python.
|
||||
However in order to improve the programming flow we also want to continually
|
||||
check for PEP8 compliance and check syntax. Luckily there exist PEP8_ and
|
||||
Pyflakes_ to do this for you. If your VIM is compiled with `+python` you can
|
||||
also utilize some very handy plugins to do these checks from within the editor.
|
||||
For PEP8 checking install vim-pep8_. Now you can map the vim function
|
||||
`Pep8()` to any hotkey or action you want. Similarly for pyflakes you can
|
||||
install vim-pyflakes_. Now you can map `Pyflakes()` like the PEP8 function and
|
||||
have it called quickly. Both plugins will display errors in a quickfix list and
|
||||
provide an easy way to jump to the corresponding line. A very handy setting is
|
||||
calling these functions whenever a buffer is saved. In order to do this, enter
|
||||
the following lines into your vimrc::
|
||||
|
||||
autocmd BufWritePost *.py call Pyflakes()
|
||||
autocmd BufWritePost *.py call Pep8()
|
||||
|
||||
|
||||
.. _indent: http://www.vim.org/scripts/script.php?script_id=974
|
||||
.. _syntax: http://www.vim.org/scripts/script.php?script_id=790
|
||||
.. _Pyflakes: http://pypi.python.org/pypi/pyflakes/
|
||||
.. _vim-pyflakes: https://github.com/nvie/vim-pyflakes
|
||||
.. _PEP8: http://pypi.python.org/pypi/pep8/
|
||||
.. _vim-pep8: https://github.com/nvie/vim-pep8
|
||||
|
||||
.. todo:: add supertab notes
|
||||
|
||||
TextMate
|
||||
--------
|
||||
|
||||
"`TextMate <http://macromates.com/>`_ brings Apple's approach to operating systems into the world of text editors. By bridging UNIX underpinnings and GUI, TextMate cherry-picks the best of both worlds to the benefit of expert scripters and novice users alike."
|
||||
|
||||
Sublime Text
|
||||
------------
|
||||
|
||||
"`Sublime Text <http://www.sublimetext.com/>`_ is a sophisticated text editor
|
||||
for code, html and prose. You'll love the slick user interface and
|
||||
extraordinary features."
|
||||
|
||||
Sublime Text has excellent support for editing Python code and uses Python for
|
||||
its plugin API.
|
||||
|
||||
`Sublime Text 2 <http://www.sublimetext.com/blog/articles/sublime-text-2-beta>`_ is currently in beta.
|
||||
|
||||
IDEs
|
||||
::::
|
||||
|
||||
PyCharm / IntelliJ IDEA
|
||||
-----------------------
|
||||
|
||||
`PyCharm <http://www.jetbrains.com/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 <http://plugins.intellij.net/plugin/?id=631/>`_.
|
||||
|
||||
Eclipse
|
||||
-------
|
||||
|
||||
The most popular Eclipse plugin for Python development is Aptana's
|
||||
`PyDev <http://pydev.org>`_.
|
||||
|
||||
|
||||
Komodo IDE
|
||||
-----------
|
||||
`Komodo IDE <http://www.activestate.com/komodo-ide>`_ is developed by ActiveState and is a commerical IDE for Windows, Mac
|
||||
and Linux.
|
||||
|
||||
Spyder
|
||||
------
|
||||
|
||||
`Spyder <http://code.google.com/p/spyderlib/>`_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy <http://www.scipy.org/>`_).
|
||||
Includes integration with pyflakes_, `pylint <http://www.logilab.org/857>`_,
|
||||
and `rope <http://rope.sourceforge.net/>`_.
|
||||
|
||||
Spyder is open-source (free), offers code completion, syntax highlighting, class and function browser, and object inspection.
|
||||
|
||||
|
||||
|
||||
Interpreter Tools
|
||||
:::::::::::::::::
|
||||
|
||||
|
||||
virtualenv
|
||||
----------
|
||||
|
||||
Virtualenv is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them.
|
||||
It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma and keeps your global site-packages directory clean and manageable.
|
||||
|
||||
`virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates
|
||||
a folder which contains all the necessary executables to contain the
|
||||
packages that a Python project would need. An example workflow is given.
|
||||
|
||||
Install virtualenv::
|
||||
|
||||
$ pip install virtualenv
|
||||
|
||||
|
||||
Create a virtual environment for a project::
|
||||
|
||||
$ cd my_project
|
||||
$ virtualenv venv
|
||||
|
||||
``virtualenv venv`` will create a folder in the currect directory
|
||||
which will contain the Python executable files, and a copy of the ``pip``
|
||||
library which you can use to install other packages. The name of the
|
||||
virtual environment (in this case, it was ``venv``) can be anything;
|
||||
omitting the name will place the files in the current directory instead.
|
||||
|
||||
In order the start using the virtual environment, run::
|
||||
|
||||
$ source venv/bin/activate
|
||||
|
||||
|
||||
The name of the current virtual environment will now appear on the left
|
||||
of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to
|
||||
let you know that it's active. From now on, any package that you install
|
||||
using ``pip`` will be placed in the venv folder, isolated from the global
|
||||
Python installation. Install packages as usual::
|
||||
|
||||
$ pip install requests
|
||||
|
||||
To stop using an environment simply type ``deactivate``. To remove the
|
||||
environment, just remove the directory it was installed into. (In this
|
||||
case, it would be ``rm -rf venv``).
|
||||
|
||||
Other Notes
|
||||
~~~~~~~~~~~
|
||||
|
||||
Running ``virtualenv`` with the option ``--no-site-packages`` will not
|
||||
include the packages that are installed globally. This can be useful
|
||||
for keeping the package list clean in case it needs to be accessed later.
|
||||
|
||||
In order to keep your environment consistent, it's a good idea to "freeze"
|
||||
the current state of the environment packages. To do this, run
|
||||
|
||||
::
|
||||
|
||||
$ pip freeze > requirements.txt
|
||||
|
||||
This will create a ``requirements.txt`` file, which contains a simple
|
||||
list of all the packages in the current environment, and their respective
|
||||
versions. Later, when a different developer (or you, if you need to re-
|
||||
create the environment) can install the same packages, with the same
|
||||
versions by running
|
||||
|
||||
::
|
||||
|
||||
$ pip install -r requirements.txt
|
||||
|
||||
This can help ensure consistency across installations, across deployments,
|
||||
and across developers.
|
||||
|
||||
Lastly, remember to exclude the virtual environment folder from source
|
||||
control by adding it to the ignore list.
|
||||
|
||||
virtualenvwrapper
|
||||
-----------------
|
||||
|
||||
`Virtualenvwrapper <http://pypi.python.org/pypi/virtualenvwrapper>`_ makes virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
|
||||
|
||||
::
|
||||
|
||||
$ pip install virtualenvwrapper
|
||||
|
||||
|
||||
Put this into your `~/.bash_profile` (Linux/Mac) file:
|
||||
|
||||
::
|
||||
|
||||
$ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
|
||||
|
||||
This will prevent your virtualenvs from relying on your (global) site packages directory, so that they are completely separate..
|
||||
|
||||
Other Tools
|
||||
:::::::::::
|
||||
|
||||
IPython
|
||||
-------
|
||||
|
||||
`IPython <http://ipython.org/>`_ provides a rich toolkit to help you make the most out of using Python interactively. Its main components are:
|
||||
|
||||
* Powerful Python shells (terminal- and Qt-based).
|
||||
* A web-based notebook with the same core features but support for rich media, text, code, mathematical expressions and inline plots.
|
||||
* Support for interactive data visualization and use of GUI toolkits.
|
||||
* Flexible, embeddable interpreters to load into your own projects.
|
||||
* Tools for high level and interactive parallel computing.
|
||||
|
||||
::
|
||||
|
||||
$ pip install ipython
|
||||
|
||||
|
||||
|
||||
BPython
|
||||
-------
|
||||
|
||||
::
|
||||
|
||||
$ pip install bpython
|
||||
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
Virtual Environments
|
||||
====================
|
||||
|
||||
.. todo:: Explain "Virtual Environments"
|
||||
|
||||
virtualenv
|
||||
----------
|
||||
|
||||
.. todo:: Write about virtualenv
|
||||
|
||||
virtualenvwrapper
|
||||
-----------------
|
||||
|
||||
.. todo:: Write about virtualenvwrapper
|
||||
|
||||
+3
-3
@@ -3,10 +3,10 @@
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
The Hitchhikers Guide to Python!
|
||||
================================
|
||||
The Hitchhiker's Guide to Python!
|
||||
=================================
|
||||
|
||||
Welcome to The Hitchhiker's Guide to Python.
|
||||
Welcome to The Hitchhiker's Guide to Python. **DON'T PANIC!**
|
||||
|
||||
**This guide is currently under heavy development, and is mostly a skeleton at the moment.** If you'd like to help, `fork us on GitHub <https://github.com/kennethreitz/python-guide>`_!
|
||||
|
||||
|
||||
@@ -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>`_.
|
||||
|
||||
+36
-1
@@ -1,4 +1,39 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
Someone should write a general blurb introducing the Python language here
|
||||
.. todo:: write a general blurb introducing the Python language
|
||||
|
||||
.. _about-ref:
|
||||
|
||||
About This Guide
|
||||
----------------
|
||||
|
||||
Purpose
|
||||
~~~~~~~
|
||||
|
||||
The Hitchhiker's Guide to Python exists to provide both novice and expert
|
||||
Python developers a best-practice handbook to the installation, configuration,
|
||||
and usage of Python on a daily basis.
|
||||
|
||||
|
||||
By the Community
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
This guide is architected and maintained by `Kenneth Reitz
|
||||
<https://github.com/kennethreitz>`_ in an open fashion. This is a
|
||||
community-driven effort that serves one purpose: to serve the community.
|
||||
|
||||
For the Community
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
All contributions to the Guide are welcome, from Pythonistas of all levels.
|
||||
If you think there's a gap in what the Guide covers, fork the Guide on
|
||||
GitHub and submit a pull request. Contributions are welcome from everyone,
|
||||
whether they're an old hand or a first-time Pythonista, and the authors to
|
||||
the Guide will gladly help if you have any questions about the
|
||||
appropriateness, completeness, or accuracy of a contribution.
|
||||
|
||||
To get started working on The Hitchhiker's Guide, see
|
||||
the :doc:`/notes/contribute` page.
|
||||
|
||||
|
||||
|
||||
@@ -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>`_
|
||||
@@ -59,13 +59,9 @@ Advanced
|
||||
Pro Python
|
||||
~~~~~~~~~~
|
||||
|
||||
TODO: Write about this book
|
||||
|
||||
`Pro Python <http://propython.com/>`_
|
||||
.. todo:: Write about `Pro Python <http://propython.com/>`_
|
||||
|
||||
Expert Python Programming
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
TODO: Write about this book
|
||||
|
||||
`Expert Python Programming <http://www.packtpub.com/expert-python-programming/book>`_
|
||||
.. todo:: Write about `Expert Python Programming <http://www.packtpub.com/expert-python-programming/book>`_
|
||||
|
||||
+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/>`_
|
||||
|
||||
@@ -1,10 +1,22 @@
|
||||
Contribute
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
Python-guide is under active development, and contributors are welcome.
|
||||
|
||||
If you have a feature request, suggestion, or bug report, please open a new issue on GitHub_. To submit patches, please send a pull request on GitHub_. Make sure you add yourself to AUTHORS_.
|
||||
If you have a feature request, suggestion, or bug report, please open a new
|
||||
issue on GitHub_. To submit patches, please send a pull request on GitHub_.
|
||||
Once your changes get merged back in, you'll automatically be added to the
|
||||
`Contributors List <https://github.com/kennethreitz/python-guide/contributors>`_.
|
||||
|
||||
Style Guide
|
||||
-----------
|
||||
|
||||
For all contributions, please follow the :ref:`guide-style-guide`.
|
||||
|
||||
.. _todo-list-ref:
|
||||
|
||||
Todo List
|
||||
---------
|
||||
|
||||
If you'd like to contribute, there's plenty to do. Here's a short todo_ list.
|
||||
|
||||
@@ -12,6 +24,4 @@ If you'd like to contribute, there's plenty to do. Here's a short todo_ list.
|
||||
|
||||
|
||||
.. _GitHub: http://github.com/kennethreitz/python-guide/
|
||||
.. _AUTHORS: http://github.com/kennethreitz/python-guide/blob/master/AUTHORS
|
||||
.. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
License
|
||||
-------
|
||||
|
||||
TBD.
|
||||
.. todo:: Determine License
|
||||
@@ -0,0 +1,164 @@
|
||||
.. _guide-style-guide:
|
||||
|
||||
=====================
|
||||
The Guide Style Guide
|
||||
=====================
|
||||
|
||||
As with all documentation, having a consistent formating helps make the
|
||||
document more understandable. In order to make The Guide easier to digest,
|
||||
all contributions should fit within the rules of this style guide where
|
||||
approriate.
|
||||
|
||||
The Guide is written as :ref:`restructuredtext-ref`.
|
||||
|
||||
.. note:: Parts of The Guide may not yet match this style guide. Feel free
|
||||
to update those parts to by in sync with The Guide Style Guide
|
||||
|
||||
.. note:: On any page of the rendered HTML you can click "Show Source" to
|
||||
see how authors have styled the page.
|
||||
|
||||
Relevancy
|
||||
---------
|
||||
|
||||
Stride to keep any contributions relevant to the :ref:`purpose of The Guide
|
||||
<about-ref>`.
|
||||
|
||||
* Avoid including too much information on subjects that don't directly
|
||||
relate to Python development.
|
||||
* Prefer to link to other sources if the information is already out there.
|
||||
Be sure to describe what and why you are linking.
|
||||
* `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_
|
||||
references where needed.
|
||||
* If a subject isn't directly relevant to Python, but useful in conjuction
|
||||
with Python (ex: Git, Github, Databases), reference by linking to useful
|
||||
resouces and describe why it's useful to Python.
|
||||
* When in doubt, ask.
|
||||
|
||||
Headings
|
||||
--------
|
||||
|
||||
Use the following styles for headings.
|
||||
|
||||
Chapter title::
|
||||
|
||||
#########
|
||||
Chapter 1
|
||||
#########
|
||||
|
||||
Page title::
|
||||
|
||||
===================
|
||||
Time is an Illusion
|
||||
===================
|
||||
|
||||
Section headings::
|
||||
|
||||
Lunchtime Doubly So
|
||||
-------------------
|
||||
|
||||
Sub section headings::
|
||||
|
||||
Very Deep
|
||||
~~~~~~~~~
|
||||
|
||||
Prose
|
||||
-----
|
||||
|
||||
Wrap text lines at 78 characters. Where necessary, lines may exceed 78
|
||||
characters, especially if wrapping would make the source text more difficult
|
||||
to read.
|
||||
|
||||
|
||||
Code Examples
|
||||
-------------
|
||||
|
||||
Wrap all code examples at 70 characters to avoid horizontal scrollbars.
|
||||
|
||||
Command line examples::
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ run command --help
|
||||
$ ls ..
|
||||
|
||||
Be sure to include the ``$`` prefix before each line.
|
||||
|
||||
Python interpreter examples::
|
||||
|
||||
Label the example::
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> import this
|
||||
|
||||
Python examples::
|
||||
|
||||
Descriptive title::
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def get_answer():
|
||||
return 42
|
||||
|
||||
Externally Linking
|
||||
------------------
|
||||
|
||||
* Prefer labels for well known subjects (ex: proper nouns) when linking::
|
||||
|
||||
Sphinx_ is used to document Python.
|
||||
|
||||
.. _Sphinx: http://sphinx.pocoo.org
|
||||
|
||||
* Prefer to use descriptive labels with inline links instead of leaving bare
|
||||
links::
|
||||
|
||||
Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
|
||||
|
||||
* Avoid using labels such as "click here", "this", etc. preferring
|
||||
decriptive labels (SEO worthy) instead.
|
||||
|
||||
Linking to Sections in The Guide
|
||||
--------------------------------
|
||||
|
||||
To cross-reference other parts of this documentation, use the `:ref:
|
||||
<http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
|
||||
keyword and labels.
|
||||
|
||||
To make reference labels more clear and unique, always add a ``-ref`` suffix::
|
||||
|
||||
.. _some-section-ref:
|
||||
|
||||
Some Section
|
||||
------------
|
||||
|
||||
Notes and Warnings
|
||||
------------------
|
||||
|
||||
Make use of the appropriate `admonitions directives
|
||||
<http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
|
||||
|
||||
Notes::
|
||||
|
||||
.. note::
|
||||
The Hitchhiker’s Guide to the Galaxy has a few things to say
|
||||
on the subject of towels. A towel, it says, is about the most
|
||||
massively useful thing an interstellar hitch hiker can have.
|
||||
|
||||
Warnings::
|
||||
|
||||
.. warning:: DON'T PANIC
|
||||
|
||||
TODOs
|
||||
-----
|
||||
|
||||
Please mark any incomplete areas of The Guide with a `todo directive
|
||||
<http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. To
|
||||
avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
|
||||
documents or large incomplete sections.
|
||||
|
||||
::
|
||||
|
||||
.. todo::
|
||||
Learn the Ultimate Answer to the Ultimate Question
|
||||
of Life, The Universe, and Everything
|
||||
|
||||
@@ -4,14 +4,84 @@ Systems Administration
|
||||
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 as deployment.
|
||||
|
||||
Install Fabric:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ pip install fabric
|
||||
|
||||
The following code will create two tasks that we can use: ``memory_usage`` and
|
||||
``deploy``. The former will output the memory usage on each machine. The
|
||||
latter will ssh into each server, cd to our project directory, activate the
|
||||
virtual environment, pull the newest codebase, and restart the application
|
||||
server.
|
||||
|
||||
::
|
||||
|
||||
from fabric.api import cd, env, prefix, run, task
|
||||
|
||||
env.hosts = ['my_server1', 'my_server2']
|
||||
|
||||
@task
|
||||
def memory_usage():
|
||||
run('free -m')
|
||||
|
||||
@task
|
||||
def deploy():
|
||||
with cd('/var/www/project-env/project'):
|
||||
with prefix('. ../bin/activate'):
|
||||
run('git pull')
|
||||
run('touch app.wsgi')
|
||||
|
||||
With the previous code saved in a file named fabfile.py, we can check memory
|
||||
usage with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ fab memory_usage
|
||||
[my_server1] Executing task 'memory'
|
||||
[my_server1] run: free -m
|
||||
[my_server1] out: total used free shared buffers cached
|
||||
[my_server1] out: Mem: 6964 1897 5067 0 166 222
|
||||
[my_server1] out: -/+ buffers/cache: 1509 5455
|
||||
[my_server1] out: Swap: 0 0 0
|
||||
|
||||
[my_server2] Executing task 'memory'
|
||||
[my_server2] run: free -m
|
||||
[my_server2] out: total used free shared buffers cached
|
||||
[my_server2] out: Mem: 1666 902 764 0 180 572
|
||||
[my_server2] out: -/+ buffers/cache: 148 1517
|
||||
[my_server2] out: Swap: 895 1 894
|
||||
|
||||
and we can deploy with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ fab deploy
|
||||
|
||||
Additional features include parallel execution, interaction with remote
|
||||
programs, and host grouping.
|
||||
|
||||
Chef
|
||||
----
|
||||
|
||||
.. todo:: Write about Chef
|
||||
|
||||
Puppet
|
||||
------
|
||||
|
||||
.. todo:: Write about Puppet
|
||||
|
||||
Blueprint
|
||||
---------
|
||||
---------
|
||||
|
||||
.. todo:: Write about Blueprint
|
||||
|
||||
Buildout
|
||||
--------
|
||||
|
||||
.. todo:: Write about Buildout
|
||||
+11
-6
@@ -5,23 +5,28 @@ Continuous Integration
|
||||
Why?
|
||||
----
|
||||
|
||||
Martin Fowler, who first wrote about Continuous Integration (short: CI) together with Kent Beck, describes the CI as follows:
|
||||
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.
|
||||
|
||||
Source: http://martinfowler.com/articles/continuousIntegration.html
|
||||
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
|
||||
-------
|
||||
|
||||
Jenkins CI (http://jenkins-ci.org) is an extensible continuous integration engine. Use it.
|
||||
`Jenkins CI <http://jenkins-ci.org>`_ is an extensible continuous integration engine. Use it.
|
||||
|
||||
|
||||
|
||||
Buildbot
|
||||
--------
|
||||
Buildbot (http://buildbot.net/buildbot/docs/current) is a Python system to automate the compile/test cycle to validate code changes.
|
||||
`Buildbot <http://buildbot.net/buildbot/docs/current>`_ is a Python system to automate the compile/test cycle to validate code changes.
|
||||
|
||||
|
||||
Mule?
|
||||
-----
|
||||
|
||||
.. todo:: Write about Mule
|
||||
|
||||
Tox
|
||||
---
|
||||
|
||||
.. todo:: Write about `Tox <http://codespeak.net/~hpk/tox/>`_
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
Command Line Applications
|
||||
=========================
|
||||
|
||||
|
||||
.. todo:: Explain "Command Line Applications"
|
||||
|
||||
Clint
|
||||
-----
|
||||
|
||||
.. todo:: Write about Clint
|
||||
@@ -22,3 +22,7 @@ database-agnostic code without SQL.
|
||||
|
||||
pip install sqlalchemy
|
||||
|
||||
Django ORM
|
||||
----------
|
||||
|
||||
.. todo:: Explain Django ORM
|
||||
@@ -12,25 +12,28 @@ http://developer.qt.nokia.com/wiki/PySideDownloads/
|
||||
|
||||
PyQt
|
||||
----
|
||||
*Note: If your software does not fully comply with the GPL you will need a commercial license!*
|
||||
.. note:: If your software does not fully comply with the GPL you will need a commercial license!
|
||||
|
||||
http://www.riverbankcomputing.co.uk/software/pyqt/download
|
||||
|
||||
Cocoa
|
||||
:::::
|
||||
*Note: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!*
|
||||
.. note:: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!
|
||||
|
||||
PyObjC
|
||||
------
|
||||
*Note: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application.*
|
||||
.. note:: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application.
|
||||
|
||||
WXPython
|
||||
::::::::
|
||||
|
||||
|
||||
Install (Stable)
|
||||
----
|
||||
----------------
|
||||
*Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.*
|
||||
|
||||
Gtk
|
||||
:::
|
||||
|
||||
tk
|
||||
::
|
||||
::
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
=======================
|
||||
Scientific Applications
|
||||
=======================
|
||||
|
||||
Context
|
||||
:::::::
|
||||
|
||||
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 to external libraries, typically
|
||||
written in faster languages (like C, or FORTRAN for matrix operations). The main libraries used are NumPy and SciPy
|
||||
|
||||
Libraries
|
||||
:::::::::
|
||||
|
||||
Numpy
|
||||
-----
|
||||
`NumPy <http://numpy.scipy.org/>`_ is a low level library written in C (and FORTRAN) for high level mathematical functions.
|
||||
NumPy cleverly overcomes the problem of running slower algorithms on Python by using multidimensional arrays and functions that operate on arrays.
|
||||
Any algorithm can then be expressed as a function on arrays, allowing the algorithms to be run quickly.
|
||||
|
||||
|
||||
NumPy is part of the SciPy project, and is released as a separate library so people who only need the basic requirements can just use NumPy.
|
||||
|
||||
NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+.
|
||||
|
||||
SciPy
|
||||
-----
|
||||
`SciPy <http://scipy.org/>`_ is a library that uses Numpy for more mathematical function. SciPy uses NumPy arrays as its basic data structure.
|
||||
SciPy comes with modules for various commonly used tasks in scientific programing like linear algebra, integration (calculus),
|
||||
ordinary differential equation solvers and signal processing.
|
||||
|
||||
Enthought
|
||||
---------
|
||||
|
||||
Installing NumPy and SciPy can be a daunting task. Which is why the `Enthought Python distribution <http://enthought.com/>`_ was created. With Enthought,
|
||||
scientific python has never been easier (one click to install about 100 scientific python packages). User beware: Enthought is not free.
|
||||
|
||||
Matplotlib
|
||||
----------
|
||||
|
||||
.. todo:: write about matplotlib.
|
||||
|
||||
Resources
|
||||
:::::::::
|
||||
|
||||
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 <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_ 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 general list. It might be a good idea to check it out if you're on Windows.
|
||||
@@ -3,6 +3,7 @@ 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
|
||||
|
||||
Context
|
||||
:::::::
|
||||
|
||||
+121
-24
@@ -1,3 +1,4 @@
|
||||
================
|
||||
Web Applications
|
||||
================
|
||||
|
||||
@@ -13,7 +14,7 @@ The Web Server Gateway Interface (or "WSGI" for short) is a standard
|
||||
interface between web servers and Python web application frameworks. By
|
||||
standardizing behavior and communication between web servers and Python web
|
||||
frameworks, WSGI makes it possible to write portable Python web code that
|
||||
can be deployed in any `WSGI-compliant web server <#servers>`_. WSGI is
|
||||
can be deployed in any :ref:`WSGI-compliant web server <wsgi-servers-ref>`. WSGI is
|
||||
documented in `PEP-3333 <http://www.python.org/dev/peps/pep-3333/>`_.
|
||||
|
||||
|
||||
@@ -70,23 +71,52 @@ you may need, such as database access or form generation and validation. For
|
||||
many popular modules, `Extensions <http://flask.pocoo.org/extensions/>`_ may
|
||||
already exist to suit your needs.
|
||||
|
||||
**Support** for flask can best be found in its mailing list. Just shoot an email to
|
||||
flask@librelist.com and reply to the confirmation email.
|
||||
|
||||
|
||||
Pyramid
|
||||
-------
|
||||
|
||||
.. todo:: Explian Pyramid
|
||||
|
||||
Servers
|
||||
:::::::
|
||||
Web.py
|
||||
------
|
||||
|
||||
Apache + mod_wsgi
|
||||
-----------------
|
||||
`web.py <http://webpy.org>`_ is a minimalist web framework that is somewhere between Django and Flask.
|
||||
The premise of web.py is that it is flexible - code your webapp any way you want it, in just python and python alone.
|
||||
web.py comes with some nifty tools built in, like database connection tools and a mini http server.
|
||||
|
||||
Apache + mod_python
|
||||
-------------------
|
||||
**Support** for web.py is quite sparse, but you can look for support in the `mailing list <http://groups.google.com/group/webpy>`_ .
|
||||
|
||||
|
||||
Nginx + gunicorn
|
||||
----------------
|
||||
Web Servers
|
||||
:::::::::::
|
||||
|
||||
Apache
|
||||
------
|
||||
|
||||
mod_python
|
||||
~~~~~~~~~~
|
||||
|
||||
For a long period Apache with mod_python was one of the most reccomended
|
||||
ways to deploy Python applications and thus you may see many tutorials
|
||||
about it on the web or in books, however Apache no longer supports
|
||||
mod_python [1]_ and thus this deployment mechanism is strongly discouraged in
|
||||
favor of WSGI based ones.
|
||||
|
||||
mod_wsgi
|
||||
~~~~~~~~
|
||||
|
||||
Many improvements have been made with mod_wsgi over mod_python for serving
|
||||
Python with Apache [2]_. If you must run the Apache web server, mod_wsgi is
|
||||
your best option for running Python, other than proxying to a dedicated WSGI
|
||||
server.
|
||||
|
||||
.. _nginx-ref:
|
||||
|
||||
Nginx
|
||||
-----
|
||||
|
||||
`Nginx <http://nginx.org/>`_ (pronounced "engine-x") is a web server and
|
||||
reverse-proxy for HTTP, SMTP and other protocols. It is known for its
|
||||
@@ -95,33 +125,83 @@ application servers (like WSGI servers). It also includes handy features
|
||||
like load-balancing, basic authentication, streaming, and others. Designed
|
||||
to serve high-load websites, Nginx is gradually becoming quite popular.
|
||||
|
||||
Mongrel2
|
||||
--------
|
||||
|
||||
`Mongrel2 <http://mongrel2.org>`_ is an application, language, and network
|
||||
architecture agnostic web server. It uses a high performance queue (zeromq) to
|
||||
communicate with your applications, all asynchronously. There is a well defined
|
||||
protocol to be used between mongrel2 and a backend handler (your app).
|
||||
|
||||
Brubeck
|
||||
~~~~~~~
|
||||
|
||||
.. todo:: Explain Mongrel2 + Brubeck
|
||||
|
||||
wsgid
|
||||
~~~~~
|
||||
|
||||
`Wsgid <http://wsgid.com>`_ is a generic mongrel2 handler that speaks both
|
||||
mongrel2 protocol and WSGI. This makes it possible to run your python webapp
|
||||
written with any WSGI compliant framework. Wsgid has built-in Django support but
|
||||
has also a generic way to load your WSGI application object directly. It's
|
||||
possible to add support for other frameworks through wsgid's pluggable
|
||||
Apploading interface.
|
||||
|
||||
.. rubric:: Resources
|
||||
|
||||
* `Deploying your django application with mongrel2 and wsgid <http://daltonmatos.wordpress.com/2011/11/06/deploying-your-django-application-with-mongrel2-and-wsgid/>`_
|
||||
|
||||
.. _wsgi-servers-ref:
|
||||
|
||||
WSGI Servers
|
||||
::::::::::::
|
||||
|
||||
Stand-alone WSGI servers typically use less resources than traditional web
|
||||
servers and provide top performance [3]_.
|
||||
|
||||
.. _gunicorn-ref:
|
||||
|
||||
gUnicorn
|
||||
--------
|
||||
|
||||
`gUnicorn <http://gunicorn.org/>`_ (Green Unicorn) is a WSGI server used
|
||||
to serve Python applications. It is a Python fork of the Ruby
|
||||
`Unicorn <http://unicorn.bogomips.org/>`_ server. gUnicorn is designed to be
|
||||
lightweight, easy to use, and uses many UNIX idioms. gUnicorn is not designed
|
||||
to face the internet, in fact it was designed to run behind Nginx which buffers
|
||||
slow requests, and takes care of other important considerations. A sample
|
||||
setup for Nginx + gUnicorn can be found in the gUnicorn
|
||||
`help <http://gunicorn.org/deploy.html>`_.
|
||||
setup for Nginx + gUnicorn can be found in the
|
||||
`gUnicorn help <http://gunicorn.org/deploy.html>`_.
|
||||
|
||||
Mongrel2 + Brubeck
|
||||
------------------
|
||||
.. _uwsgi-ref:
|
||||
|
||||
uwsgi
|
||||
-----
|
||||
|
||||
Mongrel2 + wsgid
|
||||
----------------
|
||||
`uWSGI <http://projects.unbit.it/uwsgi/>`_ is a fast, self-healing and
|
||||
developer/sysadmin-friendly application container server coded in pure C.
|
||||
|
||||
Mongrel2 is an application, language, and network architecture agnostic web server. It uses a high performance queue (zeromq) to communicate
|
||||
with your applications, all asynchronously. There is a well defined protocol to be used between mongrel2 and a backend handler (your app).
|
||||
Born as a WSGI-only server, over time it has evolved in a complete stack for
|
||||
networked/clustered web applications, implementing message/object passing,
|
||||
caching, RPC and process management.
|
||||
|
||||
Wsgid is a generic mongrel2 handler that speaks both mongrel2 protocol and WSGI. This makes it possible to run your python webapp written with any
|
||||
WSGI compliant framework. Wsgid has built-in Django support but has also a generic way to load your WSGI application object directly. It's possible
|
||||
to add support for other frameworks through wsgid's pluggable Apploading interface.
|
||||
Server Best Practices
|
||||
:::::::::::::::::::::
|
||||
|
||||
To know more about mongrel2 and wsgid go to: http://mongrel2.org and http://wsgid.com
|
||||
While Apache will serve your Python application, and many references suggest it,
|
||||
modern best practices suggest against it. With the improvements in mod_wsgi over
|
||||
mod_python, Apache can handle many more requests than before. However, mod_wsgi
|
||||
tends to use more memory than other WSGI solutions [3]_.
|
||||
|
||||
There is also a tutorial about deploying Django using this stack: http://daltonmatos.wordpress.com/2011/11/06/deploying-your-django-application-with-mongrel2-and-wsgid/
|
||||
The majority of self hosted Python applications today are hosted with a WSGI
|
||||
server such as :ref:`uWSGI <uwsgi-ref>` or :ref:`gUnicorn <gunicorn-ref>` behind a
|
||||
lightweight web server such as :ref:`nginx <nginx-ref>` or
|
||||
`lighttpd <http://www.lighttpd.net/>`_.
|
||||
|
||||
The WSGI servers serve the Python applications while the web server handles tasks
|
||||
better suited for it such as static file serving, request routing, DDoS
|
||||
protection, and basic authentication.
|
||||
|
||||
Hosting
|
||||
:::::::
|
||||
@@ -167,8 +247,8 @@ DotCloud
|
||||
|
||||
`DotCloud <http://www.dotcloud.com/>`_ supports WSGI applications and
|
||||
background/worker tasks natively on their platform. Web applications running
|
||||
Python version 2.6, and uses `nginx <http://nginx.org/>`_ and `uWSGI
|
||||
<http://projects.unbit.it/uwsgi/>`_, and allows custom configuration of both
|
||||
Python version 2.6, and uses :ref:`nginx <nginx-ref>` and :ref:`uWSGI
|
||||
<uwsgi-ref>`, and allows custom configuration of both
|
||||
for advanced users.
|
||||
|
||||
DotCloud uses a custom command-line API client which can work with
|
||||
@@ -209,12 +289,29 @@ Gondor publishes guides to deploying `Django projects
|
||||
Shared Web Hosting
|
||||
------------------
|
||||
|
||||
.. todo:: Fill in "Shared Web Hosting" stub
|
||||
|
||||
WebFaction
|
||||
~~~~~~~~~~~
|
||||
|
||||
`Webfaction <http://www.webfaction.com/>`_ started off as a dedicated python hosting company.
|
||||
In fact it used to be called python-hosting.com. Webfaction supports Python versions 2.4 through to 2.7.2
|
||||
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>`_,
|
||||
`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.
|
||||
|
||||
Twisted
|
||||
:::::::
|
||||
|
||||
|
||||
Node.js.
|
||||
|
||||
.. rubric:: References
|
||||
|
||||
.. [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>`_
|
||||
|
||||
@@ -10,6 +10,9 @@ Many applications you use every day do this:
|
||||
- BitTorrent
|
||||
-
|
||||
|
||||
|
||||
.. todo:: Fill in "Freezing Your Code" stub
|
||||
|
||||
Windows
|
||||
:::::::
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@ Packaging Your Code
|
||||
|
||||
Packaging your code is important.
|
||||
|
||||
.. todo:: Write introduction for "Packaging Your Code"
|
||||
|
||||
For Python Developers
|
||||
:::::::::::::::::::::
|
||||
@@ -14,7 +15,7 @@ If you're writing an open source Python module, `PyPI <http://pypi.python.org>`_
|
||||
Pip vs. easy_install
|
||||
--------------------
|
||||
|
||||
Use pip. More details `here <http://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install>`_
|
||||
Use `pip <http://pypi.python.org/pypi/pip>`_. More details `here <http://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install>`_
|
||||
|
||||
|
||||
Personal PyPI
|
||||
@@ -54,10 +55,13 @@ $ pip install http://127.0.0.1:9000/MyPackage.tar.gz
|
||||
Chishop
|
||||
+++++++
|
||||
|
||||
`Chishop <https://github.com/benliles/djangopypi>`_ is a simple PyPI server written in django which allows you to register/upload with distutils and install with easy_install/pip.
|
||||
|
||||
For Linux Distributions
|
||||
::::::::::::::::::::::::
|
||||
|
||||
.. todo:: Fill in "For Linux Distributions" packaging stub
|
||||
|
||||
Useful Tools
|
||||
------------
|
||||
|
||||
|
||||
@@ -1,137 +0,0 @@
|
||||
Your Development Environment
|
||||
============================
|
||||
|
||||
|
||||
Text Editors
|
||||
::::::::::::
|
||||
|
||||
|
||||
VIM
|
||||
---
|
||||
|
||||
|
||||
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 linewrapping to values compliant with PEP8::
|
||||
|
||||
set textwidth=79
|
||||
set shiftwidth=4
|
||||
set tabstop=4
|
||||
set expandtab
|
||||
set softtabstop=4
|
||||
set shiftround
|
||||
|
||||
With these settings newlines are inserted after 79 characters and indentation
|
||||
is set to 4 spaces per tab. If you also use VIM for other languages, there is a
|
||||
handy plugin at indent_, which handles indentation settings for python source
|
||||
files.
|
||||
Additionally there is also a handy syntax plugin at syntax_ featuring some
|
||||
improvements over the syntax file included in VIM 6.1.
|
||||
|
||||
These plugins supply you with a basic environment for developing in Python.
|
||||
However in order to improve the programming flow we also want to continually
|
||||
check for PEP8 compliance and check syntax. Luckily there exist PEP8_ and
|
||||
Pyflakes_ to do this for you. If your VIM is compiled with `+python` you can
|
||||
also utilize some very handy plugins to do these checks from within the editor.
|
||||
For PEP8 checking install vim-pep8_. Now you can map the vim function
|
||||
`Pep8()` to any hotkey or action you want. Similarly for pyflakes you can
|
||||
install vim-pyflakes_. Now you can map `Pyflakes()` like the PEP8 function and
|
||||
have it called quickly. Both plugins will display errors in a quickfix list and
|
||||
provide an easy way to jump to the corresponding line. A very handy setting is
|
||||
calling these functions whenever a buffer is saved. In order to do this, enter
|
||||
the following lines into your vimrc::
|
||||
|
||||
autocmd BufWritePost *.py call Pyflakes()
|
||||
autocmd BufWritePost *.py call Pep8()
|
||||
|
||||
|
||||
.. _indent: http://www.vim.org/scripts/script.php?script_id=974
|
||||
.. _syntax: http://www.vim.org/scripts/script.php?script_id=790
|
||||
.. _Pyflakes: http://pypi.python.org/pypi/pyflakes/
|
||||
.. _vim-pyflakes: https://github.com/nvie/vim-pyflakes
|
||||
.. _PEP8: http://pypi.python.org/pypi/pep8/
|
||||
.. _vim-pep8: https://github.com/nvie/vim-pep8
|
||||
|
||||
.. todo:: add supertab notes
|
||||
|
||||
|
||||
IDEs
|
||||
::::
|
||||
|
||||
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 <http://plugins.intellij.net/plugin/?id=631/>`_..
|
||||
|
||||
Eclipse
|
||||
-------
|
||||
|
||||
The most popular Eclipse plugin for Python development is Aptana's
|
||||
`PyDev <http://pydev.org>`_.
|
||||
|
||||
|
||||
Komodo IDE
|
||||
-----------
|
||||
`Komodo IDE <http://www.activestate.com/komodo-ide>`_ is developed by ActiveState and is a commerical IDE for Windows, Mac
|
||||
and Linux.
|
||||
|
||||
Spyder
|
||||
------
|
||||
|
||||
`Spyder <http://code.google.com/p/spyderlib/>`_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy <http://www.scipy.org/>`_).
|
||||
Includes integration with `pyflakes <http://pypi.python.org/pypi/pyflakes>`_, `pylint <http://www.logilab.org/857>`_,
|
||||
and `rope <http://rope.sourceforge.net/>`_.
|
||||
|
||||
Spyder is open-source (free), offers code completion, syntax highlighting, class and function browser, and object
|
||||
inspection
|
||||
|
||||
|
||||
|
||||
Interpreter Tools
|
||||
:::::::::::::::::
|
||||
|
||||
|
||||
virtualenv
|
||||
----------
|
||||
|
||||
Virtualenv is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them.
|
||||
It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma and keeps your global site-packages directory clean and manageable.
|
||||
|
||||
virtualenvwrapper
|
||||
-----------------
|
||||
|
||||
Virtualenvwrapper makes virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
|
||||
|
||||
::
|
||||
|
||||
pip install virtualenvwrapper
|
||||
|
||||
|
||||
Put this into your `~/.bash_profile` (Linux/Mac) file:
|
||||
|
||||
::
|
||||
|
||||
export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
|
||||
|
||||
This will prevent your virtualenvs from relying on your (global) site packages directory, so that they are completely separate..
|
||||
|
||||
Other Tools
|
||||
:::::::::::
|
||||
|
||||
IPython
|
||||
-------
|
||||
|
||||
::
|
||||
|
||||
$ pip install ipython
|
||||
|
||||
|
||||
|
||||
BPython
|
||||
-------
|
||||
|
||||
::
|
||||
|
||||
$ pip install bpython
|
||||
|
||||
|
||||
@@ -6,23 +6,16 @@ Mac OS X
|
||||
|
||||
*Or, "Installing Python 2.7 via Homebrew".*
|
||||
|
||||
One of the reasons everybody loves Python is the interactive shell. It
|
||||
basically allows you to execute Python commands in real time and
|
||||
immediately get results back. Flask itself does not come with an
|
||||
interactive shell, because it does not require any specific setup upfront,
|
||||
just import your application and start playing around.
|
||||
|
||||
|
||||
Package Manager
|
||||
---------------
|
||||
|
||||
While Snow Leopard comes with a large number of UNIX utilities, those
|
||||
familiar with Linux systems will notice one key component missing: a
|
||||
package manager. Mxcl's *Homebrew* is the answer.
|
||||
package manager. Mxcl's `Homebrew <http://mxcl.github.com/homebrew/>`_ is the answer.
|
||||
|
||||
To install Homebrew, simply run: ::
|
||||
To `install Homebrew <https://github.com/mxcl/homebrew/wiki/installation>`_, simply run: ::
|
||||
|
||||
$ ruby -e "$(curl -fsS http://gist.github.com/raw/323731/install_homebrew.rb)"
|
||||
$ ruby -e "$(curl -fsS https://raw.github.com/gist/323731)"
|
||||
|
||||
|
||||
It's basic commands are **update**, **install**, and **remove**.
|
||||
@@ -41,11 +34,10 @@ bugs.
|
||||
|
||||
*Don't forget to update your environment PATH.*
|
||||
|
||||
|
||||
Building From Source
|
||||
--------------------
|
||||
|
||||
|
||||
.. todo:: Write "Building From Source"
|
||||
|
||||
|
||||
Distribute & Pip
|
||||
@@ -73,10 +65,6 @@ If you have homebrew: ::
|
||||
|
||||
$ easy_install pip
|
||||
|
||||
|
||||
|
||||
To install ``pip``: ::
|
||||
|
||||
Hopefully you'll never have to use **easy_install** again.
|
||||
|
||||
|
||||
@@ -136,15 +124,11 @@ Older versions of Python aren't available from the official repository. However,
|
||||
Installing setuptools and pip
|
||||
-----------------------------
|
||||
|
||||
While Python has an extensive standard library, the set of packages available from the Internet is even more extensive. In order to install them easily, we'll install the ``setuptools`` package and ``pip`` installer::
|
||||
|
||||
.. XXX: sudo?
|
||||
While Python has an extensive standard library, the set of packages available from the Internet is even more extensive. In order to install them easily, we'll install the ``distribute`` package and then ``pip``::
|
||||
|
||||
$ wget http://python-distribute.org/distribute_setup.py
|
||||
$ python distribute_setup.py
|
||||
$ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
|
||||
$ python get-pip.py
|
||||
$ rm get-pip.py distribute_setup.py
|
||||
$ sudo python distribute_setup.py
|
||||
$ sudo easy_install pip
|
||||
|
||||
Now, most Python packages can be installed using the ``pip`` command. For example, if we wanted to install Django::
|
||||
|
||||
|
||||
@@ -66,7 +66,8 @@ PyPy aims for maximum compatibility with the reference CPython implementation
|
||||
while improving performance.
|
||||
|
||||
If you are looking to squeeze more performance out of your Python code, it's
|
||||
worth giving PyPy a try.
|
||||
worth giving PyPy a try. On a suite of benchmarks, it's current `over 5 times
|
||||
faster than CPython <http://speed.pypy.org/>`_.
|
||||
|
||||
Currently PyPy supports Python 2.7.
|
||||
|
||||
|
||||
@@ -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,34 +35,49 @@ 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."""
|
||||
global _kos_root
|
||||
if _kos_root: return _kos_root
|
||||
...
|
||||
"""Return the pathname of the KOS root directory."""
|
||||
global _kos_root
|
||||
if _kos_root: return _kos_root
|
||||
...
|
||||
|
||||
Multi-line docstrings: ::
|
||||
|
||||
def complex(real=0.0, imag=0.0):
|
||||
"""Form a complex number.
|
||||
"""Form a complex number.
|
||||
|
||||
Keyword arguments:
|
||||
real -- the real part (default 0.0)
|
||||
imag -- the imaginary part (default 0.0)
|
||||
Keyword arguments:
|
||||
real -- the real part (default 0.0)
|
||||
imag -- the imaginary part (default 0.0)
|
||||
|
||||
"""
|
||||
if imag == 0.0 and real == 0.0: return complex_zero
|
||||
...
|
||||
"""
|
||||
if imag == 0.0 and real == 0.0: return complex_zero
|
||||
...
|
||||
|
||||
Sphinx
|
||||
------
|
||||
Sphinx (http://sphinx.pocoo.org) is a tool which converts documentation in the reStructured text markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text.
|
||||
|
||||
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_
|
||||
|
||||
.. _Sphinx: http://sphinx.pocoo.org
|
||||
|
||||
.. _restructuredtext-ref:
|
||||
|
||||
|
||||
reStructuredText
|
||||
----------------
|
||||
|
||||
Most Python documentation is written with reStructuredText_. The `reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_ and the `reStructuredText Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ should help you familiarize yourself with its syntax.
|
||||
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
|
||||
Other Tools
|
||||
:::::::::::
|
||||
@@ -73,4 +89,4 @@ pocco / docco / shocco
|
||||
----------------------
|
||||
|
||||
Ronn
|
||||
----
|
||||
----
|
||||
|
||||
@@ -4,7 +4,7 @@ Choosing a License
|
||||
Open source.
|
||||
|
||||
|
||||
|
||||
.. todo:: Fill in License stub
|
||||
|
||||
|
||||
Non-Restrictive
|
||||
|
||||
@@ -3,6 +3,7 @@ Structuring Your Project
|
||||
|
||||
Structuring your project properly is extremely important.
|
||||
|
||||
.. todo:: Fill in "Structuring Your Project" stub
|
||||
|
||||
Structure is Key
|
||||
----------------
|
||||
|
||||
@@ -16,6 +16,27 @@ Also known as PEP 20, the guiding principles for Python's design.
|
||||
::
|
||||
|
||||
>>> import this
|
||||
The Zen of Python, by Tim Peters
|
||||
|
||||
Beautiful is better than ugly.
|
||||
Explicit is better than implicit.
|
||||
Simple is better than complex.
|
||||
Complex is better than complicated.
|
||||
Flat is better than nested.
|
||||
Sparse is better than dense.
|
||||
Readability counts.
|
||||
Special cases aren't special enough to break the rules.
|
||||
Although practicality beats purity.
|
||||
Errors should never pass silently.
|
||||
Unless explicitly silenced.
|
||||
In the face of ambiguity, refuse the temptation to guess.
|
||||
There should be one-- and preferably only one --obvious way to do it.
|
||||
Although that way may not be obvious at first unless you're Dutch.
|
||||
Now is better than never.
|
||||
Although never is often better than *right* now.
|
||||
If the implementation is hard to explain, it's a bad idea.
|
||||
If the implementation is easy to explain, it may be a good idea.
|
||||
Namespaces are one honking great idea -- let's do more of those!
|
||||
|
||||
See `<http://stackoverflow.com/questions/228181/the-zen-of-python>`_ for some
|
||||
examples.
|
||||
|
||||
Reference in New Issue
Block a user