diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d8dd1f4 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/osxpython.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/osxpython.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/osxpython" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/osxpython" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/_build/doctrees/_themes/README.doctree b/docs/_build/doctrees/_themes/README.doctree new file mode 100644 index 0000000..f06766e Binary files /dev/null and b/docs/_build/doctrees/_themes/README.doctree differ diff --git a/docs/_build/doctrees/dev/env.doctree b/docs/_build/doctrees/dev/env.doctree new file mode 100644 index 0000000..c94beaf Binary files /dev/null and b/docs/_build/doctrees/dev/env.doctree differ diff --git a/docs/_build/doctrees/dev/virtualenvs.doctree b/docs/_build/doctrees/dev/virtualenvs.doctree new file mode 100644 index 0000000..6940a64 Binary files /dev/null and b/docs/_build/doctrees/dev/virtualenvs.doctree differ diff --git a/docs/_build/doctrees/environment.pickle b/docs/_build/doctrees/environment.pickle new file mode 100644 index 0000000..3eba1f2 Binary files /dev/null and b/docs/_build/doctrees/environment.pickle differ diff --git a/docs/_build/doctrees/index.doctree b/docs/_build/doctrees/index.doctree new file mode 100644 index 0000000..dfca411 Binary files /dev/null and b/docs/_build/doctrees/index.doctree differ diff --git a/docs/_build/doctrees/intro/community.doctree b/docs/_build/doctrees/intro/community.doctree new file mode 100644 index 0000000..e1c8ca9 Binary files /dev/null and b/docs/_build/doctrees/intro/community.doctree differ diff --git a/docs/_build/doctrees/intro/documentation.doctree b/docs/_build/doctrees/intro/documentation.doctree new file mode 100644 index 0000000..f01fa0d Binary files /dev/null and b/docs/_build/doctrees/intro/documentation.doctree differ diff --git a/docs/_build/doctrees/intro/duction.doctree b/docs/_build/doctrees/intro/duction.doctree new file mode 100644 index 0000000..bdfbaa3 Binary files /dev/null and b/docs/_build/doctrees/intro/duction.doctree differ diff --git a/docs/_build/doctrees/intro/learning.doctree b/docs/_build/doctrees/intro/learning.doctree new file mode 100644 index 0000000..37c8002 Binary files /dev/null and b/docs/_build/doctrees/intro/learning.doctree differ diff --git a/docs/_build/doctrees/intro/news.doctree b/docs/_build/doctrees/intro/news.doctree new file mode 100644 index 0000000..360fdd9 Binary files /dev/null and b/docs/_build/doctrees/intro/news.doctree differ diff --git a/docs/_build/doctrees/notes/contribute.doctree b/docs/_build/doctrees/notes/contribute.doctree new file mode 100644 index 0000000..7b8e93f Binary files /dev/null and b/docs/_build/doctrees/notes/contribute.doctree differ diff --git a/docs/_build/doctrees/notes/license.doctree b/docs/_build/doctrees/notes/license.doctree new file mode 100644 index 0000000..b31acbe Binary files /dev/null and b/docs/_build/doctrees/notes/license.doctree differ diff --git a/docs/_build/doctrees/notes/styleguide.doctree b/docs/_build/doctrees/notes/styleguide.doctree new file mode 100644 index 0000000..19432a0 Binary files /dev/null and b/docs/_build/doctrees/notes/styleguide.doctree differ diff --git a/docs/_build/doctrees/scenarios/admin.doctree b/docs/_build/doctrees/scenarios/admin.doctree new file mode 100644 index 0000000..bd734c1 Binary files /dev/null and b/docs/_build/doctrees/scenarios/admin.doctree differ diff --git a/docs/_build/doctrees/scenarios/ci.doctree b/docs/_build/doctrees/scenarios/ci.doctree new file mode 100644 index 0000000..38696a8 Binary files /dev/null and b/docs/_build/doctrees/scenarios/ci.doctree differ diff --git a/docs/_build/doctrees/scenarios/cli.doctree b/docs/_build/doctrees/scenarios/cli.doctree new file mode 100644 index 0000000..b23557a Binary files /dev/null and b/docs/_build/doctrees/scenarios/cli.doctree differ diff --git a/docs/_build/doctrees/scenarios/db.doctree b/docs/_build/doctrees/scenarios/db.doctree new file mode 100644 index 0000000..dbe0a30 Binary files /dev/null and b/docs/_build/doctrees/scenarios/db.doctree differ diff --git a/docs/_build/doctrees/scenarios/gui.doctree b/docs/_build/doctrees/scenarios/gui.doctree new file mode 100644 index 0000000..047e3d8 Binary files /dev/null and b/docs/_build/doctrees/scenarios/gui.doctree differ diff --git a/docs/_build/doctrees/scenarios/scientific.doctree b/docs/_build/doctrees/scenarios/scientific.doctree new file mode 100644 index 0000000..518a0a8 Binary files /dev/null and b/docs/_build/doctrees/scenarios/scientific.doctree differ diff --git a/docs/_build/doctrees/scenarios/speed.doctree b/docs/_build/doctrees/scenarios/speed.doctree new file mode 100644 index 0000000..f8f0121 Binary files /dev/null and b/docs/_build/doctrees/scenarios/speed.doctree differ diff --git a/docs/_build/doctrees/scenarios/web.doctree b/docs/_build/doctrees/scenarios/web.doctree new file mode 100644 index 0000000..fbf095e Binary files /dev/null and b/docs/_build/doctrees/scenarios/web.doctree differ diff --git a/docs/_build/doctrees/shipping/freezing.doctree b/docs/_build/doctrees/shipping/freezing.doctree new file mode 100644 index 0000000..09371d5 Binary files /dev/null and b/docs/_build/doctrees/shipping/freezing.doctree differ diff --git a/docs/_build/doctrees/shipping/packaging.doctree b/docs/_build/doctrees/shipping/packaging.doctree new file mode 100644 index 0000000..dfa8106 Binary files /dev/null and b/docs/_build/doctrees/shipping/packaging.doctree differ diff --git a/docs/_build/doctrees/starting/dev-env.doctree b/docs/_build/doctrees/starting/dev-env.doctree new file mode 100644 index 0000000..a8166b7 Binary files /dev/null and b/docs/_build/doctrees/starting/dev-env.doctree differ diff --git a/docs/_build/doctrees/starting/install/linux.doctree b/docs/_build/doctrees/starting/install/linux.doctree new file mode 100644 index 0000000..2b9c476 Binary files /dev/null and b/docs/_build/doctrees/starting/install/linux.doctree differ diff --git a/docs/_build/doctrees/starting/install/osx.doctree b/docs/_build/doctrees/starting/install/osx.doctree new file mode 100644 index 0000000..b56e53c Binary files /dev/null and b/docs/_build/doctrees/starting/install/osx.doctree differ diff --git a/docs/_build/doctrees/starting/install/win.doctree b/docs/_build/doctrees/starting/install/win.doctree new file mode 100644 index 0000000..14b0e0a Binary files /dev/null and b/docs/_build/doctrees/starting/install/win.doctree differ diff --git a/docs/_build/doctrees/starting/installation.doctree b/docs/_build/doctrees/starting/installation.doctree new file mode 100644 index 0000000..447ec90 Binary files /dev/null and b/docs/_build/doctrees/starting/installation.doctree differ diff --git a/docs/_build/doctrees/starting/next.doctree b/docs/_build/doctrees/starting/next.doctree new file mode 100644 index 0000000..f960243 Binary files /dev/null and b/docs/_build/doctrees/starting/next.doctree differ diff --git a/docs/_build/doctrees/starting/which-python.doctree b/docs/_build/doctrees/starting/which-python.doctree new file mode 100644 index 0000000..a745ba9 Binary files /dev/null and b/docs/_build/doctrees/starting/which-python.doctree differ diff --git a/docs/_build/doctrees/writing/documentation.doctree b/docs/_build/doctrees/writing/documentation.doctree new file mode 100644 index 0000000..c58225a Binary files /dev/null and b/docs/_build/doctrees/writing/documentation.doctree differ diff --git a/docs/_build/doctrees/writing/license.doctree b/docs/_build/doctrees/writing/license.doctree new file mode 100644 index 0000000..eb70bfe Binary files /dev/null and b/docs/_build/doctrees/writing/license.doctree differ diff --git a/docs/_build/doctrees/writing/structure.doctree b/docs/_build/doctrees/writing/structure.doctree new file mode 100644 index 0000000..cc779ad Binary files /dev/null and b/docs/_build/doctrees/writing/structure.doctree differ diff --git a/docs/_build/doctrees/writing/style.doctree b/docs/_build/doctrees/writing/style.doctree new file mode 100644 index 0000000..4fe5938 Binary files /dev/null and b/docs/_build/doctrees/writing/style.doctree differ diff --git a/docs/_build/doctrees/writing/tests.doctree b/docs/_build/doctrees/writing/tests.doctree new file mode 100644 index 0000000..e3b76cb Binary files /dev/null and b/docs/_build/doctrees/writing/tests.doctree differ diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo new file mode 100644 index 0000000..bda7d10 --- /dev/null +++ b/docs/_build/html/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: f9ca5d98ba72140a2e4abd39df74c871 +tags: fbb0d17656682115ca4d033fb2f83ba1 diff --git a/docs/_build/html/_sources/_themes/README.txt b/docs/_build/html/_sources/_themes/README.txt new file mode 100644 index 0000000..8648482 --- /dev/null +++ b/docs/_build/html/_sources/_themes/README.txt @@ -0,0 +1,25 @@ +krTheme Sphinx Style +==================== + +This repository contains sphinx styles Kenneth Reitz uses in most of +his projects. It is a drivative of Mitsuhiko's themes for Flask and Flask related +projects. To use this style in your Sphinx documentation, follow +this guide: + +1. put this folder as _themes into your docs folder. Alternatively + you can also use git submodules to check out the contents there. + +2. add this to your conf.py: :: + + sys.path.append(os.path.abspath('_themes')) + html_theme_path = ['_themes'] + html_theme = 'flask' + +The following themes exist: + +**kr** + the standard flask documentation theme for large projects + +**kr_small** + small one-page theme. Intended to be used by very small addon libraries. + diff --git a/docs/_build/html/_sources/dev/env.txt b/docs/_build/html/_sources/dev/env.txt new file mode 100644 index 0000000..99ccf7b --- /dev/null +++ b/docs/_build/html/_sources/dev/env.txt @@ -0,0 +1,241 @@ +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 `_ 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 `_ 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 `_ is currently in beta. + +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 `_. + +Eclipse +------- + +The most popular Eclipse plugin for Python development is Aptana's +`PyDev `_. + + +Komodo IDE +----------- +`Komodo IDE `_ is developed by ActiveState and is a commerical IDE for Windows, Mac +and Linux. + +Spyder +------ + +`Spyder `_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy `_). +Includes integration with pyflakes_, `pylint `_, +and `rope `_. + +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 `_ 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 `_ 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 `_ 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 +------- + +`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/_build/html/_sources/dev/virtualenvs.txt b/docs/_build/html/_sources/dev/virtualenvs.txt new file mode 100644 index 0000000..9def09b --- /dev/null +++ b/docs/_build/html/_sources/dev/virtualenvs.txt @@ -0,0 +1,128 @@ +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 +---------- + +`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 +----------------- + +`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/_build/html/_sources/index.txt b/docs/_build/html/_sources/index.txt new file mode 100644 index 0000000..a1b1d4d --- /dev/null +++ b/docs/_build/html/_sources/index.txt @@ -0,0 +1,15 @@ +.. osxpython documentation master file, created by + sphinx-quickstart on Wed Aug 4 22:51:11 2010. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +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 `_! + +This *opinionated* guide 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. + +.. include:: contents.rst.inc \ No newline at end of file diff --git a/docs/_build/html/_sources/intro/community.txt b/docs/_build/html/_sources/intro/community.txt new file mode 100644 index 0000000..be1176e --- /dev/null +++ b/docs/_build/html/_sources/intro/community.txt @@ -0,0 +1,73 @@ +The Community +============= + +BDFL +---- + +Guido van Rossum, the creator of Python, is often referred to as the BDFL — the Benevolent Dictator For Life. + + + +Python Software Foundation +-------------------------- + +The mission of the Python Software Foundation is to promote, protect, and advance the Python programming language, and to support and facilitate the growth of a diverse and international community of Python programmers. + +`Learn More about the PSF `_. + + +PEPs +---- + +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 `_): + + **Standards** + Describes a new feature or implementation. + + **Informational** + Describes a design issue, general guidelines, or information to the community. + + **Process** + Describes a process related to Python. + + +Notable PEPs +~~~~~~~~~~~~ + +There are a few PEPs that could be considered required reading: + +- `PEP8 `_: The Python Style Guide. + Read this. All of it. Follow it. + +- `PEP20 `_: The Zen of Python. + A list of 19 statements that briefly explain the philosophy behind Python. + +- `PEP257 `_: Docstring Conventions. + Gives guidelines for semantics and conventions associated with Python docstrings. + +You can read more at `The PEP Index `_. + +Submitting a PEP +~~~~~~~~~~~~~~~~ + + PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone can write and submit a PEP for review. + + Here's an overview of the PEP acceptance workflow: + + .. image:: http://www.python.org/dev/peps/pep-0001/pep-0001-1.png + + +Python Conferences +-------------------------- + +The major events for the Python community are developer conferences. The two most notable conferences are PyCon, which is held in the US, and its European sibling, EuroPython. + +A comprehensive list of conferences is maintained `at pycon.org `_. + + +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 `_. diff --git a/docs/_build/html/_sources/intro/documentation.txt b/docs/_build/html/_sources/intro/documentation.txt new file mode 100644 index 0000000..3359f37 --- /dev/null +++ b/docs/_build/html/_sources/intro/documentation.txt @@ -0,0 +1,20 @@ +Documentation +============= + +Official Documentation +---------------------- + +The official Python Language and Library documentation can be found here: + + - `Python 2.x `_ + - `Python 3.x `_ + + +Read the Docs +------------- + +Read the Docs is a popular community project, providing a single location for all documentation of popular and even more exotic Python modules. + + `Read the Docs `_ + + diff --git a/docs/_build/html/_sources/intro/duction.txt b/docs/_build/html/_sources/intro/duction.txt new file mode 100644 index 0000000..0bd99e7 --- /dev/null +++ b/docs/_build/html/_sources/intro/duction.txt @@ -0,0 +1,39 @@ +Introduction +============ + +.. 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 +`_ 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. + + diff --git a/docs/_build/html/_sources/intro/learning.txt b/docs/_build/html/_sources/intro/learning.txt new file mode 100644 index 0000000..ecf3829 --- /dev/null +++ b/docs/_build/html/_sources/intro/learning.txt @@ -0,0 +1,67 @@ +Learning Python +=============== + +Beginner +-------- + +Learn Python Interactive Tutorial +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Learnpython.org is an easy non-intimidating way to get introduced to python. The website takes the same approach used on the popular `Try Ruby `_ website, it has an interactive python interpreter built into the site that allows you to go through the lessons without having to install Python locally. + + `Learn Python `_ + +Learn Python the Hard Way +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is an excellent beginner programmer's guide to Python. It covers "hello world" from the console to the web. + + `Learn Python the Hard Way `_ + + +Crash into Python +~~~~~~~~~~~~~~~~~ + +Also known as *Python for Programmers with 3 Hours*, this guide gives experienced developers from other languages a crash course on Python. + + `Crash into Python `_ + + +Dive Into Python 3 +~~~~~~~~~~~~~~~~~~ + +Dive Into Python 3 is a good book for those ready to jump in to Python 3. It's a +good read if you are moving from Python 2 to 3 or if you already have some +experience programming in another language. + + `Dive Into Python 3 `_ + +Think Python: How to Think Like a Computer Scientist +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Think Python attempts to give an introduction to basic concepts in computer science through the +use of the python language. The focus was to create a book with plenty of exercises, minimal jargon and +a section in each chapter devoted to the subject of debugging. + +While exploring the various features available in the python language the author weaves in various design +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 assignments in GUI +and Markov Analysis. + + `Think Python `_ + + +Advanced +-------- + +Pro Python +~~~~~~~~~~ + +.. todo:: Write about `Pro Python `_ + +Expert Python Programming +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. todo:: Write about `Expert Python Programming `_ diff --git a/docs/_build/html/_sources/intro/news.txt b/docs/_build/html/_sources/intro/news.txt new file mode 100644 index 0000000..b24fa93 --- /dev/null +++ b/docs/_build/html/_sources/intro/news.txt @@ -0,0 +1,25 @@ +News +==== + +Planet Python +~~~~~~~~~~~~~ + +This is an aggregate of Python news from a growing number of developers. + + `Planet Python `_ + +/r/python +~~~~~~~~~ + +/r/python is the Reddit Python community where users contribute and vote on +Python-related news. + + `/r/python `_ + +Python Weekly +~~~~~~~~~~~~~ + +Python Weekly is a free weekly newsletter featuring curated news, articles, +new releases, jobs, etc. related to Python. + + `Python Weekly `_ diff --git a/docs/_build/html/_sources/notes/contribute.txt b/docs/_build/html/_sources/notes/contribute.txt new file mode 100644 index 0000000..0d709f2 --- /dev/null +++ b/docs/_build/html/_sources/notes/contribute.txt @@ -0,0 +1,27 @@ +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_. +Once your changes get merged back in, you'll automatically be added to the +`Contributors List `_. + +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. + + .. include:: ../../TODO.rst + + +.. _GitHub: http://github.com/kennethreitz/python-guide/ +.. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst diff --git a/docs/_build/html/_sources/notes/license.txt b/docs/_build/html/_sources/notes/license.txt new file mode 100644 index 0000000..d26b3c7 --- /dev/null +++ b/docs/_build/html/_sources/notes/license.txt @@ -0,0 +1,4 @@ +License +------- + +.. todo:: Determine License \ No newline at end of file diff --git a/docs/_build/html/_sources/notes/styleguide.txt b/docs/_build/html/_sources/notes/styleguide.txt new file mode 100644 index 0000000..626d4a8 --- /dev/null +++ b/docs/_build/html/_sources/notes/styleguide.txt @@ -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 +`. + +* 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 `_ + 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 `_ + +* 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: +`_ +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 +`_ 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 +`_. 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 + diff --git a/docs/_build/html/_sources/scenarios/admin.txt b/docs/_build/html/_sources/scenarios/admin.txt new file mode 100644 index 0000000..991cab2 --- /dev/null +++ b/docs/_build/html/_sources/scenarios/admin.txt @@ -0,0 +1,87 @@ +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 \ No newline at end of file diff --git a/docs/_build/html/_sources/scenarios/ci.txt b/docs/_build/html/_sources/scenarios/ci.txt new file mode 100644 index 0000000..d2abfa9 --- /dev/null +++ b/docs/_build/html/_sources/scenarios/ci.txt @@ -0,0 +1,37 @@ +Continuous Integration +====================== + + +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. + +Jenkins +------- + +`Jenkins CI `_ is an extensible continuous integration engine. Use it. + + + +Buildbot +-------- +`Buildbot `_ is a Python system to automate the compile/test cycle to validate code changes. + + +Mule? +----- + +.. todo:: Write about Mule + +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/_build/html/_sources/scenarios/cli.txt b/docs/_build/html/_sources/scenarios/cli.txt new file mode 100644 index 0000000..cea7a3f --- /dev/null +++ b/docs/_build/html/_sources/scenarios/cli.txt @@ -0,0 +1,9 @@ +Command Line Applications +========================= + +.. todo:: Explain "Command Line Applications" + +Clint +----- + +.. todo:: Write about Clint \ No newline at end of file diff --git a/docs/_build/html/_sources/scenarios/db.txt b/docs/_build/html/_sources/scenarios/db.txt new file mode 100644 index 0000000..7b6ad95 --- /dev/null +++ b/docs/_build/html/_sources/scenarios/db.txt @@ -0,0 +1,28 @@ +Databases +========= + +DB-API +------ + +The Python Database API (DB-API) defines a standard interface for Python +database access modules. It's documented in `PEP 249 `_. +Nearly all Python database modules such as `sqlite3`, `psycopg` and +`mysql-python` conform to this interface. + + + +SQLAlchemy +---------- + +`SQLAlchemy `_ is a commonly used database toolkit. Unlike many database libraries +it not only provides an ORM layer but also a generalized API for writing +database-agnostic code without SQL. + +:: + + pip install sqlalchemy + +Django ORM +---------- + +.. todo:: Explain Django ORM \ No newline at end of file diff --git a/docs/_build/html/_sources/scenarios/gui.txt b/docs/_build/html/_sources/scenarios/gui.txt new file mode 100644 index 0000000..2490d98 --- /dev/null +++ b/docs/_build/html/_sources/scenarios/gui.txt @@ -0,0 +1,55 @@ +GUI Applications +================ + + +Qt +:: +Qt is a cross-platform application framework that is widely used for developing software with a GUI but can also be used for non-GUI applications. + +PySide +------ +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! + +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! + +PyObjC +------ +.. 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 +::: +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 +:: +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/_build/html/_sources/scenarios/scientific.txt b/docs/_build/html/_sources/scenarios/scientific.txt new file mode 100644 index 0000000..52a1efe --- /dev/null +++ b/docs/_build/html/_sources/scenarios/scientific.txt @@ -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 `_ 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 `_ 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 `_ 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 `_ 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. \ No newline at end of file diff --git a/docs/_build/html/_sources/scenarios/speed.txt b/docs/_build/html/_sources/scenarios/speed.txt new file mode 100644 index 0000000..bd83cde --- /dev/null +++ b/docs/_build/html/_sources/scenarios/speed.txt @@ -0,0 +1,96 @@ +Speed +===== + +CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. `PyPy`_ is fast. + +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 +::::::: + + +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 +------------ + + +The GIL +------- + +`Special care`_ must be taken when writing C extensions to make sure you register your threads +with the interpreter. + +C Extentions +:::::::::::: + + +Cython +------ + + +Pyrex +----- + + +Shedskin? +--------- + + + +Threading +::::::::: + + +Threading +--------- + + +Spanwing Processes +------------------ + + +Multiprocessing +--------------- + + +.. _`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/_build/html/_sources/scenarios/web.txt b/docs/_build/html/_sources/scenarios/web.txt new file mode 100644 index 0000000..04c36e7 --- /dev/null +++ b/docs/_build/html/_sources/scenarios/web.txt @@ -0,0 +1,228 @@ +================ +Web Applications +================ + + +Context +::::::: + + +WSGI +---- + +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 :ref:`WSGI-compliant web server `. WSGI is +documented in `PEP-3333 `_. + + +Frameworks +:::::::::: + +Broadly speaking, a web framework is a set of libraries upon which you can +build custom code to implement a web application (i.e. an interactive web +site). Most web frameworks include patterns and utilities to accomplish at +least the following: + +URL Routing + Matches an incoming HTTP request to a particular piece of Python code to + be invoked + +Request and Response Objects + Encapsulate the information received from or sent to a user's browser + +Template Engine + Allows for separating Python code implementing an application's logic from + the HTML (or other) output that it produces + +Development Web Server + Runs an HTTP server on development machines to enable rapid development; + often automatically reloads server-side code when files are updated + + +Django +------ + +`Django `_ is a "batteries included" web +application framework. By providing many utilities and patterns out of the +box, Django aims to make it possible to build complex, database-backed web +applications quickly, while encouraging best practices in code written using +it. + +Django has a large and active community, and many pre-built `re-usable +modules `_ that can be incorporated into a new +project as-is, or customized to fit your needs. + +There are annual Django conferences `in the United States +`_ and `in Europe `_. + + +Flask +----- + +`Flask `_ is a "microframework" for Python. Rather +than aiming to provide everything you could possibly need, Flask implements +the most commonly-used core components of a web application framework, like +URL routing, request and response objects, and templates. As a user of +Flask, it is therefore up to you to choose and integrate other components +you may need, such as database access or form generation and validation. For +many popular modules, `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. + + +.. todo:: Explain Pyramid + + +Web Servers +::::::::::: + +.. _nginx-ref: + +Nginx +----- + +`Nginx `_ (pronounced "engine-x") is a web server and +reverse-proxy for HTTP, SMTP and other protocols. It is known for its +high performance, relative simplicity, and compatibility with many +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. + + +.. _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 `_ (Green Unicorn) is a WSGI server used +to serve Python applications. It is a Python interpretation of the Ruby +`Unicorn `_ server. Unicorn 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 `_. + +.. _uwsgi-ref: + + +Server Best Practices +::::::::::::::::::::: + +The majority of self hosted Python applications today are hosted with a WSGI +server such as :ref:`gUnicorn `, either directly or behind a +lightweight web server such as :ref:`nginx `. + +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 +::::::: + +Platform-as-a-Service +--------------------- + +Platform-as-a-Service (PaaS) is a type of cloud computing infrastructure +which abstracts and manages infrastructure, routing, and scaling of web +applications. When using PaaS, application developers can focus on writing +application code rather than needing to be concerned with deployment +details. + +Most PaaS services offer a command-line interface that developers can use to +set up and interrogate configuration, and to deploy new releases of an +application to the service. + +PaaS services and their partners offer add-on functionality which is well +integrated into the platform, such as database hosting, email services, +logging, scheduled and background tasks, billing and payment, etc. + + +Heroku +~~~~~~ + +`Heroku `_'s +`Cedar stack `_ offers first class +support for Python 2.7 applications. + +Heroku allows you to run as many Python web applications as you like, 24/7 and free +of charge. Heroku is best described as a horizontal scaling platform. They start +to charge you once you "scale" you application to run on more than one Dyno +(abstacted servers) at a time. + +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 +`_. + + +DotCloud +~~~~~~~~ + +`DotCloud `_ supports WSGI applications and +background/worker tasks natively on their platform. Web applications running +Python version 2.6, and uses :ref:`nginx ` and :ref:`uWSGI +`, and allows custom configuration of both +for advanced users. + +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. + + +ep.io +~~~~~ + +`ep.io `_ is a PaaS designed specifically for Python web +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. + +ep.io is currently in invite-only beta. + + +Gondor +~~~~~~ + +`Gondor `_ is a PaaS specailized for deploying Django +and Pinax applications. Gondor supports Django versions 1.2 and 1.3 on +Python version 2.7, and can automatically configure your Django site if you +use ``local_settings.py`` for site-specific configuration information. + +Gondor publishes guides to deploying `Django projects +`_ and `Pinax projects +`_ on their platform. + + +.. rubric:: References + +.. [1] `The mod_python project is now officially dead `_ +.. [2] `mod_wsgi vs mod_python `_ +.. [3] `Benchmark of Python WSGI Servers `_ diff --git a/docs/_build/html/_sources/shipping/freezing.txt b/docs/_build/html/_sources/shipping/freezing.txt new file mode 100644 index 0000000..b6803af --- /dev/null +++ b/docs/_build/html/_sources/shipping/freezing.txt @@ -0,0 +1,49 @@ +Freezing Your Code +================== + +An alternative to shipping your code is freezing it — shipping it as an +executable with a bundled Python interpreter. + +Many applications you use every day do this: + +- Dropbox +- BitTorrent +- + + +.. todo:: Fill in "Freezing Your Code" stub + +Windows +::::::: + + +py2exe +------ + + + +OSX +::: + + +py2app +------ + + + + +PyInstaller +----------- + + + + +Linux +::::: + + +bbFreeze +-------- + +PyInstaller +----------- diff --git a/docs/_build/html/_sources/shipping/packaging.txt b/docs/_build/html/_sources/shipping/packaging.txt new file mode 100644 index 0000000..28762e1 --- /dev/null +++ b/docs/_build/html/_sources/shipping/packaging.txt @@ -0,0 +1,69 @@ +Packaging Your Code +=================== + +Packaging your code is important. + +.. todo:: Write introduction for "Packaging Your Code" + +For Python Developers +::::::::::::::::::::: + +If you're writing an open source Python module, `PyPI `_, more properly known as *The Cheeseshop*, is the place to host it. + + + +Pip vs. easy_install +-------------------- + +Use `pip `_. More details `here `_ + + +Personal PyPI +------------- + +If you want to install packages from a source different from PyPI, (say, if +your packages are *proprietary*), you can do it by hosting a simple http server, +running from the directory which holds those packages which need to be installed. + +**Showing an example is always beneficial** + +Say if you are after installing a package called MyPackage.tar.gz, and assuming this is your directory structure + + +- archive + - MyPackage + - MyPackage.tar.gz + +Go to your command prompt and type: +:: + +$ cd archive +$ python -m SimpleHTTPServer 9000 + +This runs a simple http server running on port 9000 and will list all packages (like **MyPackage**). Now you can install **MyPackage** using any python package installer. Using Pip, you would do it like: +:: + +$ pip install --extra-index-url=http://127.0.0.1:9000/ MyPackage + +Having a folder with the same name as the package name is **crucial** here. +I got fooled by that, one time. But if you feel that creating a folder called +**MyPackage** and keeping **MyPackage.tar.gz** inside that, is *redundant*, you can still install MyPackage using: +:: + +$ pip install http://127.0.0.1:9000/MyPackage.tar.gz + +Chishop ++++++++ + +`Chishop `_ 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 +------------ + +- epm +- alien diff --git a/docs/_build/html/_sources/starting/dev-env.txt b/docs/_build/html/_sources/starting/dev-env.txt new file mode 100644 index 0000000..b1f2498 --- /dev/null +++ b/docs/_build/html/_sources/starting/dev-env.txt @@ -0,0 +1,137 @@ +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 `_.. + +Eclipse +------- + +The most popular Eclipse plugin for Python development is Aptana's +`PyDev `_. + + +Komodo IDE +----------- +`Komodo IDE `_ is developed by ActiveState and is a commerical IDE for Windows, Mac +and Linux. + +Spyder +------ + +`Spyder `_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy `_). +Includes integration with `pyflakes `_, `pylint `_, +and `rope `_. + +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 + + diff --git a/docs/_build/html/_sources/starting/installation.txt b/docs/_build/html/_sources/starting/installation.txt new file mode 100644 index 0000000..4b8477c --- /dev/null +++ b/docs/_build/html/_sources/starting/installation.txt @@ -0,0 +1,161 @@ +Properly Installing Python +========================== + +Mac OS X +:::::::: + +*Or, "Installing Python 2.7 via Homebrew".* + +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. + +To install Homebrew, simply run: :: + + $ ruby -e "$(curl -fsS http://gist.github.com/raw/323731/install_homebrew.rb)" + + +It's basic commands are **update**, **install**, and **remove**. + +.. man brew + + +And we can now install Python 2.7: :: + + $ brew install python --framework + + +The ``--framework`` option tells Homebrew to compile a Framework-style Python build, rather than a UNIX-style build. The outdated version of Python that Snow Leopard comes packaged with +is built as a Framework, so this helps avoid some future module installation +bugs. + +*Don't forget to update your environment PATH.* + + +Building From Source +-------------------- + + + + +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.python.org, amongst a few other sources. It also plays well with +*virtualenv* and user-enviornments. + +**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* and Distribute's *easy_install*: + +If you have homebrew: :: + + $ brew install pip + +...And, if you're a masochist: :: + + $ curl -O http://python-distribute.org/distribute_setup.py + $ python distribute_setup.py + + $ easy_install pip + + + +To install ``pip``: :: + +Hopefully you'll never have to use **easy_install** again. + + +Updating Python +--------------- + +Homebrew makes it simple. :: + + $ brew update + $ brew install --force python + + +Windows +::::::: + + + +Prerequisites: +-------------- + +* Python2.7 (x86) from Python.org +* Microsoft Visual Studio + + +Step 1: 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. + +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: :: + + $ easy_install pip + + +Linux (Ubuntu) +:::::::::::::: + +Oneiric Ocelot, the latest version of Ubuntu, **comes with Python 2.7 out of the box**. Python 3.2 can be installed and run with the following commands:: + + $ sudo apt-get install python3-minimal + $ python3 + +Older versions of Python aren't available from the official repository. However, if it's needed (for example to support legacy code), we can add an unsupported repository and install an older version of Python (2.5 in the example below):: + + $ sudo apt-get install python-software-properties + $ sudo add-apt-repository ppa:fkrull/deadsnakes + $ sudo apt-get update + $ sudo apt-get install python2.5 + +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? + + $ 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 + +Now, most Python packages can be installed using the ``pip`` command. For example, if we wanted to install Django:: + + $ sudo pip install django + +A full list of ``pip``'s capabilities is available by typing ``pip --help``. + +Linux (Manual) +-------------- + +While your system will quite likely already have Python installation, you might wish to install a different version. This is done in the typical Linux software source install procedure:: + + $ wget http://www.python.org/ftp/python/2.7.2/Python-2.7.2.tgz + $ tar -xvf Python-2.7.2.tgz + $ cd Python-2.7.2 + $ ./configure + $ make + $ make install + + + diff --git a/docs/_build/html/_sources/starting/next.txt b/docs/_build/html/_sources/starting/next.txt new file mode 100644 index 0000000..e69de29 diff --git a/docs/_build/html/_sources/starting/which-python.txt b/docs/_build/html/_sources/starting/which-python.txt new file mode 100644 index 0000000..9a22bc4 --- /dev/null +++ b/docs/_build/html/_sources/starting/which-python.txt @@ -0,0 +1,97 @@ +Picking an Interpreter +====================== + +Which Python to use? + + +2.x vs 3.x +~~~~~~~~~~ + +**tl;dr**: Python 2.x is the status quo, Python 3.x is the shiny new thing. + + +`Further Reading `_ + + +Today +----- + +If you're choosing a Python interpreter to use, I *highly* recommend you Use Python 2.7.x, unless you have a strong reason not to. + + +The Future +---------- + +As more and more modules get ported over to Python3, the easier it will be for +others to use it. + + +Which Python to Support? +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're starting work on a new Python module, I recommend you write it for +Python 2.5 or 2.6, and add support for Python3 in a later iteration. + +Implementations +~~~~~~~~~~~~~~~ + +There are several popular implementations of the Python programming language on +different back-ends. + +CPython +------- + +`CPython `_ is the reference implementation of Python, +written in C. It compiles Python code to intermediate bytecode which is then +interpreted by a virtual machine. When people speak of *Python* they often mean +not just the language but also this implementation. It provides the highest +level of compatibility with Python packages and C extension modules. + +If you are writing open-source Python code and want to reach the widest possible +audience, targeting CPython is your best bet. If you need to use any packages +that are rely on C extensions for their functionality (eg: numpy) then CPython +is your only choice. + +Being the reference implementation, all versions of the Python language are +available as CPython. Python 3 is only available in a CPython implementation. + +PyPy +---- + +`PyPy `_ is a Python interpreter implemented in a restricted +statically-typed subset of the Python language called RPython. The interpreter +features a just-in-time compiler and supports multiple back-ends (C, CLI, JVM). + +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. + +Currently PyPy supports Python 2.7. + +Jython +------ + +`Jython `_ is a Python implementation that compiles +Python code to Java byte code that then executes on a JVM. It has the additional +advantage of being able to import and use any Java class the same as a Python +module. + +If you need to interface with an existing Java codebase or have other reasons to +need to write Python code for the JVM, Jython is the best choice. + +Currently Jython supports up to Python 2.5. + +IronPython +---------- + +`IronPython `_ is an implementation of Python for .NET +framework. It can use both Python and .NET framework libraries, and can also +expose Python code to other .NET languages. + +`Python Tools for Visual Studio `_ integrate +IronPython directly in to the Visual Studio development environment, making it +an ideal choice for Windows developers. + +IronPython supports Python 2.7. diff --git a/docs/_build/html/_sources/writing/documentation.txt b/docs/_build/html/_sources/writing/documentation.txt new file mode 100644 index 0000000..094a013 --- /dev/null +++ b/docs/_build/html/_sources/writing/documentation.txt @@ -0,0 +1,76 @@ +Documenting Your Code +===================== + +Documenting your code is extremely important. It is debatebly even +more important than testing. + + +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.: :: + + Block comments generally apply to some (or all) code that follows them, + and are indented to the same level as that code. Each line of a block + comment starts with a # and a single space (unless it is indented text + inside the comment). + Paragraphs inside a block comment are separated by a line containing a + single #. + +Inline comments are used for individual lines and should be used sparingly.: :: + + An inline comment is a comment on the same line as a statement. Inline + comments should be separated by at least two spaces from the statement. + They should start with a # and a single space. + Inline comments are unnecessary and in fact distracting if they state + the obvious. Don't do this: + x = x + 1 # Increment x + But sometimes, this is useful: :: + x = x + 1 # Compensate for border + +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: :: + + def 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. + + 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 + ... + +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. + + + +Other Tools +::::::::::: + +that old thing +-------------- + +pocco / docco / shocco +---------------------- + +Ronn +---- \ No newline at end of file diff --git a/docs/_build/html/_sources/writing/license.txt b/docs/_build/html/_sources/writing/license.txt new file mode 100644 index 0000000..6d91fea --- /dev/null +++ b/docs/_build/html/_sources/writing/license.txt @@ -0,0 +1,54 @@ +Choosing a License +================== + +Open source. + + + + + +Non-Restrictive +::::::::::::::: + +PSFL +---- + + +MIT / BSD / ISC +--------------- + + +MIT (X11) +````````` + +New BSD +``````` + +ISC +``` + +Apache +------ + + +Restrictive +::::::::::: + + +LGPL +---- + + + +GPL +--- + + +GPLv2 +````` + + +GPLv3 +````` + + diff --git a/docs/_build/html/_sources/writing/structure.txt b/docs/_build/html/_sources/writing/structure.txt new file mode 100644 index 0000000..849bdea --- /dev/null +++ b/docs/_build/html/_sources/writing/structure.txt @@ -0,0 +1,22 @@ +Structuring Your Project +======================== + +Structuring your project properly is extremely important. + + +Structure is Key +---------------- + + + +Vendorizing Dependencies +------------------------ + + + +Runners +------- + + +Further Reading +--------------- \ No newline at end of file diff --git a/docs/_build/html/_sources/writing/style.txt b/docs/_build/html/_sources/writing/style.txt new file mode 100644 index 0000000..216c780 --- /dev/null +++ b/docs/_build/html/_sources/writing/style.txt @@ -0,0 +1,54 @@ +Code Style +========== + + +Idioms +:::::: + +Idiomatic Python code is often referred to as being *pythonic*. + + +Zen of Python +------------- + +Also known as PEP 20, the guiding principles for Python's design. + +:: + + >>> import this + +See ``_ for some +examples. + +PEP 8 +----- + +PEP 8 is the de-facto code style guide for Python. + + `PEP 8 `_ + +There exists a command-line program, `pep8` that can check your code for +conformance. + +:: + + pip install pep8 + + +Simply run it on a file or series of files and get a report of any +violations + +:: + + $ pep8 optparse.py + optparse.py:69:11: E401 multiple imports on one line + optparse.py:77:1: E302 expected 2 blank lines, found 1 + optparse.py:88:5: E301 expected 1 blank line, found 0 + optparse.py:222:34: W602 deprecated form of raising exception + optparse.py:347:31: E211 whitespace before '(' + optparse.py:357:17: E201 whitespace after '{' + optparse.py:472:29: E221 multiple spaces before operator + optparse.py:544:21: W601 .has_key() is deprecated, use 'in' + +Conforming your style to PEP 8 is generally a good idea and helps make code a lot +more consistent when working on projects with other developers. diff --git a/docs/_build/html/_sources/writing/tests.txt b/docs/_build/html/_sources/writing/tests.txt new file mode 100644 index 0000000..90a63df --- /dev/null +++ b/docs/_build/html/_sources/writing/tests.txt @@ -0,0 +1,158 @@ +Testing Your Code +===================== + +Testing your code is very important. + + +The Basics +:::::::::: + + +Unittest +-------- + +Unittest is the batteries-included test module in the Python standard library. +Its API will be familiar to anyone who has used any of the JUnit/nUnit/CppUnit +series of tools. + +Creating testcases is accomplished by subclassing a TestCase base class + +:: + + import unittest + + def fun(x): + return x + 1 + + class MyTest(unittest.TestCase): + def test(self): + self.assertEqual(fun(3), 4) + +As of Python 2.7 unittest also includes its own test discovery mechanisms. + + `unittest in the standard library documentation `_ + + +Doctest +------- + +The doctest module searches for pieces of text that look like interactive Python +sessions, and then executes those sessions to verify that they work exactly as +shown. + + +Tools +::::: + + +py.test +------- + +py.test is a no-boilerplate alternative to Python's standard unittest module. + +:: + + $ pip install pytest + +Despite being a fully-featured and extensible test tool it boasts a simple +syntax. Creating a test suite is as easy as writing a module with a couple of +functions + +:: + + # content of test_sample.py + def func(x): + return x + 1 + + def test_answer(): + assert func(3) == 5 + +and then running the `py.test` command + +:: + + $ py.test + =========================== test session starts ============================ + platform darwin -- Python 2.7.1 -- pytest-2.2.1 + collecting ... collected 1 items + + test_sample.py F + + ================================= FAILURES ================================= + _______________________________ test_answer ________________________________ + + def test_answer(): + > assert func(3) == 5 + E assert 4 == 5 + E + where 4 = func(3) + + test_sample.py:5: AssertionError + ========================= 1 failed in 0.02 seconds ========================= + +far less work than would be required for the equivalent functionality with the +unittest module! + + `py.test `_ + + +Nose +---- + +nose extends unittest to make testing easier. + + +:: + + $ pip install nose + +nose provides automatic test discovery to save you the hassle of manually +creating test suites. It also provides numerous plugins for features such as +xUnit-compatible test output, coverage reporting, and test selection. + + `nose `_ + + +tox +--- + +tox is a tool for automating test environment management and testing against multiple +interpreter configurations + +:: + + $ pip install tox + +tox allows you to configure complicatated multi-parameter test matrices via a +simple ini-style configuration file. + + `tox `_ + +Unittest2 +--------- + +unittest2 is a a backport of Python 2.7's unittest module which has an improved +API and better assertions over the one available in previous versions of Python. + +If you're using Python 2.6 or below, you can install it with pip + +:: + + $ pip install unittest2 + +You may want to import the module under the name unittest to make porting code +to newer versions of the module easier in the future + +:: + + import unittest2 as unittest + + class MyTest(unittest.TestCase): + ... + +This way if you ever switch to a newer python version and no longer need the +unittest2 module, you can simply change the import in your test module without +the need to change any other code. + + `unittest2 `_ + + diff --git a/docs/_build/html/_static/ajax-loader.gif b/docs/_build/html/_static/ajax-loader.gif new file mode 100644 index 0000000..61faf8c Binary files /dev/null and b/docs/_build/html/_static/ajax-loader.gif differ diff --git a/docs/_build/html/_static/basic.css b/docs/_build/html/_static/basic.css new file mode 100644 index 0000000..f0379f3 --- /dev/null +++ b/docs/_build/html/_static/basic.css @@ -0,0 +1,540 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar input[type="text"] { + width: 170px; +} + +div.sphinxsidebar input[type="submit"] { + width: 30px; +} + +img { + border: 0; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlighted { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/docs/_build/html/_static/comment-bright.png b/docs/_build/html/_static/comment-bright.png new file mode 100644 index 0000000..551517b Binary files /dev/null and b/docs/_build/html/_static/comment-bright.png differ diff --git a/docs/_build/html/_static/comment-close.png b/docs/_build/html/_static/comment-close.png new file mode 100644 index 0000000..09b54be Binary files /dev/null and b/docs/_build/html/_static/comment-close.png differ diff --git a/docs/_build/html/_static/comment.png b/docs/_build/html/_static/comment.png new file mode 100644 index 0000000..92feb52 Binary files /dev/null and b/docs/_build/html/_static/comment.png differ diff --git a/docs/_build/html/_static/doctools.js b/docs/_build/html/_static/doctools.js new file mode 100644 index 0000000..bd1b44e --- /dev/null +++ b/docs/_build/html/_static/doctools.js @@ -0,0 +1,247 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilties for all documentation. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +} + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * small function to check if an array contains + * a given item. + */ +jQuery.contains = function(arr, item) { + for (var i = 0; i < arr.length; i++) { + if (arr[i] == item) + return true; + } + return false; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this); + }); + } + } + return this.each(function() { + highlight(this); + }); +}; + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('

' + _('Hide Search Matches') + '

') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/docs/_build/html/_static/down-pressed.png b/docs/_build/html/_static/down-pressed.png new file mode 100644 index 0000000..6f7ad78 Binary files /dev/null and b/docs/_build/html/_static/down-pressed.png differ diff --git a/docs/_build/html/_static/down.png b/docs/_build/html/_static/down.png new file mode 100644 index 0000000..3003a88 Binary files /dev/null and b/docs/_build/html/_static/down.png differ diff --git a/docs/_build/html/_static/file.png b/docs/_build/html/_static/file.png new file mode 100644 index 0000000..d18082e Binary files /dev/null and b/docs/_build/html/_static/file.png differ diff --git a/docs/_build/html/_static/flasky.css b/docs/_build/html/_static/flasky.css new file mode 100644 index 0000000..f26bb1a --- /dev/null +++ b/docs/_build/html/_static/flasky.css @@ -0,0 +1,570 @@ +/* + * flasky.css_t + * ~~~~~~~~~~~~ + * + * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz. + * :license: Flask Design License, see LICENSE for details. + */ + + + + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; + font-size: 17px; + background-color: white; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + width: 940px; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 220px; +} + +div.sphinxsidebar { + width: 220px; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 0 30px; +} + +img.floatingflask { + padding: 0 0 10px 10px; + float: right; +} + +div.footer { + width: 940px; + margin: 20px auto 30px auto; + font-size: 14px; + color: #888; + text-align: right; +} + +div.footer a { + color: #888; +} + +div.related { + display: none; +} + +div.sphinxsidebar a { + color: #444; + text-decoration: none; + border-bottom: 1px dotted #999; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid #999; +} + +div.sphinxsidebar { + font-size: 14px; + line-height: 1.5; +} + +div.sphinxsidebarwrapper { + padding: 18px 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0; + margin: -10px 0 0 -20px; + text-align: center; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: 'Garamond', 'Georgia', serif; + color: #444; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: #444; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: #000; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: 'Georgia', serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #004B6B; + text-decoration: underline; +} + +a:hover { + color: #6D4100; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #ddd; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; + background: #eaeaea; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + background: #fafafa; + margin: 20px -30px; + padding: 10px 30px; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; +} + +div.admonition tt.xref, div.admonition a tt { + border-bottom: 1px solid #fafafa; +} + +dd div.admonition { + margin-left: -60px; + padding-left: 60px; +} + +div.admonition p.admonition-title { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: white; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt { + font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.9em; +} + +img.screenshot { +} + +tt.descname, tt.descclassname { + font-size: 0.95em; +} + +tt.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #eee; + background: #fdfdfd; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.footnote td.label { + width: 0px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: #eee; + padding: 7px 30px; + margin: 15px -30px; + line-height: 1.3em; +} + +dl pre, blockquote pre, li pre { + margin-left: -60px; + padding-left: 60px; +} + +dl dl pre { + margin-left: -90px; + padding-left: 90px; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, a tt { + background-color: #FBFBFB; + border-bottom: 1px solid white; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted #004B6B; +} + +a.reference:hover { + border-bottom: 1px solid #6D4100; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted #004B6B; +} + +a.footnote-reference:hover { + border-bottom: 1px solid #6D4100; +} + +a:hover tt { + background: #EEE; +} + + +@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 { + width: 6px; + height: 6px; +} + +::-webkit-scrollbar-button:start:decrement, +::-webkit-scrollbar-button:end:increment { + display: block; + height: 10px; +} + +::-webkit-scrollbar-button:vertical:increment { + background-color: #fff; +} + +::-webkit-scrollbar-track-piece { + background-color: #eee; + -webkit-border-radius: 3px; +} + +::-webkit-scrollbar-thumb:vertical { + height: 50px; + background-color: #ccc; + -webkit-border-radius: 3px; +} + +::-webkit-scrollbar-thumb:horizontal { + width: 50px; + background-color: #ccc; + -webkit-border-radius: 3px; +} + +/* misc. */ + +.revsys-inline { + display: none!important; +} \ No newline at end of file diff --git a/docs/_build/html/_static/jquery.js b/docs/_build/html/_static/jquery.js new file mode 100644 index 0000000..7c24308 --- /dev/null +++ b/docs/_build/html/_static/jquery.js @@ -0,0 +1,154 @@ +/*! + * jQuery JavaScript Library v1.4.2 + * http://jquery.com/ + * + * Copyright 2010, John Resig + * Dual licensed under the MIT or GPL Version 2 licenses. + * http://jquery.org/license + * + * Includes Sizzle.js + * http://sizzlejs.com/ + * Copyright 2010, The Dojo Foundation + * Released under the MIT, BSD, and GPL Licenses. + * + * Date: Sat Feb 13 22:33:48 2010 -0500 + */ +(function(A,w){function ma(){if(!c.isReady){try{s.documentElement.doScroll("left")}catch(a){setTimeout(ma,1);return}c.ready()}}function Qa(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,j){var i=a.length;if(typeof b==="object"){for(var o in b)X(a,o,b[o],f,e,d);return a}if(d!==w){f=!j&&f&&c.isFunction(d);for(o=0;o)[^>]*$|^#([\w-]+)$/,Ua=/^.[^:#\[\.,]*$/,Va=/\S/, +Wa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Xa=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,P=navigator.userAgent,xa=false,Q=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,R=Array.prototype.slice,ya=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(a==="body"&&!b){this.context=s;this[0]=s.body;this.selector="body";this.length=1;return this}if(typeof a==="string")if((d=Ta.exec(a))&& +(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:s;if(a=Xa.exec(a))if(c.isPlainObject(b)){a=[s.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=sa([d[1]],[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}return c.merge(this,a)}else{if(b=s.getElementById(d[2])){if(b.id!==d[2])return T.find(a);this.length=1;this[0]=b}this.context=s;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=s;a=s.getElementsByTagName(a);return c.merge(this, +a)}else return!b||b.jquery?(b||T).find(a):c(b).find(a);else if(c.isFunction(a))return T.ready(a);if(a.selector!==w){this.selector=a.selector;this.context=a.context}return c.makeArray(a,this)},selector:"",jquery:"1.4.2",length:0,size:function(){return this.length},toArray:function(){return R.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){var f=c();c.isArray(a)?ba.apply(f,a):c.merge(f,a);f.prevObject=this;f.context=this.context;if(b=== +"find")f.selector=this.selector+(this.selector?" ":"")+d;else if(b)f.selector=this.selector+"."+b+"("+d+")";return f},each:function(a,b){return c.each(this,a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(s,c);else Q&&Q.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(R.apply(this,arguments),"slice",R.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this, +function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice};c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,j,i,o;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b
a"; +var e=d.getElementsByTagName("*"),j=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!j)){c.support={leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(j.getAttribute("style")),hrefNormalized:j.getAttribute("href")==="/a",opacity:/^0.55$/.test(j.style.opacity),cssFloat:!!j.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:s.createElement("select").appendChild(s.createElement("option")).selected, +parentNode:d.removeChild(d.appendChild(s.createElement("div"))).parentNode===null,deleteExpando:true,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null};b.type="text/javascript";try{b.appendChild(s.createTextNode("window."+f+"=1;"))}catch(i){}a.insertBefore(b,a.firstChild);if(A[f]){c.support.scriptEval=true;delete A[f]}try{delete b.test}catch(o){c.support.deleteExpando=false}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function k(){c.support.noCloneEvent= +false;d.detachEvent("onclick",k)});d.cloneNode(true).fireEvent("onclick")}d=s.createElement("div");d.innerHTML="";a=s.createDocumentFragment();a.appendChild(d.firstChild);c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var k=s.createElement("div");k.style.width=k.style.paddingLeft="1px";s.body.appendChild(k);c.boxModel=c.support.boxModel=k.offsetWidth===2;s.body.removeChild(k).style.display="none"});a=function(k){var n= +s.createElement("div");k="on"+k;var r=k in n;if(!r){n.setAttribute(k,"return;");r=typeof n[k]==="function"}return r};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=j=null}})();c.props={"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ya=0,za={};c.extend({cache:{},expando:G,noData:{embed:true,object:true, +applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var f=a[G],e=c.cache;if(!f&&typeof b==="string"&&d===w)return null;f||(f=++Ya);if(typeof b==="object"){a[G]=f;e[f]=c.extend(true,{},b)}else if(!e[f]){a[G]=f;e[f]={}}a=e[f];if(d!==w)a[b]=d;return typeof b==="string"?a[b]:a}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{if(c.support.deleteExpando)delete a[c.expando]; +else a.removeAttribute&&a.removeAttribute(c.expando);delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this,a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===w){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===w&&this.length)f=c.data(this[0],a);return f===w&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this, +a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d);return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b=== +w)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]||a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var Aa=/[\n\t]/g,ca=/\s+/,Za=/\r/g,$a=/href|src|style/,ab=/(button|input)/i,bb=/(button|input|object|select|textarea)/i, +cb=/^(a|area)$/i,Ba=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(n){var r=c(this);r.addClass(a.call(this,n,r.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d-1)return true;return false},val:function(a){if(a===w){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value||{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var j=b?d:0;for(d=b?d+1:e.length;j=0;else if(c.nodeName(this,"select")){var u=c.makeArray(r);c("option",this).each(function(){this.selected= +c.inArray(c(this).val(),u)>=0});if(!u.length)this.selectedIndex=-1}else this.value=r}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return w;if(f&&b in c.attrFn)return c(a)[b](d);f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==w;b=f&&c.props[b]||b;if(a.nodeType===1){var j=$a.test(b);if(b in a&&f&&!j){if(e){b==="type"&&ab.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed"); +a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:bb.test(a.nodeName)||cb.test(a.nodeName)&&a.href?0:w;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText=""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&j?a.getAttribute(b,2):a.getAttribute(b);return a===null?w:a}return c.style(a,b,d)}});var O=/\.(.*)$/,db=function(a){return a.replace(/[^\w\s\.\|`]/g, +function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==A&&!a.frameElement)a=A;var e,j;if(d.handler){e=d;d=e.handler}if(!d.guid)d.guid=c.guid++;if(j=c.data(a)){var i=j.events=j.events||{},o=j.handle;if(!o)j.handle=o=function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(o.elem,arguments):w};o.elem=a;b=b.split(" ");for(var k,n=0,r;k=b[n++];){j=e?c.extend({},e):{handler:d,data:f};if(k.indexOf(".")>-1){r=k.split("."); +k=r.shift();j.namespace=r.slice(0).sort().join(".")}else{r=[];j.namespace=""}j.type=k;j.guid=d.guid;var u=i[k],z=c.event.special[k]||{};if(!u){u=i[k]=[];if(!z.setup||z.setup.call(a,f,r,o)===false)if(a.addEventListener)a.addEventListener(k,o,false);else a.attachEvent&&a.attachEvent("on"+k,o)}if(z.add){z.add.call(a,j);if(!j.handler.guid)j.handler.guid=d.guid}u.push(j);c.event.global[k]=true}a=null}}},global:{},remove:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){var e,j=0,i,o,k,n,r,u,z=c.data(a), +C=z&&z.events;if(z&&C){if(b&&b.type){d=b.handler;b=b.type}if(!b||typeof b==="string"&&b.charAt(0)==="."){b=b||"";for(e in C)c.event.remove(a,e+b)}else{for(b=b.split(" ");e=b[j++];){n=e;i=e.indexOf(".")<0;o=[];if(!i){o=e.split(".");e=o.shift();k=new RegExp("(^|\\.)"+c.map(o.slice(0).sort(),db).join("\\.(?:.*\\.)?")+"(\\.|$)")}if(r=C[e])if(d){n=c.event.special[e]||{};for(B=f||0;B=0){a.type= +e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();c.event.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return w;a.result=w;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d,b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(j){}if(!a.isPropagationStopped()&& +f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){f=a.target;var i,o=c.nodeName(f,"a")&&e==="click",k=c.event.special[e]||{};if((!k._default||k._default.call(d,a)===false)&&!o&&!(f&&f.nodeName&&c.noData[f.nodeName.toLowerCase()])){try{if(f[e]){if(i=f["on"+e])f["on"+e]=null;c.event.triggered=true;f[e]()}}catch(n){}if(i)f["on"+e]=i;c.event.triggered=false}}},handle:function(a){var b,d,f,e;a=arguments[0]=c.event.fix(a||A.event);a.currentTarget=this;b=a.type.indexOf(".")<0&&!a.exclusive; +if(!b){d=a.type.split(".");a.type=d.shift();f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)")}e=c.data(this,"events");d=e[a.type];if(e&&d){d=d.slice(0);e=0;for(var j=d.length;e-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d},fa=function(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Fa(d);if(a.type!=="focusout"||d.type!=="radio")c.data(d,"_change_data", +e);if(!(f===w||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}};c.event.special.change={filters:{focusout:fa,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return fa.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return fa.call(this,a)},beforeactivate:function(a){a=a.target;c.data(a, +"_change_data",Fa(a))}},setup:function(){if(this.type==="file")return false;for(var a in ea)c.event.add(this,a+".specialChange",ea[a]);return da.test(this.nodeName)},teardown:function(){c.event.remove(this,".specialChange");return da.test(this.nodeName)}};ea=c.event.special.change.filters}s.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this,f)}c.event.special[b]={setup:function(){this.addEventListener(a, +d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var j in d)this[b](j,f,d[j],e);return this}if(c.isFunction(f)){e=f;f=w}var i=b==="one"?c.proxy(e,function(k){c(this).unbind(k,i);return e.apply(this,arguments)}):e;if(d==="unload"&&b!=="one")this.one(d,f,e);else{j=0;for(var o=this.length;j0){y=t;break}}t=t[g]}m[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g, +e=0,j=Object.prototype.toString,i=false,o=true;[0,0].sort(function(){o=false;return 0});var k=function(g,h,l,m){l=l||[];var q=h=h||s;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g||typeof g!=="string")return l;for(var p=[],v,t,y,S,H=true,M=x(h),I=g;(f.exec(""),v=f.exec(I))!==null;){I=v[3];p.push(v[1]);if(v[2]){S=v[3];break}}if(p.length>1&&r.exec(g))if(p.length===2&&n.relative[p[0]])t=ga(p[0]+p[1],h);else for(t=n.relative[p[0]]?[h]:k(p.shift(),h);p.length;){g=p.shift();if(n.relative[g])g+=p.shift(); +t=ga(g,t)}else{if(!m&&p.length>1&&h.nodeType===9&&!M&&n.match.ID.test(p[0])&&!n.match.ID.test(p[p.length-1])){v=k.find(p.shift(),h,M);h=v.expr?k.filter(v.expr,v.set)[0]:v.set[0]}if(h){v=m?{expr:p.pop(),set:z(m)}:k.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=v.expr?k.filter(v.expr,v.set):v.set;if(p.length>0)y=z(t);else H=false;for(;p.length;){var D=p.pop();v=D;if(n.relative[D])v=p.pop();else D="";if(v==null)v=h;n.relative[D](y,v,M)}}else y=[]}y||(y=t);y||k.error(D|| +g);if(j.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))l.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&&y[g].nodeType===1&&l.push(t[g]);else l.push.apply(l,y);else z(y,l);if(S){k(S,q,l,m);k.uniqueSort(l)}return l};k.uniqueSort=function(g){if(B){i=o;g.sort(B);if(i)for(var h=1;h":function(g,h){var l=typeof h==="string";if(l&&!/\W/.test(h)){h=h.toLowerCase();for(var m=0,q=g.length;m=0))l||m.push(v);else if(l)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()}, +CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&&"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,l,m,q,p){h=g[1].replace(/\\/g,"");if(!p&&n.attrMap[h])g[1]=n.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,l,m,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=k(g[3],null,null,h);else{g=k.filter(g[3],h,l,true^q);l||m.push.apply(m, +g);return false}else if(n.match.POS.test(g[0])||n.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true);return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,l){return!!k(l[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)}, +text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"===g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}}, +setFilters:{first:function(g,h){return h===0},last:function(g,h,l,m){return h===m.length-1},even:function(g,h){return h%2===0},odd:function(g,h){return h%2===1},lt:function(g,h,l){return hl[3]-0},nth:function(g,h,l){return l[3]-0===h},eq:function(g,h,l){return l[3]-0===h}},filter:{PSEUDO:function(g,h,l,m){var q=h[1],p=n.filters[q];if(p)return p(g,l,h,m);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h= +h[3];l=0;for(m=h.length;l=0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var l=h[1];g=n.attrHandle[l]?n.attrHandle[l](g):g[l]!=null?g[l]:g.getAttribute(l);l=g+"";var m=h[2];h=h[4];return g==null?m==="!=":m=== +"="?l===h:m==="*="?l.indexOf(h)>=0:m==="~="?(" "+l+" ").indexOf(h)>=0:!h?l&&g!==false:m==="!="?l!==h:m==="^="?l.indexOf(h)===0:m==="$="?l.substr(l.length-h.length)===h:m==="|="?l===h||l.substr(0,h.length+1)===h+"-":false},POS:function(g,h,l,m){var q=n.setFilters[h[2]];if(q)return q(g,l,h,m)}}},r=n.match.POS;for(var u in n.match){n.match[u]=new RegExp(n.match[u].source+/(?![^\[]*\])(?![^\(]*\))/.source);n.leftMatch[u]=new RegExp(/(^(?:.|\r|\n)*?)/.source+n.match[u].source.replace(/\\(\d+)/g,function(g, +h){return"\\"+(h-0+1)}))}var z=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g};try{Array.prototype.slice.call(s.documentElement.childNodes,0)}catch(C){z=function(g,h){h=h||[];if(j.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var l=0,m=g.length;l";var l=s.documentElement;l.insertBefore(g,l.firstChild);if(s.getElementById(h)){n.find.ID=function(m,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(m[1]))?q.id===m[1]||typeof q.getAttributeNode!=="undefined"&& +q.getAttributeNode("id").nodeValue===m[1]?[q]:w:[]};n.filter.ID=function(m,q){var p=typeof m.getAttributeNode!=="undefined"&&m.getAttributeNode("id");return m.nodeType===1&&p&&p.nodeValue===q}}l.removeChild(g);l=g=null})();(function(){var g=s.createElement("div");g.appendChild(s.createComment(""));if(g.getElementsByTagName("*").length>0)n.find.TAG=function(h,l){l=l.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var m=0;l[m];m++)l[m].nodeType===1&&h.push(l[m]);l=h}return l};g.innerHTML=""; +if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")n.attrHandle.href=function(h){return h.getAttribute("href",2)};g=null})();s.querySelectorAll&&function(){var g=k,h=s.createElement("div");h.innerHTML="

";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){k=function(m,q,p,v){q=q||s;if(!v&&q.nodeType===9&&!x(q))try{return z(q.querySelectorAll(m),p)}catch(t){}return g(m,q,p,v)};for(var l in g)k[l]=g[l];h=null}}(); +(function(){var g=s.createElement("div");g.innerHTML="
";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length===0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){n.order.splice(1,0,"CLASS");n.find.CLASS=function(h,l,m){if(typeof l.getElementsByClassName!=="undefined"&&!m)return l.getElementsByClassName(h[1])};g=null}}})();var E=s.compareDocumentPosition?function(g,h){return!!(g.compareDocumentPosition(h)&16)}: +function(g,h){return g!==h&&(g.contains?g.contains(h):true)},x=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},ga=function(g,h){var l=[],m="",q;for(h=h.nodeType?[h]:h;q=n.match.PSEUDO.exec(g);){m+=q[0];g=g.replace(n.match.PSEUDO,"")}g=n.relative[g]?g+"*":g;q=0;for(var p=h.length;q=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f0)for(var j=d;j0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,j= +{},i;if(f&&a.length){e=0;for(var o=a.length;e-1:c(f).is(e)){d.push({selector:i,elem:f});delete j[i]}}f=f.parentNode}}return d}var k=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(n,r){for(;r&&r.ownerDocument&&r!==b;){if(k?k.index(r)>-1:c(r).is(a))return r;r=r.parentNode}return null})},index:function(a){if(!a||typeof a=== +"string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(),a);return this.pushStack(qa(a[0])||qa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode", +d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")},nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")? +a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);eb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e):e;if((this.length>1||gb.test(f))&&fb.test(a))e=e.reverse();return this.pushStack(e,a,R.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===w||a.nodeType!==1||!c(a).is(d));){a.nodeType=== +1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!==b&&d.push(a);return d}});var Ja=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ka=/(<([\w:]+)[^>]*?)\/>/g,hb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,La=/<([\w:]+)/,ib=/"},F={option:[1,""],legend:[1,"
","
"],thead:[1,"","
"],tr:[2,"","
"],td:[3,"","
"],col:[2,"","
"],area:[1,"",""],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div
","
"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d= +c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==w)return this.empty().append((this[0]&&this[0].ownerDocument||s).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this}, +wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})}, +prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b, +this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,f;(f=this[d])!=null;d++)if(!a||c.filter(a,[f]).length){if(!b&&f.nodeType===1){c.cleanData(f.getElementsByTagName("*"));c.cleanData([f])}f.parentNode&&f.parentNode.removeChild(f)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild); +return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Ja,"").replace(/=([^="'>\s]+\/)>/g,'="$1">').replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){ra(this,b);ra(this.find("*"),b.find("*"))}return b},html:function(a){if(a===w)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Ja, +""):null;else if(typeof a==="string"&&!ta.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(La.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Ka,Ma);try{for(var b=0,d=this.length;b0||e.cacheable||this.length>1?k.cloneNode(true):k)}o.length&&c.each(o,Qa)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);var e=this.length===1&&this[0].parentNode;if(e&&e.nodeType===11&&e.childNodes.length===1&&d.length===1){d[b](this[0]); +return this}else{e=0;for(var j=d.length;e0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),i);f=f.concat(i)}return this.pushStack(f,a,d.selector)}}});c.extend({clean:function(a,b,d,f){b=b||s;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||s;for(var e=[],j=0,i;(i=a[j])!=null;j++){if(typeof i==="number")i+="";if(i){if(typeof i==="string"&&!jb.test(i))i=b.createTextNode(i);else if(typeof i==="string"){i=i.replace(Ka,Ma);var o=(La.exec(i)||["", +""])[1].toLowerCase(),k=F[o]||F._default,n=k[0],r=b.createElement("div");for(r.innerHTML=k[1]+i+k[2];n--;)r=r.lastChild;if(!c.support.tbody){n=ib.test(i);o=o==="table"&&!n?r.firstChild&&r.firstChild.childNodes:k[1]===""&&!n?r.childNodes:[];for(k=o.length-1;k>=0;--k)c.nodeName(o[k],"tbody")&&!o[k].childNodes.length&&o[k].parentNode.removeChild(o[k])}!c.support.leadingWhitespace&&V.test(i)&&r.insertBefore(b.createTextNode(V.exec(i)[0]),r.firstChild);i=r.childNodes}if(i.nodeType)e.push(i);else e= +c.merge(e,i)}}if(d)for(j=0;e[j];j++)if(f&&c.nodeName(e[j],"script")&&(!e[j].type||e[j].type.toLowerCase()==="text/javascript"))f.push(e[j].parentNode?e[j].parentNode.removeChild(e[j]):e[j]);else{e[j].nodeType===1&&e.splice.apply(e,[j+1,0].concat(c.makeArray(e[j].getElementsByTagName("script"))));d.appendChild(e[j])}return e},cleanData:function(a){for(var b,d,f=c.cache,e=c.event.special,j=c.support.deleteExpando,i=0,o;(o=a[i])!=null;i++)if(d=o[c.expando]){b=f[d];if(b.events)for(var k in b.events)e[k]? +c.event.remove(o,k):Ca(o,k,b.handle);if(j)delete o[c.expando];else o.removeAttribute&&o.removeAttribute(c.expando);delete f[d]}}});var kb=/z-?index|font-?weight|opacity|zoom|line-?height/i,Na=/alpha\([^)]*\)/,Oa=/opacity=([^)]*)/,ha=/float/i,ia=/-([a-z])/ig,lb=/([A-Z])/g,mb=/^-?\d+(?:px)?$/i,nb=/^-?\d/,ob={position:"absolute",visibility:"hidden",display:"block"},pb=["Left","Right"],qb=["Top","Bottom"],rb=s.defaultView&&s.defaultView.getComputedStyle,Pa=c.support.cssFloat?"cssFloat":"styleFloat",ja= +function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===w)return c.curCSS(d,f);if(typeof e==="number"&&!kb.test(f))e+="px";c.style(d,f,e)})};c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return w;if((b==="width"||b==="height")&&parseFloat(d)<0)d=w;var f=a.style||a,e=d!==w;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter= +Na.test(a)?a.replace(Na,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Oa.exec(f.filter)[1])/100+"":""}if(ha.test(b))b=Pa;b=b.replace(ia,ja);if(e)f[b]=d;return f[b]},css:function(a,b,d,f){if(b==="width"||b==="height"){var e,j=b==="width"?pb:qb;function i(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(j,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a, +"border"+this+"Width",true))||0})}a.offsetWidth!==0?i():c.swap(a,ob,i);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&&a.currentStyle){f=Oa.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ha.test(b))b=Pa;if(!d&&e&&e[b])f=e[b];else if(rb){if(ha.test(b))b="float";b=b.replace(lb,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f= +a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ia,ja);f=a.currentStyle[b]||a.currentStyle[d];if(!mb.test(f)&&nb.test(f)){b=e.left;var j=a.runtimeStyle.left;a.runtimeStyle.left=a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=j}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b= +a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var sb=J(),tb=//gi,ub=/select|textarea/i,vb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ka=/\?/,wb=/(\?|&)_=.*?(&|$)/,xb=/^(\w+:)?\/\/([^\/?#]+)/,yb=/%20/g,zb=c.fn.load;c.fn.extend({load:function(a,b,d){if(typeof a!== +"string")return zb.call(this,a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b=c.param(b,c.ajaxSettings.traditional);f="POST"}var j=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(i,o){if(o==="success"||o==="notmodified")j.html(e?c("
").append(i.responseText.replace(tb,"")).find(e):i.responseText);d&&j.each(d,[i.responseText,o,i])}});return this}, +serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||ub.test(this.nodeName)||vb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "), +function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a,b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href, +global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:A.XMLHttpRequest&&(A.location.protocol!=="file:"||!A.ActiveXObject)?function(){return new A.XMLHttpRequest}:function(){try{return new A.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&& +e.success.call(k,o,i,x);e.global&&f("ajaxSuccess",[x,e])}function d(){e.complete&&e.complete.call(k,x,i);e.global&&f("ajaxComplete",[x,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")}function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),j,i,o,k=a&&a.context||e,n=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(n==="GET")N.test(e.url)||(e.url+=(ka.test(e.url)? +"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)||N.test(e.url))){j=e.jsonpCallback||"jsonp"+sb++;if(e.data)e.data=(e.data+"").replace(N,"="+j+"$1");e.url=e.url.replace(N,"="+j+"$1");e.dataType="script";A[j]=A[j]||function(q){o=q;b();d();A[j]=w;try{delete A[j]}catch(p){}z&&z.removeChild(C)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache=== +false&&n==="GET"){var r=J(),u=e.url.replace(wb,"$1_="+r+"$2");e.url=u+(u===e.url?(ka.test(e.url)?"&":"?")+"_="+r:"")}if(e.data&&n==="GET")e.url+=(ka.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&&c.event.trigger("ajaxStart");r=(r=xb.exec(e.url))&&(r[1]&&r[1]!==location.protocol||r[2]!==location.host);if(e.dataType==="script"&&n==="GET"&&r){var z=s.getElementsByTagName("head")[0]||s.documentElement,C=s.createElement("script");C.src=e.url;if(e.scriptCharset)C.charset=e.scriptCharset;if(!j){var B= +false;C.onload=C.onreadystatechange=function(){if(!B&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){B=true;b();d();C.onload=C.onreadystatechange=null;z&&C.parentNode&&z.removeChild(C)}}}z.insertBefore(C,z.firstChild);return w}var E=false,x=e.xhr();if(x){e.username?x.open(n,e.url,e.async,e.username,e.password):x.open(n,e.url,e.async);try{if(e.data||a&&a.contentType)x.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&x.setRequestHeader("If-Modified-Since", +c.lastModified[e.url]);c.etag[e.url]&&x.setRequestHeader("If-None-Match",c.etag[e.url])}r||x.setRequestHeader("X-Requested-With","XMLHttpRequest");x.setRequestHeader("Accept",e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(ga){}if(e.beforeSend&&e.beforeSend.call(k,x,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");x.abort();return false}e.global&&f("ajaxSend",[x,e]);var g=x.onreadystatechange=function(q){if(!x||x.readyState===0||q==="abort"){E|| +d();E=true;if(x)x.onreadystatechange=c.noop}else if(!E&&x&&(x.readyState===4||q==="timeout")){E=true;x.onreadystatechange=c.noop;i=q==="timeout"?"timeout":!c.httpSuccess(x)?"error":e.ifModified&&c.httpNotModified(x,e.url)?"notmodified":"success";var p;if(i==="success")try{o=c.httpData(x,e.dataType,e)}catch(v){i="parsererror";p=v}if(i==="success"||i==="notmodified")j||b();else c.handleError(e,x,i,p);d();q==="timeout"&&x.abort();if(e.async)x=null}};try{var h=x.abort;x.abort=function(){x&&h.call(x); +g("abort")}}catch(l){}e.async&&e.timeout>0&&setTimeout(function(){x&&!E&&g("timeout")},e.timeout);try{x.send(n==="POST"||n==="PUT"||n==="DELETE"?e.data:null)}catch(m){c.handleError(e,x,null,m);d()}e.async||g();return x}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status=== +1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]=f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b=== +"json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(i,o){if(c.isArray(o))c.each(o,function(k,n){b||/\[\]$/.test(i)?f(i,n):d(i+"["+(typeof n==="object"||c.isArray(n)?k:"")+"]",n)});else!b&&o!=null&&typeof o==="object"?c.each(o,function(k,n){d(i+"["+k+"]",n)}):f(i,o)}function f(i,o){o=c.isFunction(o)?o():o;e[e.length]=encodeURIComponent(i)+"="+encodeURIComponent(o)}var e=[];if(b===w)b=c.ajaxSettings.traditional; +if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var j in a)d(j,a[j]);return e.join("&").replace(yb,"+")}});var la={},Ab=/toggle|show|hide/,Bb=/^([+-]=)?([\d+-.]+)(.*)$/,W,va=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove();la[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration=== +"number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a,b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]|| +c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(j){return e.step(j)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start; +this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now= +this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem, +e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos=c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b
"; +a.insertBefore(b,a.firstChild);d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==j;a.removeChild(b); +c.offset.initialize=c.noop},bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),j=parseInt(c.curCSS(a,"top",true),10)||0,i=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a, +d,e);d={top:b.top-e.top+j,left:b.left-e.left+i};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top- +f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a=this.offsetParent||s.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],j;if(!e)return null;if(f!==w)return this.each(function(){if(j=wa(this))j.scrollTo(!a?f:c(j).scrollLeft(),a?f:c(j).scrollTop());else this[d]=f});else return(j=wa(e))?"pageXOffset"in j?j[a?"pageYOffset": +"pageXOffset"]:c.support.boxModel&&j.document.documentElement[d]||j.document.body[d]:e[d]}});c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(j){var i=c(this);i[d](f.call(this,j,i[d]()))});return"scrollTo"in +e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]||e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===w?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});A.jQuery=A.$=c})(window); diff --git a/docs/_build/html/_static/minus.png b/docs/_build/html/_static/minus.png new file mode 100644 index 0000000..da1c562 Binary files /dev/null and b/docs/_build/html/_static/minus.png differ diff --git a/docs/_build/html/_static/plus.png b/docs/_build/html/_static/plus.png new file mode 100644 index 0000000..b3cb374 Binary files /dev/null and b/docs/_build/html/_static/plus.png differ diff --git a/docs/_build/html/_static/pygments.css b/docs/_build/html/_static/pygments.css new file mode 100644 index 0000000..ee96fae --- /dev/null +++ b/docs/_build/html/_static/pygments.css @@ -0,0 +1,70 @@ +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #8f5902; font-style: italic } /* Comment */ +.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */ +.highlight .g { color: #000000 } /* Generic */ +.highlight .k { color: #004461; font-weight: bold } /* Keyword */ +.highlight .l { color: #000000 } /* Literal */ +.highlight .n { color: #000000 } /* Name */ +.highlight .o { color: #582800 } /* Operator */ +.highlight .x { color: #000000 } /* Other */ +.highlight .p { color: #000000; font-weight: bold } /* Punctuation */ +.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #8f5902 } /* Comment.Preproc */ +.highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #a40000 } /* Generic.Deleted */ +.highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #ef2929 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #808080 } /* Generic.Output */ +.highlight .gp { color: #745334 } /* Generic.Prompt */ +.highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */ +.highlight .kc { color: #004461; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #004461; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #004461; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #004461; font-weight: bold } /* Keyword.Pseudo */ +.highlight .kr { color: #004461; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #004461; font-weight: bold } /* Keyword.Type */ +.highlight .ld { color: #000000 } /* Literal.Date */ +.highlight .m { color: #990000 } /* Literal.Number */ +.highlight .s { color: #4e9a06 } /* Literal.String */ +.highlight .na { color: #c4a000 } /* Name.Attribute */ +.highlight .nb { color: #004461 } /* Name.Builtin */ +.highlight .nc { color: #000000 } /* Name.Class */ +.highlight .no { color: #000000 } /* Name.Constant */ +.highlight .nd { color: #808080 } /* Name.Decorator */ +.highlight .ni { color: #ce5c00 } /* Name.Entity */ +.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #000000 } /* Name.Function */ +.highlight .nl { color: #f57900 } /* Name.Label */ +.highlight .nn { color: #000000 } /* Name.Namespace */ +.highlight .nx { color: #000000 } /* Name.Other */ +.highlight .py { color: #000000 } /* Name.Property */ +.highlight .nt { color: #004461; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #000000 } /* Name.Variable */ +.highlight .ow { color: #004461; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #f8f8f8; text-decoration: underline } /* Text.Whitespace */ +.highlight .mf { color: #990000 } /* Literal.Number.Float */ +.highlight .mh { color: #990000 } /* Literal.Number.Hex */ +.highlight .mi { color: #990000 } /* Literal.Number.Integer */ +.highlight .mo { color: #990000 } /* Literal.Number.Oct */ +.highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */ +.highlight .sc { color: #4e9a06 } /* Literal.String.Char */ +.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4e9a06 } /* Literal.String.Double */ +.highlight .se { color: #4e9a06 } /* Literal.String.Escape */ +.highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */ +.highlight .si { color: #4e9a06 } /* Literal.String.Interpol */ +.highlight .sx { color: #4e9a06 } /* Literal.String.Other */ +.highlight .sr { color: #4e9a06 } /* Literal.String.Regex */ +.highlight .s1 { color: #4e9a06 } /* Literal.String.Single */ +.highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */ +.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */ +.highlight .vc { color: #000000 } /* Name.Variable.Class */ +.highlight .vg { color: #000000 } /* Name.Variable.Global */ +.highlight .vi { color: #000000 } /* Name.Variable.Instance */ +.highlight .il { color: #990000 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/docs/_build/html/_static/searchtools.js b/docs/_build/html/_static/searchtools.js new file mode 100644 index 0000000..663be4c --- /dev/null +++ b/docs/_build/html/_static/searchtools.js @@ -0,0 +1,560 @@ +/* + * searchtools.js_t + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilties for the full-text search. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurance, the + * latter for highlighting it. + */ + +jQuery.makeSearchSummary = function(text, keywords, hlwords) { + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('
').text(excerpt); + $.each(hlwords, function() { + rv = rv.highlightText(this, 'highlighted'); + }); + return rv; +} + + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + loadIndex : function(url) { + $.ajax({type: "GET", url: url, data: null, success: null, + dataType: "script", cache: true}); + }, + + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (var i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('

' + _('Searching') + '

').appendTo(this.out); + this.dots = $('').appendTo(this.title); + this.status = $('

').appendTo(this.out); + this.output = $('
    ').appendTo(this.out); + + $('#search-progress').text(_('Preparing search...')); + this.startPulse(); + + // index already loaded, the browser was quick! + if (this.hasIndex()) + this.query(query); + else + this.deferQuery(query); + }, + + query : function(query) { + var stopwords = ["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"]; + + // Stem the searchterms and add them to the correct list + var stemmer = new Stemmer(); + var searchterms = []; + var excluded = []; + var hlterms = []; + var tmp = query.split(/\s+/); + var objectterms = []; + for (var i = 0; i < tmp.length; i++) { + if (tmp[i] != "") { + objectterms.push(tmp[i].toLowerCase()); + } + + if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) || + tmp[i] == "") { + // skip this "word" + continue; + } + // stem the word + var word = stemmer.stemWord(tmp[i]).toLowerCase(); + // select the correct list + if (word[0] == '-') { + var toAppend = excluded; + word = word.substr(1); + } + else { + var toAppend = searchterms; + hlterms.push(tmp[i].toLowerCase()); + } + // only add if not already in the list + if (!$.contains(toAppend, word)) + toAppend.push(word); + }; + var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); + + // console.debug('SEARCH: searching for:'); + // console.info('required: ', searchterms); + // console.info('excluded: ', excluded); + + // prepare search + var filenames = this._index.filenames; + var titles = this._index.titles; + var terms = this._index.terms; + var fileMap = {}; + var files = null; + // different result priorities + var importantResults = []; + var objectResults = []; + var regularResults = []; + var unimportantResults = []; + $('#search-progress').empty(); + + // lookup as object + for (var i = 0; i < objectterms.length; i++) { + var others = [].concat(objectterms.slice(0,i), + objectterms.slice(i+1, objectterms.length)) + var results = this.performObjectSearch(objectterms[i], others); + // Assume first word is most likely to be the object, + // other words more likely to be in description. + // Therefore put matches for earlier words first. + // (Results are eventually used in reverse order). + objectResults = results[0].concat(objectResults); + importantResults = results[1].concat(importantResults); + unimportantResults = results[2].concat(unimportantResults); + } + + // perform the search on the required terms + for (var i = 0; i < searchterms.length; i++) { + var word = searchterms[i]; + // no match but word was a required one + if ((files = terms[word]) == null) + break; + if (files.length == undefined) { + files = [files]; + } + // create the mapping + for (var j = 0; j < files.length; j++) { + var file = files[j]; + if (file in fileMap) + fileMap[file].push(word); + else + fileMap[file] = [word]; + } + } + + // now check if the files don't contain excluded terms + for (var file in fileMap) { + var valid = true; + + // check if all requirements are matched + if (fileMap[file].length != searchterms.length) + continue; + + // ensure that none of the excluded terms is in the + // search result. + for (var i = 0; i < excluded.length; i++) { + if (terms[excluded[i]] == file || + $.contains(terms[excluded[i]] || [], file)) { + valid = false; + break; + } + } + + // if we have still a valid result we can add it + // to the result list + if (valid) + regularResults.push([filenames[file], titles[file], '', null]); + } + + // delete unused variables in order to not waste + // memory until list is retrieved completely + delete filenames, titles, terms; + + // now sort the regular results descending by title + regularResults.sort(function(a, b) { + var left = a[1].toLowerCase(); + var right = b[1].toLowerCase(); + return (left > right) ? -1 : ((left < right) ? 1 : 0); + }); + + // combine all results + var results = unimportantResults.concat(regularResults) + .concat(objectResults).concat(importantResults); + + // print the results + var resultCount = results.length; + function displayNextItem() { + // results left, load the summary and display it + if (results.length) { + var item = results.pop(); + var listItem = $('
  • '); + if (DOCUMENTATION_OPTIONS.FILE_SUFFIX == '') { + // dirhtml builder + var dirname = item[0] + '/'; + if (dirname.match(/\/index\/$/)) { + dirname = dirname.substring(0, dirname.length-6); + } else if (dirname == 'index/') { + dirname = ''; + } + listItem.append($('').attr('href', + DOCUMENTATION_OPTIONS.URL_ROOT + dirname + + highlightstring + item[2]).html(item[1])); + } else { + // normal html builders + listItem.append($('').attr('href', + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX + + highlightstring + item[2]).html(item[1])); + } + if (item[3]) { + listItem.append($(' (' + item[3] + ')')); + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { + $.get(DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' + + item[0] + '.txt', function(data) { + if (data != '') { + listItem.append($.makeSearchSummary(data, searchterms, hlterms)); + Search.output.append(listItem); + } + listItem.slideDown(5, function() { + displayNextItem(); + }); + }, "text"); + } else { + // no source available, just display title + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } + } + // search finished, update title and status message + else { + Search.stopPulse(); + Search.title.text(_('Search Results')); + if (!resultCount) + Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); + else + Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); + Search.status.fadeIn(500); + } + } + displayNextItem(); + }, + + performObjectSearch : function(object, otherterms) { + var filenames = this._index.filenames; + var objects = this._index.objects; + var objnames = this._index.objnames; + var titles = this._index.titles; + + var importantResults = []; + var objectResults = []; + var unimportantResults = []; + + for (var prefix in objects) { + for (var name in objects[prefix]) { + var fullname = (prefix ? prefix + '.' : '') + name; + if (fullname.toLowerCase().indexOf(object) > -1) { + var match = objects[prefix][name]; + var objname = objnames[match[1]][2]; + var title = titles[match[0]]; + // If more than one term searched for, we require other words to be + // found in the name/title/description + if (otherterms.length > 0) { + var haystack = (prefix + ' ' + name + ' ' + + objname + ' ' + title).toLowerCase(); + var allfound = true; + for (var i = 0; i < otherterms.length; i++) { + if (haystack.indexOf(otherterms[i]) == -1) { + allfound = false; + break; + } + } + if (!allfound) { + continue; + } + } + var descr = objname + _(', in ') + title; + anchor = match[3]; + if (anchor == '') + anchor = fullname; + else if (anchor == '-') + anchor = objnames[match[1]][1] + '-' + fullname; + result = [filenames[match[0]], fullname, '#'+anchor, descr]; + switch (match[2]) { + case 1: objectResults.push(result); break; + case 0: importantResults.push(result); break; + case 2: unimportantResults.push(result); break; + } + } + } + } + + // sort results descending + objectResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + importantResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + unimportantResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + return [importantResults, objectResults, unimportantResults] + } +} + +$(document).ready(function() { + Search.init(); +}); \ No newline at end of file diff --git a/docs/_build/html/_static/small_flask.css b/docs/_build/html/_static/small_flask.css new file mode 100644 index 0000000..1c6df30 --- /dev/null +++ b/docs/_build/html/_static/small_flask.css @@ -0,0 +1,70 @@ +/* + * small_flask.css_t + * ~~~~~~~~~~~~~~~~~ + * + * :copyright: Copyright 2010 by Armin Ronacher. + * :license: Flask Design License, see LICENSE for details. + */ + +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; +} diff --git a/docs/_build/html/_static/test b/docs/_build/html/_static/test new file mode 100644 index 0000000..e69de29 diff --git a/docs/_build/html/_static/underscore.js b/docs/_build/html/_static/underscore.js new file mode 100644 index 0000000..5d89914 --- /dev/null +++ b/docs/_build/html/_static/underscore.js @@ -0,0 +1,23 @@ +// Underscore.js 0.5.5 +// (c) 2009 Jeremy Ashkenas, DocumentCloud Inc. +// Underscore is freely distributable under the terms of the MIT license. +// Portions of Underscore are inspired by or borrowed from Prototype.js, +// Oliver Steele's Functional, and John Resig's Micro-Templating. +// For all details and documentation: +// http://documentcloud.github.com/underscore/ +(function(){var j=this,n=j._,i=function(a){this._wrapped=a},m=typeof StopIteration!=="undefined"?StopIteration:"__break__",b=j._=function(a){return new i(a)};if(typeof exports!=="undefined")exports._=b;var k=Array.prototype.slice,o=Array.prototype.unshift,p=Object.prototype.toString,q=Object.prototype.hasOwnProperty,r=Object.prototype.propertyIsEnumerable;b.VERSION="0.5.5";b.each=function(a,c,d){try{if(a.forEach)a.forEach(c,d);else if(b.isArray(a)||b.isArguments(a))for(var e=0,f=a.length;e=e.computed&&(e={value:f,computed:g})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);var e={computed:Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;gf?1:0}),"value")};b.sortedIndex=function(a,c,d){d=d||b.identity;for(var e=0,f=a.length;e>1;d(a[g])=0})})};b.zip=function(){for(var a=b.toArray(arguments),c=b.max(b.pluck(a,"length")),d=new Array(c),e=0;e0?f-c:c-f)>=0)return e;e[g++]=f}};b.bind=function(a,c){var d=b.rest(arguments,2);return function(){return a.apply(c||j,d.concat(b.toArray(arguments)))}};b.bindAll=function(a){var c=b.rest(arguments);if(c.length==0)c=b.functions(a);b.each(c,function(d){a[d]=b.bind(a[d],a)}); +return a};b.delay=function(a,c){var d=b.rest(arguments,2);return setTimeout(function(){return a.apply(a,d)},c)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(b.rest(arguments)))};b.wrap=function(a,c){return function(){var d=[a].concat(b.toArray(arguments));return c.apply(c,d)}};b.compose=function(){var a=b.toArray(arguments);return function(){for(var c=b.toArray(arguments),d=a.length-1;d>=0;d--)c=[a[d].apply(this,c)];return c[0]}};b.keys=function(a){if(b.isArray(a))return b.range(0,a.length); +var c=[];for(var d in a)q.call(a,d)&&c.push(d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=function(a){return b.select(b.keys(a),function(c){return b.isFunction(a[c])}).sort()};b.extend=function(a,c){for(var d in c)a[d]=c[d];return a};b.clone=function(a){if(b.isArray(a))return a.slice(0);return b.extend({},a)};b.tap=function(a,c){c(a);return a};b.isEqual=function(a,c){if(a===c)return true;var d=typeof a;if(d!=typeof c)return false;if(a==c)return true;if(!a&&c||a&&!c)return false; +if(a.isEqual)return a.isEqual(c);if(b.isDate(a)&&b.isDate(c))return a.getTime()===c.getTime();if(b.isNaN(a)&&b.isNaN(c))return true;if(b.isRegExp(a)&&b.isRegExp(c))return a.source===c.source&&a.global===c.global&&a.ignoreCase===c.ignoreCase&&a.multiline===c.multiline;if(d!=="object")return false;if(a.length&&a.length!==c.length)return false;d=b.keys(a);var e=b.keys(c);if(d.length!=e.length)return false;for(var f in a)if(!b.isEqual(a[f],c[f]))return false;return true};b.isEmpty=function(a){return b.keys(a).length== +0};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=function(a){return!!(a&&a.concat&&a.unshift)};b.isArguments=function(a){return a&&b.isNumber(a.length)&&!b.isArray(a)&&!r.call(a,"length")};b.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};b.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};b.isNumber=function(a){return p.call(a)==="[object Number]"};b.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};b.isRegExp=function(a){return!!(a&& +a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};b.isNaN=function(a){return b.isNumber(a)&&isNaN(a)};b.isNull=function(a){return a===null};b.isUndefined=function(a){return typeof a=="undefined"};b.noConflict=function(){j._=n;return this};b.identity=function(a){return a};b.breakLoop=function(){throw m;};var s=0;b.uniqueId=function(a){var c=s++;return a?a+c:c};b.template=function(a,c){a=new Function("obj","var p=[],print=function(){p.push.apply(p,arguments);};with(obj){p.push('"+a.replace(/[\r\t\n]/g, +" ").replace(/'(?=[^%]*%>)/g,"\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g,"',$1,'").split("<%").join("');").split("%>").join("p.push('")+"');}return p.join('');");return c?a(c):a};b.forEach=b.each;b.foldl=b.inject=b.reduce;b.foldr=b.reduceRight;b.filter=b.select;b.every=b.all;b.some=b.any;b.head=b.first;b.tail=b.rest;b.methods=b.functions;var l=function(a,c){return c?b(a).chain():a};b.each(b.functions(b),function(a){var c=b[a];i.prototype[a]=function(){var d=b.toArray(arguments); +o.call(d,this._wrapped);return l(c.apply(b,d),this._chain)}});b.each(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){c.apply(this._wrapped,arguments);return l(this._wrapped,this._chain)}});b.each(["concat","join","slice"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){return l(c.apply(this._wrapped,arguments),this._chain)}});i.prototype.chain=function(){this._chain=true;return this};i.prototype.value=function(){return this._wrapped}})(); diff --git a/docs/_build/html/_static/up-pressed.png b/docs/_build/html/_static/up-pressed.png new file mode 100644 index 0000000..8bd587a Binary files /dev/null and b/docs/_build/html/_static/up-pressed.png differ diff --git a/docs/_build/html/_static/up.png b/docs/_build/html/_static/up.png new file mode 100644 index 0000000..b946256 Binary files /dev/null and b/docs/_build/html/_static/up.png differ diff --git a/docs/_build/html/_static/websupport.js b/docs/_build/html/_static/websupport.js new file mode 100644 index 0000000..e9bd1b8 --- /dev/null +++ b/docs/_build/html/_static/websupport.js @@ -0,0 +1,808 @@ +/* + * websupport.js + * ~~~~~~~~~~~~~ + * + * sphinx.websupport utilties for all documentation. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +(function($) { + $.fn.autogrow = function() { + return this.each(function() { + var textarea = this; + + $.fn.autogrow.resize(textarea); + + $(textarea) + .focus(function() { + textarea.interval = setInterval(function() { + $.fn.autogrow.resize(textarea); + }, 500); + }) + .blur(function() { + clearInterval(textarea.interval); + }); + }); + }; + + $.fn.autogrow.resize = function(textarea) { + var lineHeight = parseInt($(textarea).css('line-height'), 10); + var lines = textarea.value.split('\n'); + var columns = textarea.cols; + var lineCount = 0; + $.each(lines, function() { + lineCount += Math.ceil(this.length / columns) || 1; + }); + var height = lineHeight * (lineCount + 1); + $(textarea).css('height', height); + }; +})(jQuery); + +(function($) { + var comp, by; + + function init() { + initEvents(); + initComparator(); + } + + function initEvents() { + $('a.comment-close').live("click", function(event) { + event.preventDefault(); + hide($(this).attr('id').substring(2)); + }); + $('a.vote').live("click", function(event) { + event.preventDefault(); + handleVote($(this)); + }); + $('a.reply').live("click", function(event) { + event.preventDefault(); + openReply($(this).attr('id').substring(2)); + }); + $('a.close-reply').live("click", function(event) { + event.preventDefault(); + closeReply($(this).attr('id').substring(2)); + }); + $('a.sort-option').live("click", function(event) { + event.preventDefault(); + handleReSort($(this)); + }); + $('a.show-proposal').live("click", function(event) { + event.preventDefault(); + showProposal($(this).attr('id').substring(2)); + }); + $('a.hide-proposal').live("click", function(event) { + event.preventDefault(); + hideProposal($(this).attr('id').substring(2)); + }); + $('a.show-propose-change').live("click", function(event) { + event.preventDefault(); + showProposeChange($(this).attr('id').substring(2)); + }); + $('a.hide-propose-change').live("click", function(event) { + event.preventDefault(); + hideProposeChange($(this).attr('id').substring(2)); + }); + $('a.accept-comment').live("click", function(event) { + event.preventDefault(); + acceptComment($(this).attr('id').substring(2)); + }); + $('a.delete-comment').live("click", function(event) { + event.preventDefault(); + deleteComment($(this).attr('id').substring(2)); + }); + $('a.comment-markup').live("click", function(event) { + event.preventDefault(); + toggleCommentMarkupBox($(this).attr('id').substring(2)); + }); + } + + /** + * Set comp, which is a comparator function used for sorting and + * inserting comments into the list. + */ + function setComparator() { + // If the first three letters are "asc", sort in ascending order + // and remove the prefix. + if (by.substring(0,3) == 'asc') { + var i = by.substring(3); + comp = function(a, b) { return a[i] - b[i]; }; + } else { + // Otherwise sort in descending order. + comp = function(a, b) { return b[by] - a[by]; }; + } + + // Reset link styles and format the selected sort option. + $('a.sel').attr('href', '#').removeClass('sel'); + $('a.by' + by).removeAttr('href').addClass('sel'); + } + + /** + * Create a comp function. If the user has preferences stored in + * the sortBy cookie, use those, otherwise use the default. + */ + function initComparator() { + by = 'rating'; // Default to sort by rating. + // If the sortBy cookie is set, use that instead. + if (document.cookie.length > 0) { + var start = document.cookie.indexOf('sortBy='); + if (start != -1) { + start = start + 7; + var end = document.cookie.indexOf(";", start); + if (end == -1) { + end = document.cookie.length; + by = unescape(document.cookie.substring(start, end)); + } + } + } + setComparator(); + } + + /** + * Show a comment div. + */ + function show(id) { + $('#ao' + id).hide(); + $('#ah' + id).show(); + var context = $.extend({id: id}, opts); + var popup = $(renderTemplate(popupTemplate, context)).hide(); + popup.find('textarea[name="proposal"]').hide(); + popup.find('a.by' + by).addClass('sel'); + var form = popup.find('#cf' + id); + form.submit(function(event) { + event.preventDefault(); + addComment(form); + }); + $('#s' + id).after(popup); + popup.slideDown('fast', function() { + getComments(id); + }); + } + + /** + * Hide a comment div. + */ + function hide(id) { + $('#ah' + id).hide(); + $('#ao' + id).show(); + var div = $('#sc' + id); + div.slideUp('fast', function() { + div.remove(); + }); + } + + /** + * Perform an ajax request to get comments for a node + * and insert the comments into the comments tree. + */ + function getComments(id) { + $.ajax({ + type: 'GET', + url: opts.getCommentsURL, + data: {node: id}, + success: function(data, textStatus, request) { + var ul = $('#cl' + id); + var speed = 100; + $('#cf' + id) + .find('textarea[name="proposal"]') + .data('source', data.source); + + if (data.comments.length === 0) { + ul.html('
  • No comments yet.
    • '); + ul.data('empty', true); + } else { + // If there are comments, sort them and put them in the list. + var comments = sortComments(data.comments); + speed = data.comments.length * 100; + appendComments(comments, ul); + ul.data('empty', false); + } + $('#cn' + id).slideUp(speed + 200); + ul.slideDown(speed); + }, + error: function(request, textStatus, error) { + showError('Oops, there was a problem retrieving the comments.'); + }, + dataType: 'json' + }); + } + + /** + * Add a comment via ajax and insert the comment into the comment tree. + */ + function addComment(form) { + var node_id = form.find('input[name="node"]').val(); + var parent_id = form.find('input[name="parent"]').val(); + var text = form.find('textarea[name="comment"]').val(); + var proposal = form.find('textarea[name="proposal"]').val(); + + if (text == '') { + showError('Please enter a comment.'); + return; + } + + // Disable the form that is being submitted. + form.find('textarea,input').attr('disabled', 'disabled'); + + // Send the comment to the server. + $.ajax({ + type: "POST", + url: opts.addCommentURL, + dataType: 'json', + data: { + node: node_id, + parent: parent_id, + text: text, + proposal: proposal + }, + success: function(data, textStatus, error) { + // Reset the form. + if (node_id) { + hideProposeChange(node_id); + } + form.find('textarea') + .val('') + .add(form.find('input')) + .removeAttr('disabled'); + var ul = $('#cl' + (node_id || parent_id)); + if (ul.data('empty')) { + $(ul).empty(); + ul.data('empty', false); + } + insertComment(data.comment); + var ao = $('#ao' + node_id); + ao.find('img').attr({'src': opts.commentBrightImage}); + if (node_id) { + // if this was a "root" comment, remove the commenting box + // (the user can get it back by reopening the comment popup) + $('#ca' + node_id).slideUp(); + } + }, + error: function(request, textStatus, error) { + form.find('textarea,input').removeAttr('disabled'); + showError('Oops, there was a problem adding the comment.'); + } + }); + } + + /** + * Recursively append comments to the main comment list and children + * lists, creating the comment tree. + */ + function appendComments(comments, ul) { + $.each(comments, function() { + var div = createCommentDiv(this); + ul.append($(document.createElement('li')).html(div)); + appendComments(this.children, div.find('ul.comment-children')); + // To avoid stagnating data, don't store the comments children in data. + this.children = null; + div.data('comment', this); + }); + } + + /** + * After adding a new comment, it must be inserted in the correct + * location in the comment tree. + */ + function insertComment(comment) { + var div = createCommentDiv(comment); + + // To avoid stagnating data, don't store the comments children in data. + comment.children = null; + div.data('comment', comment); + + var ul = $('#cl' + (comment.node || comment.parent)); + var siblings = getChildren(ul); + + var li = $(document.createElement('li')); + li.hide(); + + // Determine where in the parents children list to insert this comment. + for(i=0; i < siblings.length; i++) { + if (comp(comment, siblings[i]) <= 0) { + $('#cd' + siblings[i].id) + .parent() + .before(li.html(div)); + li.slideDown('fast'); + return; + } + } + + // If we get here, this comment rates lower than all the others, + // or it is the only comment in the list. + ul.append(li.html(div)); + li.slideDown('fast'); + } + + function acceptComment(id) { + $.ajax({ + type: 'POST', + url: opts.acceptCommentURL, + data: {id: id}, + success: function(data, textStatus, request) { + $('#cm' + id).fadeOut('fast'); + $('#cd' + id).removeClass('moderate'); + }, + error: function(request, textStatus, error) { + showError('Oops, there was a problem accepting the comment.'); + } + }); + } + + function deleteComment(id) { + $.ajax({ + type: 'POST', + url: opts.deleteCommentURL, + data: {id: id}, + success: function(data, textStatus, request) { + var div = $('#cd' + id); + if (data == 'delete') { + // Moderator mode: remove the comment and all children immediately + div.slideUp('fast', function() { + div.remove(); + }); + return; + } + // User mode: only mark the comment as deleted + div + .find('span.user-id:first') + .text('[deleted]').end() + .find('div.comment-text:first') + .text('[deleted]').end() + .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id + + ', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id) + .remove(); + var comment = div.data('comment'); + comment.username = '[deleted]'; + comment.text = '[deleted]'; + div.data('comment', comment); + }, + error: function(request, textStatus, error) { + showError('Oops, there was a problem deleting the comment.'); + } + }); + } + + function showProposal(id) { + $('#sp' + id).hide(); + $('#hp' + id).show(); + $('#pr' + id).slideDown('fast'); + } + + function hideProposal(id) { + $('#hp' + id).hide(); + $('#sp' + id).show(); + $('#pr' + id).slideUp('fast'); + } + + function showProposeChange(id) { + $('#pc' + id).hide(); + $('#hc' + id).show(); + var textarea = $('#pt' + id); + textarea.val(textarea.data('source')); + $.fn.autogrow.resize(textarea[0]); + textarea.slideDown('fast'); + } + + function hideProposeChange(id) { + $('#hc' + id).hide(); + $('#pc' + id).show(); + var textarea = $('#pt' + id); + textarea.val('').removeAttr('disabled'); + textarea.slideUp('fast'); + } + + function toggleCommentMarkupBox(id) { + $('#mb' + id).toggle(); + } + + /** Handle when the user clicks on a sort by link. */ + function handleReSort(link) { + var classes = link.attr('class').split(/\s+/); + for (var i=0; iThank you! Your comment will show up ' + + 'once it is has been approved by a moderator.'); + } + // Prettify the comment rating. + comment.pretty_rating = comment.rating + ' point' + + (comment.rating == 1 ? '' : 's'); + // Make a class (for displaying not yet moderated comments differently) + comment.css_class = comment.displayed ? '' : ' moderate'; + // Create a div for this comment. + var context = $.extend({}, opts, comment); + var div = $(renderTemplate(commentTemplate, context)); + + // If the user has voted on this comment, highlight the correct arrow. + if (comment.vote) { + var direction = (comment.vote == 1) ? 'u' : 'd'; + div.find('#' + direction + 'v' + comment.id).hide(); + div.find('#' + direction + 'u' + comment.id).show(); + } + + if (opts.moderator || comment.text != '[deleted]') { + div.find('a.reply').show(); + if (comment.proposal_diff) + div.find('#sp' + comment.id).show(); + if (opts.moderator && !comment.displayed) + div.find('#cm' + comment.id).show(); + if (opts.moderator || (opts.username == comment.username)) + div.find('#dc' + comment.id).show(); + } + return div; + } + + /** + * A simple template renderer. Placeholders such as <%id%> are replaced + * by context['id'] with items being escaped. Placeholders such as <#id#> + * are not escaped. + */ + function renderTemplate(template, context) { + var esc = $(document.createElement('div')); + + function handle(ph, escape) { + var cur = context; + $.each(ph.split('.'), function() { + cur = cur[this]; + }); + return escape ? esc.text(cur || "").html() : cur; + } + + return template.replace(/<([%#])([\w\.]*)\1>/g, function() { + return handle(arguments[2], arguments[1] == '%' ? true : false); + }); + } + + /** Flash an error message briefly. */ + function showError(message) { + $(document.createElement('div')).attr({'class': 'popup-error'}) + .append($(document.createElement('div')) + .attr({'class': 'error-message'}).text(message)) + .appendTo('body') + .fadeIn("slow") + .delay(2000) + .fadeOut("slow"); + } + + /** Add a link the user uses to open the comments popup. */ + $.fn.comment = function() { + return this.each(function() { + var id = $(this).attr('id').substring(1); + var count = COMMENT_METADATA[id]; + var title = count + ' comment' + (count == 1 ? '' : 's'); + var image = count > 0 ? opts.commentBrightImage : opts.commentImage; + var addcls = count == 0 ? ' nocomment' : ''; + $(this) + .append( + $(document.createElement('a')).attr({ + href: '#', + 'class': 'sphinx-comment-open' + addcls, + id: 'ao' + id + }) + .append($(document.createElement('img')).attr({ + src: image, + alt: 'comment', + title: title + })) + .click(function(event) { + event.preventDefault(); + show($(this).attr('id').substring(2)); + }) + ) + .append( + $(document.createElement('a')).attr({ + href: '#', + 'class': 'sphinx-comment-close hidden', + id: 'ah' + id + }) + .append($(document.createElement('img')).attr({ + src: opts.closeCommentImage, + alt: 'close', + title: 'close' + })) + .click(function(event) { + event.preventDefault(); + hide($(this).attr('id').substring(2)); + }) + ); + }); + }; + + var opts = { + processVoteURL: '/_process_vote', + addCommentURL: '/_add_comment', + getCommentsURL: '/_get_comments', + acceptCommentURL: '/_accept_comment', + deleteCommentURL: '/_delete_comment', + commentImage: '/static/_static/comment.png', + closeCommentImage: '/static/_static/comment-close.png', + loadingImage: '/static/_static/ajax-loader.gif', + commentBrightImage: '/static/_static/comment-bright.png', + upArrow: '/static/_static/up.png', + downArrow: '/static/_static/down.png', + upArrowPressed: '/static/_static/up-pressed.png', + downArrowPressed: '/static/_static/down-pressed.png', + voting: false, + moderator: false + }; + + if (typeof COMMENT_OPTIONS != "undefined") { + opts = jQuery.extend(opts, COMMENT_OPTIONS); + } + + var popupTemplate = '\ +
    \ +

    \ + Sort by:\ + best rated\ + newest\ + oldest\ +

    \ +
    Comments
    \ +
    \ + loading comments...
    \ +
      \ +
      \ +

      Add a comment\ + (markup):

      \ +
      \ + reStructured text markup: *emph*, **strong**, \ + ``code``, \ + code blocks: :: and an indented block after blank line
      \ +
      \ + \ +

      \ + \ + Propose a change ▹\ + \ + \ + Propose a change ▿\ + \ +

      \ + \ + \ + \ + \ +
      \ +
      \ +
      '; + + var commentTemplate = '\ +
      \ +
      \ +
      \ + \ + \ + \ + \ + \ + \ +
      \ +
      \ + \ + \ + \ + \ + \ + \ +
      \ +
      \ +
      \ +

      \ + <%username%>\ + <%pretty_rating%>\ + <%time.delta%>\ +

      \ +
      <#text#>
      \ +

      \ + \ + reply ▿\ + proposal ▹\ + proposal ▿\ + \ + \ +

      \ + 
      \
+<#proposal_diff#>\
+
      \ +
        \ +
        \ +
        \ +
        \ + '; + + var replyTemplate = '\ +
      • \ +
        \ +
        \ + \ + \ + \ + \ + \ +
        \ +
        \ +
        • '; + + $(document).ready(function() { + init(); + }); +})(jQuery); + +$(document).ready(function() { + // add comment anchors for all paragraphs that are commentable + $('.sphinx-has-comment').comment(); + + // highlight search words in search results + $("div.context").each(function() { + var params = $.getQueryParameters(); + var terms = (params.q) ? params.q[0].split(/\s+/) : []; + var result = $(this); + $.each(terms, function() { + result.highlightText(this.toLowerCase(), 'highlighted'); + }); + }); + + // directly open comment window if requested + var anchor = document.location.hash; + if (anchor.substring(0, 9) == '#comment-') { + $('#ao' + anchor.substring(9)).click(); + document.location.hash = '#s' + anchor.substring(9); + } +}); diff --git a/docs/_build/html/_themes/README.html b/docs/_build/html/_themes/README.html new file mode 100644 index 0000000..4fcf881 --- /dev/null +++ b/docs/_build/html/_themes/README.html @@ -0,0 +1,153 @@ + + + + + + + + + krTheme Sphinx Style — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        krTheme Sphinx Style

        +

        This repository contains sphinx styles Kenneth Reitz uses in most of +his projects. It is a drivative of Mitsuhiko’s themes for Flask and Flask related +projects. To use this style in your Sphinx documentation, follow +this guide:

        +
          +

        1. put this folder as _themes into your docs folder. Alternatively +you can also use git submodules to check out the contents there.

          +
          2. +

        2. add this to your conf.py:

          +
          sys.path.append(os.path.abspath('_themes'))
+html_theme_path = ['_themes']
+html_theme = 'flask'
+
          +
          +
          3. +
        +

        The following themes exist:

        +
        +
        kr
        +
        the standard flask documentation theme for large projects
        +
        kr_small
        +
        small one-page theme. Intended to be used by very small addon libraries.
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/dev/env.html b/docs/_build/html/dev/env.html new file mode 100644 index 0000000..12b70cb --- /dev/null +++ b/docs/_build/html/dev/env.html @@ -0,0 +1,352 @@ + + + + + + + + + Your Development Environment — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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()
        +
        +
        +

        Todo

        +

        add supertab notes

        +
        +
        +
        +

        TextMate

        +

        “TextMate 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 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 is currently in beta.

        +
        +
        +
        +

        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.

        +
        +
        +

        Eclipse

        +

        The most popular Eclipse plugin for Python development is Aptana’s +PyDev.

        +
        +
        +

        Komodo IDE

        +

        Komodo IDE is developed by ActiveState and is a commerical IDE for Windows, Mac +and Linux.

        +
        +
        +

        Spyder

        +

        Spyder an IDE specifically geared toward working with scientific python libraries (namely Scipy). +Includes integration with pyflakes, pylint, +and rope.

        +

        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 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 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 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

        +

        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
        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/dev/virtualenvs.html b/docs/_build/html/dev/virtualenvs.html new file mode 100644 index 0000000..811f1e3 --- /dev/null +++ b/docs/_build/html/dev/virtualenvs.html @@ -0,0 +1,263 @@ + + + + + + + + + Virtual Environments — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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

        +

        virtualenv is a tool to create +isolated Python environments.

        +

        Install it via pip:

        +
        $ pip install virtualenv
+
        +
        +
        +

        Basic Usage

        +
          +
        1. Create a virtual environment:
          2. +
        +
        $ virtualenv venv
+
        +
        +

        This creates a copy of Python in whichever directory you ran the command in, +placing it in a folder named venv.

        +
          +
        1. To begin using the virtual environment, it needs to be activated:
          2. +
        +
        $ source venv/bin/activate
+
        +
        +

        You can then begin installing any new modules without affecting the system +default Python or other virtual environments.

        +
          +
        1. If you are done working in the virtual environment for the moment, you can +deactivate it:
          2. +
        +
        $ 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

        +

        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):

        +
        $ pip install virtualenvwrapper
+$ export WORKON_HOME=~/Envs
+$ source /usr/local/bin/virtualenvwrapper.sh
+
        +
        +

        (Full virtualenvwrapper install instructions.)

        +
        +

        Basic Usage

        +
          +
        1. Create a virtual environment:
          2. +
        +
        $ mkvirtualenv venv
+
        +
        +

        This creates the venv folder inside ~/Envs.

        +
          +
        1. Work on a virtual environment:
          2. +
        +
        $ 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.

        +
          +
        1. Deactivating is still the same:
          2. +
        +
        $ deactivate
+
        +
        +
          +
        1. To delete:
          2. +
        +
        $ 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.

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/genindex.html b/docs/_build/html/genindex.html new file mode 100644 index 0000000..66dd936 --- /dev/null +++ b/docs/_build/html/genindex.html @@ -0,0 +1,125 @@ + + + + + + + + + + + Index — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + + +

        Index

        + +
        + +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        Related Topics

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/index.html b/docs/_build/html/index.html new file mode 100644 index 0000000..6c5a58d --- /dev/null +++ b/docs/_build/html/index.html @@ -0,0 +1,370 @@ + + + + + + + + + The Hitchhiker’s Guide to Python! — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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!

        +

        This opinionated guide 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.

        +
        +

        Getting Started

        +

        This part of the guide focuses on setting up your Python environment.

        +
        + +
        +
          +
        • Properly Install Python
          • +
        +
        +
        + +
        +
        +
        + +
        +

        Writing Great Code

        +

        This part of the guide focuses on best practices for writing Python code.

        +
        + +
        +
        + +
        +

        Shipping Great Code

        +

        This part of the guide focuses on deploying your Python code.

        +
        + +
        +
        +
        +

        Additional Notes

        +

        This part of the guide, which is mostly prose, begins with some +background information about Python, then focuses on next steps.

        +
        + +
        +
        +

        Contibution notes and legal information are here (for those interested).

        +
        + +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        + +

        Feedback

        +

        + Feedback is greatly appreciated. If you have any questions, comments, + random praise, or anonymous threats, + shoot me an email. +

        + + +

        Useful Links

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/intro/community.html b/docs/_build/html/intro/community.html new file mode 100644 index 0000000..0e8e921 --- /dev/null +++ b/docs/_build/html/intro/community.html @@ -0,0 +1,222 @@ + + + + + + + + + The Community — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        The Community

        +
        +

        BDFL

        +

        Guido van Rossum, the creator of Python, is often referred to as the BDFL — the Benevolent Dictator For Life.

        +
        +
        +

        Python Software Foundation

        +

        The mission of the Python Software Foundation is to promote, protect, and advance the Python programming language, and to support and facilitate the growth of a diverse and international community of Python programmers.

        +

        Learn More about the PSF.

        +
        +
        +

        PEPs

        +

        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):

        +
        +
        +
        Standards
        +
        Describes a new feature or implementation.
        +
        Informational
        +
        Describes a design issue, general guidelines, or information to the community.
        +
        Process
        +
        Describes a process related to Python.
        +
        +
        +
        +

        Notable PEPs

        +

        There are a few PEPs that could be considered required reading:

        +
          +
        • +
          PEP8: The Python Style Guide.
          +

          Read this. All of it. Follow it.

          +
          +
          +
          • +
        • +
          PEP20: The Zen of Python.
          +

          A list of 19 statements that briefly explain the philosophy behind Python.

          +
          +
          +
          • +
        • +
          PEP257: Docstring Conventions.
          +

          Gives guidelines for semantics and conventions associated with Python docstrings.

          +
          +
          +
          • +
        +

        You can read more at The PEP Index.

        +
        +
        +

        Submitting a PEP

        +
        +

        PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone can write and submit a PEP for review.

        +

        Here’s an overview of the PEP acceptance workflow:

        +http://www.python.org/dev/peps/pep-0001/pep-0001-1.png +
        +
        +
        +
        +

        Python Conferences

        +

        The major events for the Python community are developer conferences. The two most notable conferences are PyCon, which is held in the US, and its European sibling, EuroPython.

        +

        A comprehensive list of conferences is maintained at pycon.org.

        +
        +
        +

        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.

        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/intro/documentation.html b/docs/_build/html/intro/documentation.html new file mode 100644 index 0000000..b1c4b4d --- /dev/null +++ b/docs/_build/html/intro/documentation.html @@ -0,0 +1,165 @@ + + + + + + + + + Documentation — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Documentation

        +
        +

        Official Documentation

        +

        The official Python Language and Library documentation can be found here:

        +
        +
        +
        +
        +

        Read the Docs

        +

        Read the Docs is a popular community project, providing a single location for all documentation of popular and even more exotic Python modules.

        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/intro/duction.html b/docs/_build/html/intro/duction.html new file mode 100644 index 0000000..cdca1f7 --- /dev/null +++ b/docs/_build/html/intro/duction.html @@ -0,0 +1,182 @@ + + + + + + + + + Introduction — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Introduction

        +
        +

        Todo

        +

        write a general blurb introducing the Python language

        +
        +
        +

        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 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 Contribute page.

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/intro/learning.html b/docs/_build/html/intro/learning.html new file mode 100644 index 0000000..78ebe7c --- /dev/null +++ b/docs/_build/html/intro/learning.html @@ -0,0 +1,219 @@ + + + + + + + + + Learning Python — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Learning Python

        +
        +

        Beginner

        +
        +

        Learn Python Interactive Tutorial

        +

        Learnpython.org is an easy non-intimidating way to get introduced to python. The website takes the same approach used on the popular Try Ruby website, it has an interactive python interpreter built into the site that allows you to go through the lessons without having to install Python locally.

        +
        +
        +
        +
        +

        Learn Python the Hard Way

        +

        This is an excellent beginner programmer’s guide to Python. It covers “hello world” from the console to the web.

        +
        +
        +
        +
        +

        Crash into Python

        +

        Also known as Python for Programmers with 3 Hours, this guide gives experienced developers from other languages a crash course on Python.

        +
        +
        +
        +
        +

        Dive Into Python 3

        +

        Dive Into Python 3 is a good book for those ready to jump in to Python 3. It’s a +good read if you are moving from Python 2 to 3 or if you already have some +experience programming in another language.

        +
        +
        +
        +
        +

        Think Python: How to Think Like a Computer Scientist

        +

        Think Python attempts to give an introduction to basic concepts in computer science through the +use of the python language. The focus was to create a book with plenty of exercises, minimal jargon and +a section in each chapter devoted to the subject of debugging.

        +

        While exploring the various features available in the python language the author weaves in various design +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 assignments in GUI +and Markov Analysis.

        +
        +
        +
        +
        +
        +

        Advanced

        +
        +

        Pro Python

        +
        +

        Todo

        +

        Write about Pro Python

        +
        +
        +
        +

        Expert Python Programming

        +
        +

        Todo

        +

        Write about Expert Python Programming

        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/intro/news.html b/docs/_build/html/intro/news.html new file mode 100644 index 0000000..854c0b4 --- /dev/null +++ b/docs/_build/html/intro/news.html @@ -0,0 +1,170 @@ + + + + + + + + + News — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        News

        +
        +

        Planet Python

        +

        This is an aggregate of Python news from a growing number of developers.

        +
        +
        +
        +
        +

        /r/python

        +

        /r/python is the Reddit Python community where users contribute and vote on +Python-related news.

        +
        +
        +
        +
        +

        Python Weekly

        +

        Python Weekly is a free weekly newsletter featuring curated news, articles, +new releases, jobs, etc. related to Python.

        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/notes/contribute.html b/docs/_build/html/notes/contribute.html new file mode 100644 index 0000000..7a51854 --- /dev/null +++ b/docs/_build/html/notes/contribute.html @@ -0,0 +1,272 @@ + + + + + + + + + Contribute — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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. +Once your changes get merged back in, you’ll automatically be added to the +Contributors List.

        +
        +

        Style Guide

        +

        For all contributions, please follow the The Guide Style Guide.

        +
        +
        +

        Todo List

        +

        If you’d like to contribute, there’s plenty to do. Here’s a short todo list.

        +
        +
          +
        • Establish “use this” vs “alternatives are....” recommendations
          • +
        +
        +

        Todo

        +

        add supertab notes

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/dev/env.rst, line 58.)

        +
        +

        Todo

        +

        write a general blurb introducing the Python language

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/intro/duction.rst, line 4.)

        +
        +

        Todo

        +

        Write about Pro Python

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/intro/learning.rst, line 62.)

        +
        +

        Todo

        +

        Write about Expert Python Programming

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/intro/learning.rst, line 67.)

        +
        +

        Todo

        +

        Determine License

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/notes/license.rst, line 4.)

        +
        +

        Todo

        +

        Write about Chef

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/admin.rst, line 72.)

        +
        +

        Todo

        +

        Write about Puppet

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/admin.rst, line 77.)

        +
        +

        Todo

        +

        Write about Blueprint

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/admin.rst, line 82.)

        +
        +

        Todo

        +

        Write about Buildout

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/admin.rst, line 87.)

        +
        +

        Todo

        +

        Write about Mule

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/ci.rst, line 27.)

        +
        +

        Todo

        +

        Explain “Command Line Applications”

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/cli.rst, line 4.)

        +
        +

        Todo

        +

        Write about Clint

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/cli.rst, line 9.)

        +
        +

        Todo

        +

        Explain Django ORM

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/db.rst, line 28.)

        +
        +

        Todo

        +

        write about matplotlib.

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/scientific.rst, line 43.)

        +
        +

        Todo

        +

        Explain Pyramid

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/scenarios/web.rst, line 78.)

        +
        +

        Todo

        +

        Fill in “Freezing Your Code” stub

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/shipping/freezing.rst, line 14.)

        +
        +

        Todo

        +

        Write introduction for “Packaging Your Code”

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/shipping/packaging.rst, line 6.)

        +
        +

        Todo

        +

        Fill in “For Linux Distributions” packaging stub

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/shipping/packaging.rst, line 63.)

        +
        +

        Todo

        +

        Write “Building From Source”

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/starting/installation.rst, line 40.)

        +
        +

        Todo

        +

        Fill in License stub

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/writing/license.rst, line 7.)

        +
        +

        Todo

        +

        Fill in “Structuring Your Project” stub

        +
        +

        (The original entry is located in /Users/kreitz/repos/public/python-guide/docs/writing/structure.rst, line 6.)

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/notes/license.html b/docs/_build/html/notes/license.html new file mode 100644 index 0000000..5fa570c --- /dev/null +++ b/docs/_build/html/notes/license.html @@ -0,0 +1,144 @@ + + + + + + + + + License — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        License

        +
        +

        Todo

        +

        Determine License

        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/notes/styleguide.html b/docs/_build/html/notes/styleguide.html new file mode 100644 index 0000000..6aee7da --- /dev/null +++ b/docs/_build/html/notes/styleguide.html @@ -0,0 +1,288 @@ + + + + + + + + + The Guide Style Guide — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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 reStructuredText.

        +
        +

        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 purpose of The Guide.

        +
          +
        • 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 +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: +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 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. To +avoid cluttering the Todo List, 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
        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/objects.inv b/docs/_build/html/objects.inv new file mode 100644 index 0000000..4f2f18e Binary files /dev/null and b/docs/_build/html/objects.inv differ diff --git a/docs/_build/html/scenarios/admin.html b/docs/_build/html/scenarios/admin.html new file mode 100644 index 0000000..48c0f37 --- /dev/null +++ b/docs/_build/html/scenarios/admin.html @@ -0,0 +1,235 @@ + + + + + + + + + Systems Administration — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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:

        +
        $ 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:

        +
        $ 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:

        +
        $ 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

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/scenarios/ci.html b/docs/_build/html/scenarios/ci.html new file mode 100644 index 0000000..7d98f46 --- /dev/null +++ b/docs/_build/html/scenarios/ci.html @@ -0,0 +1,183 @@ + + + + + + + + + Continuous Integration — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Continuous Integration

        +
        +

        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.
        +
        +
        +

        Jenkins

        +

        Jenkins CI is an extensible continuous integration engine. Use it.

        +
        +
        +

        Buildbot

        +

        Buildbot is a Python system to automate the compile/test cycle to validate code changes.

        +
        +
        +

        Mule?

        +
        +

        Todo

        +

        Write about Mule

        +
        +
        +
        +

        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.
          • +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/scenarios/cli.html b/docs/_build/html/scenarios/cli.html new file mode 100644 index 0000000..ca26a66 --- /dev/null +++ b/docs/_build/html/scenarios/cli.html @@ -0,0 +1,159 @@ + + + + + + + + + Command Line Applications — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Command Line Applications

        +
        +

        Todo

        +

        Explain “Command Line Applications”

        +
        +
        +

        Clint

        +
        +

        Todo

        +

        Write about Clint

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/scenarios/db.html b/docs/_build/html/scenarios/db.html new file mode 100644 index 0000000..29e7711 --- /dev/null +++ b/docs/_build/html/scenarios/db.html @@ -0,0 +1,172 @@ + + + + + + + + + Databases — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Databases

        +
        +

        DB-API

        +

        The Python Database API (DB-API) defines a standard interface for Python +database access modules. It’s documented in PEP 249. +Nearly all Python database modules such as sqlite3, psycopg and +mysql-python conform to this interface.

        +
        +
        +

        SQLAlchemy

        +

        SQLAlchemy is a commonly used database toolkit. Unlike many database libraries +it not only provides an ORM layer but also a generalized API for writing +database-agnostic code without SQL.

        +
        pip install sqlalchemy
        +
        +
        +
        +

        Django ORM

        +
        +

        Todo

        +

        Explain Django ORM

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/scenarios/gui.html b/docs/_build/html/scenarios/gui.html new file mode 100644 index 0000000..d421558 --- /dev/null +++ b/docs/_build/html/scenarios/gui.html @@ -0,0 +1,219 @@ + + + + + + + + + GUI Applications — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        GUI Applications

        +
        +

        Qt

        +

        Qt is a cross-platform application framework that is widely used for developing software with a GUI but can also be used for non-GUI applications.

        + +
        +

        PyQt

        +
        +

        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!

        +
        +
        +

        PyObjC

        +
        +

        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

        +

        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

        +

        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.

        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/scenarios/scientific.html b/docs/_build/html/scenarios/scientific.html new file mode 100644 index 0000000..7f513f3 --- /dev/null +++ b/docs/_build/html/scenarios/scientific.html @@ -0,0 +1,198 @@ + + + + + + + + + Scientific Applications — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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 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 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 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 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.

        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/scenarios/speed.html b/docs/_build/html/scenarios/speed.html new file mode 100644 index 0000000..ac7d08d --- /dev/null +++ b/docs/_build/html/scenarios/speed.html @@ -0,0 +1,232 @@ + + + + + + + + + Speed — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Speed

        +

        CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. PyPy is fast.

        +

        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

        +
        +

        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

        +
        +
        +

        The GIL

        +

        Special care must be taken when writing C extensions to make sure you register your threads +with the interpreter.

        +
        +
        +
        +

        C Extentions

        +
        +

        Cython

        +
        +
        +

        Pyrex

        +
        +
        +

        Shedskin?

        +
        +
        +
        +

        Threading

        +
        +

        Threading

        +
        +
        +

        Spanwing Processes

        +
        +
        +

        Multiprocessing

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/scenarios/web.html b/docs/_build/html/scenarios/web.html new file mode 100644 index 0000000..9fd72e1 --- /dev/null +++ b/docs/_build/html/scenarios/web.html @@ -0,0 +1,355 @@ + + + + + + + + + Web Applications — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Web Applications

        +
        +

        Context

        +
        +

        WSGI

        +

        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. WSGI is +documented in PEP-3333.

        +
        +
        +
        +

        Frameworks

        +

        Broadly speaking, a web framework is a set of libraries upon which you can +build custom code to implement a web application (i.e. an interactive web +site). Most web frameworks include patterns and utilities to accomplish at +least the following:

        +
        +
        URL Routing
        +
        Matches an incoming HTTP request to a particular piece of Python code to +be invoked
        +
        Request and Response Objects
        +
        Encapsulate the information received from or sent to a user’s browser
        +
        Template Engine
        +
        Allows for separating Python code implementing an application’s logic from +the HTML (or other) output that it produces
        +
        Development Web Server
        +
        Runs an HTTP server on development machines to enable rapid development; +often automatically reloads server-side code when files are updated
        +
        +
        +

        Django

        +

        Django is a “batteries included” web +application framework. By providing many utilities and patterns out of the +box, Django aims to make it possible to build complex, database-backed web +applications quickly, while encouraging best practices in code written using +it.

        +

        Django has a large and active community, and many pre-built re-usable +modules that can be incorporated into a new +project as-is, or customized to fit your needs.

        +

        There are annual Django conferences in the United States and in Europe.

        +
        +
        +

        Flask

        +

        Flask is a “microframework” for Python. Rather +than aiming to provide everything you could possibly need, Flask implements +the most commonly-used core components of a web application framework, like +URL routing, request and response objects, and templates. As a user of +Flask, it is therefore up to you to choose and integrate other components +you may need, such as database access or form generation and validation. For +many popular modules, 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.

        +
        +

        Todo

        +

        Explain Pyramid

        +
        +
        +
        +
        +

        Web Servers

        +
        +

        Nginx

        +

        Nginx (pronounced “engine-x”) is a web server and +reverse-proxy for HTTP, SMTP and other protocols. It is known for its +high performance, relative simplicity, and compatibility with many +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.

        +
        +
        +
        +

        WSGI Servers

        +

        Stand-alone WSGI servers typically use less resources than traditional web +servers and provide top performance [3].

        +
        +

        Gunicorn

        +

        Gunicorn (Green Unicorn) is a WSGI server used +to serve Python applications. It is a Python interpretation of the Ruby +Unicorn server. Unicorn 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.

        +
        +
        +
        +

        Server Best Practices

        +

        The majority of self hosted Python applications today are hosted with a WSGI +server such as gUnicorn, either directly or behind a +lightweight web server such as nginx.

        +

        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

        +
        +

        Platform-as-a-Service

        +

        Platform-as-a-Service (PaaS) is a type of cloud computing infrastructure +which abstracts and manages infrastructure, routing, and scaling of web +applications. When using PaaS, application developers can focus on writing +application code rather than needing to be concerned with deployment +details.

        +

        Most PaaS services offer a command-line interface that developers can use to +set up and interrogate configuration, and to deploy new releases of an +application to the service.

        +

        PaaS services and their partners offer add-on functionality which is well +integrated into the platform, such as database hosting, email services, +logging, scheduled and background tasks, billing and payment, etc.

        +
        +

        Heroku

        +

        Heroku‘s +Cedar stack offers first class +support for Python 2.7 applications.

        +

        Heroku allows you to run as many Python web applications as you like, 24/7 and free +of charge. Heroku is best described as a horizontal scaling platform. They start +to charge you once you “scale” you application to run on more than one Dyno +(abstacted servers) at a time.

        +

        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.

        +
        +
        +

        DotCloud

        +

        DotCloud supports WSGI applications and +background/worker tasks natively on their platform. Web applications running +Python version 2.6, and uses nginx and uWSGI, and allows custom configuration of both +for advanced users.

        +

        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.

        +
        +
        +

        ep.io

        +

        ep.io is a PaaS designed specifically for Python web +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.

        +

        ep.io is currently in invite-only beta.

        +
        +
        +

        Gondor

        +

        Gondor is a PaaS specailized for deploying Django +and Pinax applications. Gondor supports Django versions 1.2 and 1.3 on +Python version 2.7, and can automatically configure your Django site if you +use local_settings.py for site-specific configuration information.

        +

        Gondor publishes guides to deploying Django projects and Pinax projects on their platform.

        +

        References

        + + + + + +
        [1]The mod_python project is now officially dead
        + + + + + +
        [2]mod_wsgi vs mod_python
        + + + + + +
        [3]Benchmark of Python WSGI Servers
        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/search.html b/docs/_build/html/search.html new file mode 100644 index 0000000..dc74614 --- /dev/null +++ b/docs/_build/html/search.html @@ -0,0 +1,132 @@ + + + + + + + + + Search — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +

        Search

        +
        + +

        + Please activate JavaScript to enable the search + functionality. +

        +
        +

        + From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list. +

        +
        + + + +
        + +
        + +
        + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        Related Topics

        + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/searchindex.js b/docs/_build/html/searchindex.js new file mode 100644 index 0000000..50e61ef --- /dev/null +++ b/docs/_build/html/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({objects:{},terms:{osx:[5,6,25],all:[22,19,16,24,18,3,20],code:[5,6,3,7,22,23,19,18,8,20,26,10],skeleton:6,pocco:19,divers:16,global:[26,19],focus:6,alien:22,concept:14,per:[7,26],follow:[7,19,16,18,8,4,26],benevol:16,ironpython:20,consider:18,cython:0,lgpl:2,depend:[6,12,26],system:[7,6,18,15,8],bpython:26,flask:[18,4],intermedi:20,send:1,articl:[7,9],program:[14,16,20,26,10],present:16,jvm:20,under:[6,23,1],testcas:23,worth:20,introduc:[11,14],sourc:[22,7,20,18,8,2,26],everi:5,kent:7,far:23,distribute_setup:8,util:[18,26,8],mechan:23,broadli:18,stackoverflow:10,veri:[23,4,26],install_homebrew:8,administr:[6,15],level:[20,19],gui:[25,6,14],list:[22,1,16,18,8,26],iter:20,scipi:26,"try":[14,20],item:23,unsupport:8,uwsgi:18,team:7,small:4,markov:14,servic:18,jetbrain:26,pleas:1,prevent:26,bill:18,contibut:6,compens:19,request:[18,1],chef:[6,15],second:23,aptana:26,design:[14,18,16,10],aggreg:9,git:[18,4],download:25,further:[6,12,20],port:[22,23,20],append:4,gunicorn:18,even:[24,19,8],index:[22,16],wide:25,pep257:16,section:14,workflow:[18,16],abl:20,"while":[14,18,20,8],current:[7,6,18,20],version:[23,19,18,8,20,26],run:[22,18,23,8,10],"new":[6,18,1,16,2,20,9],net:[7,20],ever:23,"public":18,full:8,whose:18,gener:[11,19,16,18,3,10],never:8,here:[11,6,1,22,16,24,8],mule:[7,6],beck:7,studio:[20,8],ubuntu:[6,8],path:[4,8],e221:10,becom:18,interpret:[5,6,14,23,20,26],box:[18,8],great:6,boast:23,invit:18,step:[6,18,8],queue:18,webfact:18,mitsuhiko:4,doctest:23,pick:[25,6,20],action:26,opinion:6,studi:14,commonli:[0,18,3],portabl:18,control:18,semant:16,via:[23,8],repositori:[18,4,8],extra:22,curat:9,appli:[14,19],modul:[22,6,3,23,24,18,8,20],foundat:[6,16],submodul:4,apt:8,vim:26,brought:26,put:[4,26],unix:[18,8],api:[6,18,26,3,23],ocelot:8,html_theme:4,instal:[22,6,3,14,23,8,25,26,10],html_theme_path:4,unit:18,highli:20,from:[22,14,19,18,26,8,9],describ:[7,16],would:[22,23],commun:[6,24,18,9,16],handbook:6,two:[19,16],todai:20,next:6,websit:[14,18],bdfl:[6,16],handler:18,call:[22,20,26],recommend:20,taken:19,basi:6,type:[22,19,16,18,8,20],tell:8,more:[22,7,19,16,24,18,8,20,10],chapter:14,share:[18,26],abspath:4,xunit:23,pylint:26,notic:8,enhanc:16,visual:[20,8],extens:[7,18,20,8,23],templat:18,particular:18,known:[22,14,18,26,10],cheeseshop:22,hold:22,enviorn:8,addon:4,dictat:16,hour:14,setup:18,work:[7,23,18,20,26,10],focu:[14,18],dev:19,docco:19,itself:16,can:[22,4,23,16,24,18,8,25,20,26,10],learn:[6,16,14],meet:16,root:19,spyder:26,def:[23,19],boilerpl:23,novic:6,prompt:22,encapsul:18,kenneth:4,give:[14,20,16],process:[0,16],sudo:8,smtp:18,accept:16,topic:[14,16],proprietari:22,explor:14,incom:18,tar:[22,8],string:19,alwai:22,cours:14,multipl:[7,23,20,19,10],clint:[6,13],rather:[18,8],anoth:14,py2ex:5,perhap:1,pyqt:25,write:[11,6,23,14,22,16,18,3,25,20],how:[14,18],anyon:[23,16],reject:16,answer:8,verifi:[7,23],strong:20,simpl:[22,23,8],updat:[18,8],map:26,book:14,dive:14,after:[22,16,26,10],usabl:18,befor:10,mac:[25,6,26,8],contribut:[6,9,1],mai:[18,23],end:20,redund:22,philosophi:16,associ:16,grow:9,test_sampl:23,newlin:26,"short":[7,18,1],attempt:14,practic:[7,6,18,14],ani:[22,23,18,20,26,10],minim:[14,8],correspond:26,rope:26,django:[18,8],issu:[16,1],inform:[6,18,19,16],"switch":23,maintain:[18,8,16],environ:[6,23,20,26,8],allow:[7,14,18,8,23],enter:26,order:[26,8],talk:16,"________________________________":23,help:[6,18,8,10],intimid:14,gradual:18,offici:[6,24,8],move:14,zen:[16,10],mission:16,held:16,scientist:14,through:[14,18],still:22,bunch:16,style:[6,1,23,19,16,8,4,10],group:[6,16],cli:[20,26],fit:18,paa:18,gtk:[25,6],deadsnak:8,bytecod:20,better:23,platform:[25,18,23],window:[5,6,20,26,8],pytest:23,rapidli:7,infrastructur:18,comprehens:16,bittorr:5,therefor:18,might:8,easier:[23,20],fool:22,them:[26,19,8],good:[14,26,10],crash:14,greater:14,thei:[23,20,26,19,16],python:[5,6,0,23,8,1,7,14,22,11,19,16,24,18,26,3,20,9,10],nokia:25,dai:[5,7],exot:24,bound:0,oneir:8,framework:[25,6,18,20,8],facilit:16,e401:10,now:[22,26,8],"_theme":4,discuss:[14,16],introduct:[11,6,14],choic:20,multiprocess:0,name:[22,23,26,19],mytest:23,revers:18,devcent:1,unlik:[8,3],authent:18,separ:[18,26,19],easili:8,editor:[6,26],each:[7,14,19],debug:14,x11:2,european:16,side:18,mean:20,compil:[7,20,26,8],python27:8,hitchhik:6,intellij:26,newslett:9,py2app:5,individu:19,hard:14,continu:[7,6,26],procedur:8,heavi:6,contrib:8,expandtab:26,significantli:7,todo:[14,1],event:16,out:[20,18,4,19,8],assertequ:23,shown:23,accomplish:[18,23],network:18,shiftround:26,space:[26,19,10],open:[22,2,20,26,1],crucial:22,publish:18,content:[23,4],rel:18,internet:[18,8],sparingli:19,got:22,matric:23,pluggabl:18,proxi:18,insid:[22,19],advanc:[6,18,16,14],mypackag:22,differ:[22,6,16,8,20,26],free:[26,9],standard:[3,23,16,18,8,4],quick:7,reason:20,orm:3,releas:[18,9],org:[7,14,19,16,18,8,25],"byte":20,upon:18,quo:20,care:18,indent:[26,19],thread:[6,0],fairli:19,could:[18,16],junit:23,capabl:8,keep:[22,26],thing:[20,19],mxcl:8,europython:16,place:[22,26],propos:16,isc:2,app:18,principl:10,think:14,frequent:7,first:[7,18],oper:10,softwar:[7,6,25,8,16],major:16,directli:[18,20],pyrex:0,feel:22,unicorn:18,number:[19,9,8],yourself:1,restrict:[6,2,20],instruct:18,alreadi:[14,18,8],puppet:[6,15],submit:[16,1],blank:10,vote:9,stabl:25,shiftwidth:26,custom:18,miss:8,primari:19,pysidedownload:25,gpl:[25,2],tox:23,pydev:26,ronn:19,convent:16,script:8,interact:[14,18,23],sometim:19,least:[7,18,19],stack:18,promot:16,master:8,statement:[19,16],similarli:26,interfac:[18,20,3],zeromq:18,dotcloud:18,compliant:[18,26],includ:[7,14,23,19,18,26],autocmd:26,luckili:26,consol:14,gear:26,behind:[18,16],tool:[22,6,23,19,20,26],suit:[18,23],setuptool:8,github:[6,8,1],mostli:6,komodo:26,learnpython:14,than:[18,19,8,23],serv:18,jump:[14,26],target:20,cpython:[0,20],whenev:26,provid:[6,23,24,18,3,20,26],remov:8,structur:[22,6,12],charact:26,project:[6,12,24,18,4,26,10],pronounc:18,balanc:18,toward:26,beginn:[6,14],bet:20,browser:[18,26],pre:18,analysi:14,sai:22,kr_small:4,comput:[14,18],nicer:26,runner:[6,12],pro:14,whitespac:10,reader:14,"return":[23,19],packag:[22,6,8,25,20,26],increment:19,cohes:7,need:[22,23,18,8,25,20,26],border:19,option:8,engin:[7,18],built:[14,18,8],advic:6,pep8:[16,26,10],rout:18,violat:10,snow:8,softtabstop:26,note:[25,6],also:[20,3,14,23,18,8,25,4,26,10],ideal:20,exampl:[22,14,18,8,10],comment:19,take:[14,18],which:[22,6,14,23,19,16,18,20,26],green:18,subject:14,unittest2:23,singl:[24,19],compat:[18,20,23],begin:6,sure:[8,1],unless:[20,19],distribut:[22,6,8],plenti:[14,1],deploy:18,buffer:[18,26],previou:23,reach:20,most:[0,16,18,8,4,26],beta:18,deploi:[6,18],bsd:2,pyflakes_:26,pyflak:26,appload:18,latex:19,simplic:18,don:[25,19,8],url:[22,18],doc:[7,6,24,4,19],later:20,cover:14,pyinstal:5,doe:25,bash_profil:26,part:[6,19],shedskin:0,psycopg:3,jenkin:[7,6],brew:8,usual:7,microsoft:8,fact:[18,19],wsgi:18,has_kei:10,uninstal:8,show:22,text:[6,23,26,19],sent:18,syntax:[23,26],session:23,buildbot:[7,6],"static":20,find:7,despit:23,onli:[25,18,20,26,3],slow:[0,18],locat:24,execut:[5,23,20],explain:16,configur:[6,18,8,23],activ:[18,8,1],state:[18,19],should:[11,19],theme:4,continuousintegr:7,folder:[22,4],darwin:23,local:[14,16],over:[23,20,26],nunit:23,assing:14,pypa:8,nearli:3,variou:14,get:[6,14,18,8,20,10],familiar:[23,8],pypi:[22,0,20,8],compli:25,autom:[7,23],nativ:18,obviou:19,martinfowl:7,"_kos_root":19,report:[10,23,1],tbd:21,requir:[23,26,16],experi:14,keyword:19,patch:1,reload:18,integr:[7,6,18,20,26],contain:[4,19],where:[7,23,9,16],wrote:7,wiki:[25,16],conform:[3,10],set:[6,18,26,8],creator:16,textwidth:26,daltonmato:18,displai:26,see:[18,10],respons:18,fail:23,idea:[26,10],best:[6,18,20,14],concern:18,planet:[6,9],statu:20,detect:7,kei:[6,12,8,1],expert:[6,14],hopefulli:8,databas:[6,18,3],review:16,easi:[14,18,26,23],jargon:14,discoveri:23,hotkei:26,written:[18,20],restructur:19,languag:[11,14,19,16,24,18,20,26],between:18,"import":[22,12,23,19,18,20,10],paramet:23,approach:[7,14],email:18,blurb:11,xvf:8,altern:[5,23,4],reddit:9,psfl:2,extend:23,numer:23,wsgid:18,weav:14,job:9,extent:[6,0],highlight:26,solv:26,homebrew:8,eclips:26,addit:[6,20],both:[6,18,20,26],protect:16,vimrc:26,widest:20,plugin:[23,26],howev:[26,8],annual:18,against:23,etc:[18,9],audienc:20,tutori:[14,18],context:[6,0,18],logic:18,improv:[23,20,26],seri:[23,10],com:[7,25,18,8,10],fantast:8,simpli:[23,8,10],stream:18,point:[18,1],tgz:8,schedul:18,unittest:23,commer:26,ipython:26,spanw:0,webapp:18,batteri:[18,23],typic:8,guid:[6,1,14,16,18,4,10],assum:22,summar:7,pycon:16,speak:[18,20],quit:[18,8],pleasur:26,java:20,coupl:[23,26],addition:26,come:8,numpi:20,three:16,w601:10,compon:[18,8],much:16,valu:26,interest:[6,16],basic:[6,14,23,19,18,8,26],quickli:[7,18,26],e201:10,life:16,legaci:8,gist:8,imag:19,xxx:8,worker:18,search:23,specail:18,argument:19,assert:23,togeth:7,func:23,rpython:20,riverbankcomput:25,rang:19,those:[22,6,23,8,14],"case":14,multi:[23,19],look:[23,20],raw:8,plain:19,tabstop:26,properti:8,commerci:25,aim:[18,20],defin:[18,3,16],invok:18,behavior:18,error:[7,26],fun:23,aid:26,layer:3,pyramid:18,printabl:19,virtualenvwrapp:26,advantag:20,readi:14,non:[25,6,2,14],contributor:1,archiv:22,mongrel2:18,conf:4,lightweight:18,prose:6,partner:18,mani:[5,7,18,8,3],ship:[5,6],sever:[14,20],scienc:14,guido:16,develop:[22,6,1,7,14,16,18,26,25,20,9,10],welcom:[6,1],author:[14,1],perform:[18,20],suggest:1,make:[1,23,18,8,20,26,10],format:19,cross:25,same:[22,14,20,26,19],member:7,handl:26,pysid:25,complex:[18,19],w602:10,sqlite3:3,failur:23,document:[6,23,19,24,18,3,4],kos_root:19,mod_wsgi:18,complet:26,http:[22,7,19,18,8,25,10],x86:8,again:8,fkrull:8,interrog:18,pinax:18,leopard:8,someon:11,handi:[18,26],codebas:20,moment:6,rais:10,user:[6,18,9,8,16],pdf:19,php:25,chang:[7,23,16],techniqu:7,exactli:23,task:[0,18],equival:23,masochist:8,older:8,incorpor:18,markup:19,driv:4,well:[18,8],without:[14,23,3],person:[7,22],client:18,command:[22,6,13,23,18,8,26,10],test_answ:23,thi:[5,6,23,20,8,1,7,14,22,19,16,18,26,3,25,4,9,10],choos:[6,18,2,20],pep1:16,programm:[14,16],everyth:18,guidelin:16,self:[23,19],sibl:16,latest:8,load:18,apach:[18,2],protocol:18,just:20,less:23,excel:14,paragraph:19,linewrap:26,weekli:[6,9],sampl:18,file:[18,23,26,10],mysql:3,speed:[6,0],gondor:18,cppunit:23,web:[6,18,14],rapid:18,europ:18,expos:20,scenario:6,except:10,krtheme:4,add:[20,18,4,8,1],other:[6,14,23,19,18,8,20,26,10],python3:[20,8],exercis:14,overview:[7,16],save:[23,26],explanatori:19,"_______________________________":23,match:18,build:[7,18,8],real:[14,19],applic:[5,6,18,25,13],jython:20,vendor:[6,12],around:16,e211:10,read:[6,12,14,16,24,20],agnost:[18,3],varieti:18,psf:16,piec:[18,23],gatewai:18,nginx:18,reitz:4,cedar:18,know:18,background:[6,18],world:14,base:[6,18,26,23],licens:[25,6,2,21],python2:8,insert:26,exist:[6,4,18,20,26,10],like:[22,6,1,14,23,18,8,26],specif:[18,26],deprec:[8,10],rossum:16,manual:[23,19,8],html:[7,18,19],mit:2,collect:23,nose:23,have:[22,1,14,8,20,26],martin:7,popular:[14,24,18,20,26],output:[18,19,23],unnecessari:19,"function":[18,20,26,23],node:18,www:[25,19,8],drop:8,old:19,often:[18,16,20,10],linux:[5,6,22,26,8],some:[6,14,19,18,8,26,10],back:[18,20],intern:16,wxpython:[25,6],"export":26,fabric:[6,15],facto:10,server:[22,6,18],librari:[3,4,23,24,18,8,20,26],virtualenv:[26,8],freez:[5,6],tab:26,scale:18,lead:7,complex_zero:19,avoid:8,benefici:22,pep:[6,19,16,18,3,10],subclass:23,larg:[18,4,8],select:23,devot:14,toolkit:3,pattern:[14,18],backend:18,notabl:16,refer:[16,20,19,10],machin:[18,20],core:18,encourag:18,object:[18,26],idiomat:10,imaginari:19,inspect:26,usag:[7,6],confer:[6,18,16],who:[7,23],host:[22,6,18],complicat:23,squeez:20,prerequisit:8,found:[24,18,10],peer:16,wget:8,shocco:19,fulli:[25,23],plug:26,about:[7,6,18,16,14],gplv2:2,gplv3:2,shini:20,plai:8,page:[4,19,1],optpars:10,chishop:22,microframework:18,done:8,produc:18,block:19,subset:20,ppa:8,own:23,dilemma:26,activest:26,payment:18,inlin:19,within:26,easy_instal:[22,8],automat:[18,23],appropri:25,cocoa:[25,6],coverag:23,dropbox:5,wrap:26,lesson:14,reli:[20,26],forget:8,your:[5,6,12,20,22,19,23,18,8,25,4,26,10],manag:[18,26,8,23],mod_python:18,van:16,complianc:26,wai:[14,18,26,23],few:[8,16],aren:8,support:[6,18,20,8,16],enabl:18,question:10,fast:0,why:[7,6],avail:[25,14,23,20,8],start:[6,23,19,18,20,26],heroku:18,wordpress:18,pocoo:19,lot:10,replac:8,hassl:23,gil:0,blueprint:[6,15],properli:[22,6,12,8],local_set:18,form:[18,19,10],offer:[18,26],forc:8,bundl:5,regard:19,amongst:8,bbfreez:5,cloud:18,sqlalchemi:[6,3],newer:23,line:[6,13,19,18,26,10],highest:20,bug:[8,1],suppli:26,pull:1,virtualenvwrapper_virtualenv_arg:26,consist:10,possibl:[7,18,20],"default":[18,26,19],wish:8,access:[18,3],maximum:20,distract:19,asynchron:18,below:[23,8],growth:16,pyobjc:25,site:[14,18,26],backport:23,problem:7,extrem:[12,19],debatebl:19,quickfix:26,expect:10,featur:[1,14,23,16,18,26,20,9],creat:[22,14,23,26],pycharm:26,pep20:16,flow:26,"abstract":18,twist:[6,18],implement:[6,0,18,20,16],ini:23,bufwritepost:26,pip:[22,3,23,8,26,10],curl:8,face:18,check:[4,26,10],high:18,brubeck:18,want:[22,23,20,26,8],xyz:1,titl:17,when:[18,20,19,10],detail:[22,14,18],virtual:[20,26],epm:22,idiom:[6,18,10],valid:[7,18],futur:[23,20,8],peopl:20,test:[7,6,23,19],you:[5,6,23,20,1,14,22,16,18,8,25,4,26],architectur:18,fork:[6,18],assertionerror:23,relat:[4,9,16],intend:[18,4],clean:26,ftp:8,simplehttpserv:22,rubi:[14,18,8],"class":[23,20,26],fowler:7,docstr:[19,16],briefli:16,log:18,consid:[8,16],sql:3,e301:10,e302:10,legal:6,reduc:7,outdat:8,experienc:14,receiv:18,sphinx:[4,19],longer:23,scientif:26,directori:[22,26,19],cycl:7,hello:14,fss:8,pathnam:19,time:[22,18,20],convert:19,cpu:0,daili:[7,6]},objtypes:{},titles:["Speed","Contribute","Choosing a License","Databases","krTheme Sphinx Style","Freezing Your Code","The Hitchhikers Guide to Python!","Continuous Integration","Properly Installing Python","News","Code Style","Introduction","Structuring Your Project","Command Line Applications","Learning Python","Systems Administration","The Community","<no title>","Web Applications","Documenting Your Code","Picking an Interpreter","License","Packaging Your Code","Testing Your Code","Documentation","GUI Applications","Your Development Environment"],objnames:{},filenames:["scenarios/speed","notes/contribute","writing/license","scenarios/db","_themes/README","shipping/freezing","index","scenarios/ci","starting/installation","intro/news","writing/style","intro/duction","writing/structure","scenarios/cli","intro/learning","scenarios/admin","intro/community","starting/next","scenarios/web","writing/documentation","starting/which-python","notes/license","shipping/packaging","writing/tests","intro/documentation","scenarios/gui","starting/dev-env"]}) \ No newline at end of file diff --git a/docs/_build/html/shipping/freezing.html b/docs/_build/html/shipping/freezing.html new file mode 100644 index 0000000..ec4ffb1 --- /dev/null +++ b/docs/_build/html/shipping/freezing.html @@ -0,0 +1,197 @@ + + + + + + + + + Freezing Your Code — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Freezing Your Code

        +

        An alternative to shipping your code is freezing it — shipping it as an +executable with a bundled Python interpreter.

        +

        Many applications you use every day do this:

        +
          +
        • Dropbox
          • +
        • BitTorrent
          • +
        • +
        +
        +

        Todo

        +

        Fill in “Freezing Your Code” stub

        +
        +
        +

        Windows

        +
        +

        py2exe

        +
        +
        +
        +

        OSX

        +
        +

        py2app

        +
        +
        +

        PyInstaller

        +
        +
        +
        +

        Linux

        +
        +

        bbFreeze

        +
        +
        +

        PyInstaller

        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/shipping/packaging.html b/docs/_build/html/shipping/packaging.html new file mode 100644 index 0000000..54f5989 --- /dev/null +++ b/docs/_build/html/shipping/packaging.html @@ -0,0 +1,227 @@ + + + + + + + + + Packaging Your Code — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Packaging Your Code

        +

        Packaging your code is important.

        +
        +

        Todo

        +

        Write introduction for “Packaging Your Code”

        +
        +
        +

        For Python Developers

        +

        If you’re writing an open source Python module, PyPI, more properly known as The Cheeseshop, is the place to host it.

        +
        +

        Pip vs. easy_install

        +

        Use pip. More details here

        +
        +
        +

        Personal PyPI

        +

        If you want to install packages from a source different from PyPI, (say, if +your packages are proprietary), you can do it by hosting a simple http server, +running from the directory which holds those packages which need to be installed.

        +

        Showing an example is always beneficial

        +

        Say if you are after installing a package called MyPackage.tar.gz, and assuming this is your directory structure

        +
          +
        • +
          archive
          +
            +
          • +
            MyPackage
            +
              +
            • MyPackage.tar.gz
              • +
            +
            +
            +
            • +
          +
          +
          +
          • +
        +

        Go to your command prompt and type:

        +
        $ cd archive
+$ python -m SimpleHTTPServer 9000
        +
        +

        This runs a simple http server running on port 9000 and will list all packages (like MyPackage). Now you can install MyPackage using any python package installer. Using Pip, you would do it like:

        +
        $ pip install --extra-index-url=http://127.0.0.1:9000/ MyPackage
        +
        +

        Having a folder with the same name as the package name is crucial here. +I got fooled by that, one time. But if you feel that creating a folder called +MyPackage and keeping MyPackage.tar.gz inside that, is redundant, you can still install MyPackage using:

        +
        $ pip install  http://127.0.0.1:9000/MyPackage.tar.gz
        +
        +
        +

        Chishop

        +

        Chishop 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

        +
          +
        • epm
          • +
        • alien
          • +
        +
        +
        +
        + + +
        +
        +
        +
        +

        Python Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.. +
        + + Fork me on GitHub + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/starting/dev-env.html b/docs/_build/html/starting/dev-env.html new file mode 100644 index 0000000..8cfd0ff --- /dev/null +++ b/docs/_build/html/starting/dev-env.html @@ -0,0 +1,256 @@ + + + + + + + + + Your Development Environment — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        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()
        +
        +
        +
        +
        +

        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..

        +
        +
        +

        Eclipse

        +

        The most popular Eclipse plugin for Python development is Aptana’s +PyDev.

        +
        +
        +

        Komodo IDE

        +

        Komodo IDE is developed by ActiveState and is a commerical IDE for Windows, Mac +and Linux.

        +
        +
        +

        Spyder

        +

        Spyder an IDE specifically geared toward working with scientific python libraries (namely Scipy). +Includes integration with pyflakes, pylint, +and rope.

        +

        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
        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/starting/installation.html b/docs/_build/html/starting/installation.html new file mode 100644 index 0000000..af6dc72 --- /dev/null +++ b/docs/_build/html/starting/installation.html @@ -0,0 +1,275 @@ + + + + + + + + + Properly Installing Python — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Properly Installing Python

        +
        +

        Mac OS X

        +

        Or, “Installing Python 2.7 via Homebrew”.

        +
        +

        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.

        +

        To install Homebrew, simply run:

        +
        $ ruby -e "$(curl -fsS http://gist.github.com/raw/323731/install_homebrew.rb)"
        +
        +

        It’s basic commands are update, install, and remove.

        +

        And we can now install Python 2.7:

        +
        $ brew install python --framework
        +
        +

        The --framework option tells Homebrew to compile a Framework-style Python build, rather than a UNIX-style build. The outdated version of Python that Snow Leopard comes packaged with +is built as a Framework, so this helps avoid some future module installation +bugs.

        +

        Don’t forget to update your environment PATH.

        +
        +
        +

        Building From Source

        +
        +
        +

        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.python.org, amongst a few other sources. It also plays well with +virtualenv and user-enviornments.

        +

        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 and Distribute’s easy_install:

        +

        If you have homebrew:

        +
        $ brew install pip
        +
        +

        ...And, if you’re a masochist:

        +
        $ curl -O http://python-distribute.org/distribute_setup.py
+$ python distribute_setup.py
+
+$ easy_install pip
        +
        +

        To install pip:

        +

        Hopefully you’ll never have to use easy_install again.

        +
        +
        +

        Updating Python

        +

        Homebrew makes it simple.

        +
        $ brew update
+$ brew install --force python
        +
        +
        +
        +
        +

        Windows

        +
        +

        Prerequisites:

        +
          +
        • Python2.7 (x86) from Python.org
          • +
        • Microsoft Visual Studio
          • +
        +
        +
        +

        Step 1: 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.

        +
        +
        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:

        +
        $ easy_install pip
        +
        +
        +
        +
        +

        Linux (Ubuntu)

        +

        Oneiric Ocelot, the latest version of Ubuntu, comes with Python 2.7 out of the box. Python 3.2 can be installed and run with the following commands:

        +
        $ sudo apt-get install python3-minimal
+$ python3
        +
        +

        Older versions of Python aren’t available from the official repository. However, if it’s needed (for example to support legacy code), we can add an unsupported repository and install an older version of Python (2.5 in the example below):

        +
        $ sudo apt-get install python-software-properties
+$ sudo add-apt-repository ppa:fkrull/deadsnakes
+$ sudo apt-get update
+$ sudo apt-get install python2.5
        +
        +
        +

        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?
        +
        +
        +
        $ 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
        +

        Now, most Python packages can be installed using the pip command. For example, if we wanted to install Django:

        +
        $ sudo pip install django
        +
        +

        A full list of pip‘s capabilities is available by typing pip --help.

        +
        +
        +

        Linux (Manual)

        +

        While your system will quite likely already have Python installation, you might wish to install a different version. This is done in the typical Linux software source install procedure:

        +
        $ wget http://www.python.org/ftp/python/2.7.2/Python-2.7.2.tgz
+$ tar -xvf Python-2.7.2.tgz
+$ cd Python-2.7.2
+$ ./configure
+$ make
+$ make install
        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/starting/next.html b/docs/_build/html/starting/next.html new file mode 100644 index 0000000..18386b4 --- /dev/null +++ b/docs/_build/html/starting/next.html @@ -0,0 +1,132 @@ + + + + + + + + + <no title> — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/starting/which-python.html b/docs/_build/html/starting/which-python.html new file mode 100644 index 0000000..052936f --- /dev/null +++ b/docs/_build/html/starting/which-python.html @@ -0,0 +1,225 @@ + + + + + + + + + Picking an Interpreter — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Picking an Interpreter

        +

        Which Python to use?

        +
        +

        2.x vs 3.x

        +

        tl;dr: Python 2.x is the status quo, Python 3.x is the shiny new thing.

        +

        Further Reading

        +
        +

        Today

        +

        If you’re choosing a Python interpreter to use, I highly recommend you Use Python 2.7.x, unless you have a strong reason not to.

        +
        +
        +

        The Future

        +

        As more and more modules get ported over to Python3, the easier it will be for +others to use it.

        +
        +
        +
        +

        Which Python to Support?

        +

        If you’re starting work on a new Python module, I recommend you write it for +Python 2.5 or 2.6, and add support for Python3 in a later iteration.

        +
        +
        +

        Implementations

        +

        There are several popular implementations of the Python programming language on +different back-ends.

        +
        +

        CPython

        +

        CPython is the reference implementation of Python, +written in C. It compiles Python code to intermediate bytecode which is then +interpreted by a virtual machine. When people speak of Python they often mean +not just the language but also this implementation. It provides the highest +level of compatibility with Python packages and C extension modules.

        +

        If you are writing open-source Python code and want to reach the widest possible +audience, targeting CPython is your best bet. If you need to use any packages +that are rely on C extensions for their functionality (eg: numpy) then CPython +is your only choice.

        +

        Being the reference implementation, all versions of the Python language are +available as CPython. Python 3 is only available in a CPython implementation.

        +
        +
        +

        PyPy

        +

        PyPy is a Python interpreter implemented in a restricted +statically-typed subset of the Python language called RPython. The interpreter +features a just-in-time compiler and supports multiple back-ends (C, CLI, JVM).

        +

        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.

        +

        Currently PyPy supports Python 2.7.

        +
        +
        +

        Jython

        +

        Jython is a Python implementation that compiles +Python code to Java byte code that then executes on a JVM. It has the additional +advantage of being able to import and use any Java class the same as a Python +module.

        +

        If you need to interface with an existing Java codebase or have other reasons to +need to write Python code for the JVM, Jython is the best choice.

        +

        Currently Jython supports up to Python 2.5.

        +
        +
        +

        IronPython

        +

        IronPython is an implementation of Python for .NET +framework. It can use both Python and .NET framework libraries, and can also +expose Python code to other .NET languages.

        +

        Python Tools for Visual Studio integrate +IronPython directly in to the Visual Studio development environment, making it +an ideal choice for Windows developers.

        +

        IronPython supports Python 2.7.

        +
        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/writing/documentation.html b/docs/_build/html/writing/documentation.html new file mode 100644 index 0000000..87c9763 --- /dev/null +++ b/docs/_build/html/writing/documentation.html @@ -0,0 +1,223 @@ + + + + + + + + + Documenting Your Code — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Documenting Your Code

        +

        Documenting your code is extremely important. It is debatebly even +more important than testing.

        +
        +

        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.:

        +
        Block comments generally apply to some (or all) code that follows them,
+and are indented to the same level as that code.  Each line of a block
+comment starts with a # and a single space (unless it is indented text
+inside the comment).
+Paragraphs inside a block comment are separated by a line containing a
+single #.
        +
        +

        Inline comments are used for individual lines and should be used sparingly.:

        +
        An inline comment is a comment on the same line as a statement.  Inline
+comments should be separated by at least two spaces from the statement.
+They should start with a # and a single space.
+Inline comments are unnecessary and in fact distracting if they state
+the obvious.  Don't do this:
+    x = x + 1                 # Increment x
+But sometimes, this is useful: ::
+    x = x + 1                 # Compensate for border
        +
        +
        +
        +

        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:

        +
        def 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.
+
+    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
+    ...
+
        +
        +
        +
        +

        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.

        +
        +
        +
        +

        Other Tools

        +
        +

        that old thing

        +
        +
        +

        pocco / docco / shocco

        +
        +
        +

        Ronn

        +
        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/writing/license.html b/docs/_build/html/writing/license.html new file mode 100644 index 0000000..3a11fbf --- /dev/null +++ b/docs/_build/html/writing/license.html @@ -0,0 +1,199 @@ + + + + + + + + + Choosing a License — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Choosing a License

        +

        Open source.

        +
        +

        Non-Restrictive

        +
        +

        PSFL

        +
        +
        +

        MIT / BSD / ISC

        +
        +

        MIT (X11)

        +
        +
        +

        New BSD

        +
        +
        +

        ISC

        +
        +
        +
        +

        Apache

        +
        +
        +
        +

        Restrictive

        +
        +

        LGPL

        +
        +
        +

        GPL

        +
        +

        GPLv2

        +
        +
        +

        GPLv3

        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/writing/structure.html b/docs/_build/html/writing/structure.html new file mode 100644 index 0000000..d336946 --- /dev/null +++ b/docs/_build/html/writing/structure.html @@ -0,0 +1,159 @@ + + + + + + + + + Structuring Your Project — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Structuring Your Project

        +

        Structuring your project properly is extremely important.

        +
        +

        Structure is Key

        +
        +
        +

        Vendorizing Dependencies

        +
        +
        +

        Runners

        +
        +
        +

        Further Reading

        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/writing/style.html b/docs/_build/html/writing/style.html new file mode 100644 index 0000000..dc3677b --- /dev/null +++ b/docs/_build/html/writing/style.html @@ -0,0 +1,184 @@ + + + + + + + + + Code Style — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Code Style

        +
        +

        Idioms

        +

        Idiomatic Python code is often referred to as being pythonic.

        +
        +

        Zen of Python

        +

        Also known as PEP 20, the guiding principles for Python’s design.

        +
        >>> import this
+
        +
        +

        See http://stackoverflow.com/questions/228181/the-zen-of-python for some +examples.

        +
        +
        +

        PEP 8

        +

        PEP 8 is the de-facto code style guide for Python.

        +
        +
        +

        There exists a command-line program, pep8 that can check your code for +conformance.

        +
        pip install pep8
        +
        +

        Simply run it on a file or series of files and get a report of any +violations

        +
        $ pep8 optparse.py
+optparse.py:69:11: E401 multiple imports on one line
+optparse.py:77:1: E302 expected 2 blank lines, found 1
+optparse.py:88:5: E301 expected 1 blank line, found 0
+optparse.py:222:34: W602 deprecated form of raising exception
+optparse.py:347:31: E211 whitespace before '('
+optparse.py:357:17: E201 whitespace after '{'
+optparse.py:472:29: E221 multiple spaces before operator
+optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
        +
        +

        Conforming your style to PEP 8 is generally a good idea and helps make code a lot +more consistent when working on projects with other developers.

        +
        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/writing/tests.html b/docs/_build/html/writing/tests.html new file mode 100644 index 0000000..7c779ec --- /dev/null +++ b/docs/_build/html/writing/tests.html @@ -0,0 +1,270 @@ + + + + + + + + + Testing Your Code — pythonguide 0.0.1 documentation + + + + + + + + + + + + + + + + + +
        +

        Navigation

        + +
        + +
        +
        +
        +
        + +
        +

        Testing Your Code

        +

        Testing your code is very important.

        +
        +

        The Basics

        +
        +

        Unittest

        +

        Unittest is the batteries-included test module in the Python standard library. +Its API will be familiar to anyone who has used any of the JUnit/nUnit/CppUnit +series of tools.

        +

        Creating testcases is accomplished by subclassing a TestCase base class

        +
        import unittest
+
+def fun(x):
+    return x + 1
+
+class MyTest(unittest.TestCase):
+    def test(self):
+        self.assertEqual(fun(3), 4)
+
        +
        +

        As of Python 2.7 unittest also includes its own test discovery mechanisms.

        +
        +
        +
        +
        +

        Doctest

        +

        The doctest module searches for pieces of text that look like interactive Python +sessions, and then executes those sessions to verify that they work exactly as +shown.

        +
        +
        +
        +

        Tools

        +
        +

        py.test

        +

        py.test is a no-boilerplate alternative to Python’s standard unittest module.

        +
        $ pip install pytest
        +
        +

        Despite being a fully-featured and extensible test tool it boasts a simple +syntax. Creating a test suite is as easy as writing a module with a couple of +functions

        +
        # content of test_sample.py
+def func(x):
+    return x + 1
+
+def test_answer():
+    assert func(3) == 5
+
        +
        +

        and then running the py.test command

        +
        $ py.test
+=========================== test session starts ============================
+platform darwin -- Python 2.7.1 -- pytest-2.2.1
+collecting ... collected 1 items
+
+test_sample.py F
+
+================================= FAILURES =================================
+_______________________________ test_answer ________________________________
+
+    def test_answer():
+>       assert func(3) == 5
+E       assert 4 == 5
+E        +  where 4 = func(3)
+
+test_sample.py:5: AssertionError
+========================= 1 failed in 0.02 seconds =========================
        +
        +

        far less work than would be required for the equivalent functionality with the +unittest module!

        +
        +
        +
        +
        +

        Nose

        +

        nose extends unittest to make testing easier.

        +
        $ pip install nose
        +
        +

        nose provides automatic test discovery to save you the hassle of manually +creating test suites. It also provides numerous plugins for features such as +xUnit-compatible test output, coverage reporting, and test selection.

        +
        +
        +
        +
        +

        tox

        +

        tox is a tool for automating test environment management and testing against multiple +interpreter configurations

        +
        $ pip install tox
        +
        +

        tox allows you to configure complicatated multi-parameter test matrices via a +simple ini-style configuration file.

        +
        +
        +
        +
        +

        Unittest2

        +

        unittest2 is a a backport of Python 2.7’s unittest module which has an improved +API and better assertions over the one available in previous versions of Python.

        +

        If you’re using Python 2.6 or below, you can install it with pip

        +
        $ pip install unittest2
        +
        +

        You may want to import the module under the name unittest to make porting code +to newer versions of the module easier in the future

        +
        import unittest2 as unittest
+
+class MyTest(unittest.TestCase):
+    ...
+
        +
        +

        This way if you ever switch to a newer python version and no longer need the +unittest2 module, you can simply change the import in your test module without +the need to change any other code.

        +
        +
        +
        +
        +
        + + +
        +
        +
        +
        +

        About This Guide

        +

        + This opinionated guide 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. +

        +

        Table Of Contents

        + +

        Related Topics

        + +

        This Page

        + + + +
        +
        +
        +
        +
        + © Copyright 2011. A Kenneth Reitz Project. +
        + + Fork me on GitHub + + + + + + + \ No newline at end of file diff --git a/docs/_static/test b/docs/_static/test new file mode 100644 index 0000000..e69de29 diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html new file mode 100644 index 0000000..e29e37d --- /dev/null +++ b/docs/_templates/sidebarintro.html @@ -0,0 +1,29 @@ +

        Conduct of Code.

        +

        + This opinionated guide 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. +

        + +

        Donate

        +

        + If you enjoy this guide, consider supporting the author on Gittip: +

        +

        + +

        + +

        Feedback

        +

        + Feedback is greatly appreciated. If you have any questions, comments, + random praise, or anonymous threats, + shoot me an email. +

        + + +

        Useful Links

        + diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html new file mode 100644 index 0000000..d7f12de --- /dev/null +++ b/docs/_templates/sidebarlogo.html @@ -0,0 +1,14 @@ +

        Python Guide.

        +

        + This opinionated guide 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. +

        + +

        Donate

        +

        + If you enjoy this guide, consider supporting the author on Gittip: +

        +

        + +

        \ No newline at end of file diff --git a/docs/_themes/.gitignore b/docs/_themes/.gitignore new file mode 100644 index 0000000..66b6e4c --- /dev/null +++ b/docs/_themes/.gitignore @@ -0,0 +1,3 @@ +*.pyc +*.pyo +.DS_Store diff --git a/docs/_themes/LICENSE b/docs/_themes/LICENSE new file mode 100644 index 0000000..81f4d30 --- /dev/null +++ b/docs/_themes/LICENSE @@ -0,0 +1,45 @@ +Modifications: + +Copyright (c) 2010 Kenneth Reitz. + + +Original Project: + +Copyright (c) 2010 by Armin Ronacher. + + +Some rights reserved. + +Redistribution and use in source and binary forms of the theme, with or +without modification, are permitted provided that the following conditions +are met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + +* The names of the contributors may not be used to endorse or + promote products derived from this software without specific + prior written permission. + +We kindly ask you to only use these themes in an unmodified manner just +for Flask and Flask-related products, not for unrelated projects. If you +like the visual style and want to use it for your own projects, please +consider making some larger changes to the themes (such as changing +font faces, sizes, colors or margins). + +THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/_themes/README.rst b/docs/_themes/README.rst new file mode 100644 index 0000000..8648482 --- /dev/null +++ b/docs/_themes/README.rst @@ -0,0 +1,25 @@ +krTheme Sphinx Style +==================== + +This repository contains sphinx styles Kenneth Reitz uses in most of +his projects. It is a drivative of Mitsuhiko's themes for Flask and Flask related +projects. To use this style in your Sphinx documentation, follow +this guide: + +1. put this folder as _themes into your docs folder. Alternatively + you can also use git submodules to check out the contents there. + +2. add this to your conf.py: :: + + sys.path.append(os.path.abspath('_themes')) + html_theme_path = ['_themes'] + html_theme = 'flask' + +The following themes exist: + +**kr** + the standard flask documentation theme for large projects + +**kr_small** + small one-page theme. Intended to be used by very small addon libraries. + diff --git a/docs/_themes/flask_theme_support.py b/docs/_themes/flask_theme_support.py new file mode 100644 index 0000000..33f4744 --- /dev/null +++ b/docs/_themes/flask_theme_support.py @@ -0,0 +1,86 @@ +# flasky extensions. flasky pygments style based on tango style +from pygments.style import Style +from pygments.token import Keyword, Name, Comment, String, Error, \ + Number, Operator, Generic, Whitespace, Punctuation, Other, Literal + + +class FlaskyStyle(Style): + background_color = "#f8f8f8" + default_style = "" + + styles = { + # No corresponding class for the following: + #Text: "", # class: '' + Whitespace: "underline #f8f8f8", # class: 'w' + Error: "#a40000 border:#ef2929", # class: 'err' + Other: "#000000", # class 'x' + + Comment: "italic #8f5902", # class: 'c' + Comment.Preproc: "noitalic", # class: 'cp' + + Keyword: "bold #004461", # class: 'k' + Keyword.Constant: "bold #004461", # class: 'kc' + Keyword.Declaration: "bold #004461", # class: 'kd' + Keyword.Namespace: "bold #004461", # class: 'kn' + Keyword.Pseudo: "bold #004461", # class: 'kp' + Keyword.Reserved: "bold #004461", # class: 'kr' + Keyword.Type: "bold #004461", # class: 'kt' + + Operator: "#582800", # class: 'o' + Operator.Word: "bold #004461", # class: 'ow' - like keywords + + Punctuation: "bold #000000", # class: 'p' + + # because special names such as Name.Class, Name.Function, etc. + # are not recognized as such later in the parsing, we choose them + # to look the same as ordinary variables. + Name: "#000000", # class: 'n' + Name.Attribute: "#c4a000", # class: 'na' - to be revised + Name.Builtin: "#004461", # class: 'nb' + Name.Builtin.Pseudo: "#3465a4", # class: 'bp' + Name.Class: "#000000", # class: 'nc' - to be revised + Name.Constant: "#000000", # class: 'no' - to be revised + Name.Decorator: "#888", # class: 'nd' - to be revised + Name.Entity: "#ce5c00", # class: 'ni' + Name.Exception: "bold #cc0000", # class: 'ne' + Name.Function: "#000000", # class: 'nf' + Name.Property: "#000000", # class: 'py' + Name.Label: "#f57900", # class: 'nl' + Name.Namespace: "#000000", # class: 'nn' - to be revised + Name.Other: "#000000", # class: 'nx' + Name.Tag: "bold #004461", # class: 'nt' - like a keyword + Name.Variable: "#000000", # class: 'nv' - to be revised + Name.Variable.Class: "#000000", # class: 'vc' - to be revised + Name.Variable.Global: "#000000", # class: 'vg' - to be revised + Name.Variable.Instance: "#000000", # class: 'vi' - to be revised + + Number: "#990000", # class: 'm' + + Literal: "#000000", # class: 'l' + Literal.Date: "#000000", # class: 'ld' + + String: "#4e9a06", # class: 's' + String.Backtick: "#4e9a06", # class: 'sb' + String.Char: "#4e9a06", # class: 'sc' + String.Doc: "italic #8f5902", # class: 'sd' - like a comment + String.Double: "#4e9a06", # class: 's2' + String.Escape: "#4e9a06", # class: 'se' + String.Heredoc: "#4e9a06", # class: 'sh' + String.Interpol: "#4e9a06", # class: 'si' + String.Other: "#4e9a06", # class: 'sx' + String.Regex: "#4e9a06", # class: 'sr' + String.Single: "#4e9a06", # class: 's1' + String.Symbol: "#4e9a06", # class: 'ss' + + Generic: "#000000", # class: 'g' + Generic.Deleted: "#a40000", # class: 'gd' + Generic.Emph: "italic #000000", # class: 'ge' + Generic.Error: "#ef2929", # class: 'gr' + Generic.Heading: "bold #000080", # class: 'gh' + Generic.Inserted: "#00A000", # class: 'gi' + Generic.Output: "#888", # class: 'go' + Generic.Prompt: "#745334", # class: 'gp' + Generic.Strong: "bold #000000", # class: 'gs' + Generic.Subheading: "bold #800080", # class: 'gu' + Generic.Traceback: "bold #a40000", # class: 'gt' + } diff --git a/docs/_themes/kr/layout.html b/docs/_themes/kr/layout.html new file mode 100644 index 0000000..5c081a7 --- /dev/null +++ b/docs/_themes/kr/layout.html @@ -0,0 +1,48 @@ +{%- extends "basic/layout.html" %} +{%- block extrahead %} + {{ super() }} + {% if theme_touch_icon %} + + {% endif %} + +{% endblock %} +{%- block relbar2 %}{% endblock %} +{%- block footer %} +
        + © Copyright {{ copyright }}. +
        + + Fork me on GitHub + + + + + + + + +{%- endblock %} diff --git a/docs/_themes/kr/relations.html b/docs/_themes/kr/relations.html new file mode 100644 index 0000000..3bbcde8 --- /dev/null +++ b/docs/_themes/kr/relations.html @@ -0,0 +1,19 @@ +

        Related Topics

        + diff --git a/docs/_themes/kr/static/flasky.css_t b/docs/_themes/kr/static/flasky.css_t new file mode 100644 index 0000000..c86b80b --- /dev/null +++ b/docs/_themes/kr/static/flasky.css_t @@ -0,0 +1,535 @@ +/* + * flasky.css_t + * ~~~~~~~~~~~~ + * + * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz. + * :license: Flask Design License, see LICENSE for details. + */ + +{% set page_width = '940px' %} +{% set sidebar_width = '220px' %} + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; + font-size: 17px; + background-color: white; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + width: {{ page_width }}; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 {{ sidebar_width }}; +} + +div.sphinxsidebar { + width: {{ sidebar_width }}; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 0 30px; +} + +img.floatingflask { + padding: 0 0 10px 10px; + float: right; +} + +div.footer { + width: {{ page_width }}; + margin: 20px auto 30px auto; + font-size: 14px; + color: #888; + text-align: right; +} + +div.footer a { + color: #888; +} + +div.related { + display: none; +} + +div.sphinxsidebar a { + color: #444; + text-decoration: none; + border-bottom: 1px dotted #999; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid #999; +} + +div.sphinxsidebar { + font-size: 14px; + line-height: 1.5; +} + +div.sphinxsidebarwrapper { + padding: 18px 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0; + margin: -10px 0 0 -20px; + text-align: center; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: 'Garamond', 'Georgia', serif; + color: #444; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: #444; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: #000; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: 'Georgia', serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #004B6B; + text-decoration: underline; +} + +a:hover { + color: #6D4100; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #ddd; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; + background: #eaeaea; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + background: #fafafa; + margin: 20px -30px; + padding: 10px 30px; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; +} + +div.admonition tt.xref, div.admonition a tt { + border-bottom: 1px solid #fafafa; +} + +dd div.admonition { + margin-left: -60px; + padding-left: 60px; +} + +div.admonition p.admonition-title { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: white; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt { + font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.9em; +} + +img.screenshot { +} + +tt.descname, tt.descclassname { + font-size: 0.95em; +} + +tt.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #eee; + background: #fdfdfd; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.footnote td.label { + width: 0px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: #eee; + padding: 7px 30px; + margin: 15px -30px; + line-height: 1.3em; +} + +dl pre, blockquote pre, li pre { + margin-left: -60px; + padding-left: 60px; +} + +dl dl pre { + margin-left: -90px; + padding-left: 90px; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, a tt { + background-color: #FBFBFB; + border-bottom: 1px solid white; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted #004B6B; +} + +a.reference:hover { + border-bottom: 1px solid #6D4100; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted #004B6B; +} + +a.footnote-reference:hover { + border-bottom: 1px solid #6D4100; +} + +a:hover tt { + background: #EEE; +} + + +@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; + } +} + +/* misc. */ + +.revsys-inline { + display: none!important; +} \ No newline at end of file diff --git a/docs/_themes/kr/static/small_flask.css b/docs/_themes/kr/static/small_flask.css new file mode 100644 index 0000000..1c6df30 --- /dev/null +++ b/docs/_themes/kr/static/small_flask.css @@ -0,0 +1,70 @@ +/* + * small_flask.css_t + * ~~~~~~~~~~~~~~~~~ + * + * :copyright: Copyright 2010 by Armin Ronacher. + * :license: Flask Design License, see LICENSE for details. + */ + +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; +} diff --git a/docs/_themes/kr/theme.conf b/docs/_themes/kr/theme.conf new file mode 100644 index 0000000..307a1f0 --- /dev/null +++ b/docs/_themes/kr/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = basic +stylesheet = flasky.css +pygments_style = flask_theme_support.FlaskyStyle + +[options] +touch_icon = diff --git a/docs/_themes/kr_small/layout.html b/docs/_themes/kr_small/layout.html new file mode 100644 index 0000000..aa1716a --- /dev/null +++ b/docs/_themes/kr_small/layout.html @@ -0,0 +1,22 @@ +{% extends "basic/layout.html" %} +{% block header %} + {{ super() }} + {% if pagename == 'index' %} +
        + {% endif %} +{% endblock %} +{% block footer %} + {% if pagename == 'index' %} +
        + {% endif %} +{% endblock %} +{# do not display relbars #} +{% block relbar1 %}{% endblock %} +{% block relbar2 %} + {% if theme_github_fork %} + Fork me on GitHub + {% endif %} +{% endblock %} +{% block sidebar1 %}{% endblock %} +{% block sidebar2 %}{% endblock %} diff --git a/docs/_themes/kr_small/static/flasky.css_t b/docs/_themes/kr_small/static/flasky.css_t new file mode 100644 index 0000000..fe2141c --- /dev/null +++ b/docs/_themes/kr_small/static/flasky.css_t @@ -0,0 +1,287 @@ +/* + * flasky.css_t + * ~~~~~~~~~~~~ + * + * Sphinx stylesheet -- flasky theme based on nature theme. + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'Georgia', serif; + font-size: 17px; + color: #000; + background: white; + margin: 0; + padding: 0; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 40px auto 0 auto; + width: 700px; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 30px 30px; +} + +img.floatingflask { + padding: 0 0 10px 10px; + float: right; +} + +div.footer { + text-align: right; + color: #888; + padding: 10px; + font-size: 14px; + width: 650px; + margin: 0 auto 40px auto; +} + +div.footer a { + color: #888; + text-decoration: underline; +} + +div.related { + line-height: 32px; + color: #888; +} + +div.related ul { + padding: 0 0 0 10px; +} + +div.related a { + color: #444; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #004B6B; + text-decoration: underline; +} + +a:hover { + color: #6D4100; + text-decoration: underline; +} + +div.body { + padding-bottom: 40px; /* saved for footer */ +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +{% if theme_index_logo %} +div.indexwrapper h1 { + text-indent: -999999px; + background: url({{ theme_index_logo }}) no-repeat center center; + height: {{ theme_index_logo_height }}; +} +{% endif %} + +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: white; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; + background: #eaeaea; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + background: #fafafa; + margin: 20px -30px; + padding: 10px 30px; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; +} + +div.admonition p.admonition-title { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight{ + background-color: white; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt { + font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.85em; +} + +img.screenshot { +} + +tt.descname, tt.descclassname { + font-size: 0.95em; +} + +tt.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #eee; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.footnote td { + padding: 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +pre { + padding: 0; + margin: 15px -30px; + padding: 8px; + line-height: 1.3em; + padding: 7px 30px; + background: #eee; + border-radius: 2px; + -moz-border-radius: 2px; + -webkit-border-radius: 2px; +} + +dl pre { + margin-left: -60px; + padding-left: 60px; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, a tt { + background-color: #FBFBFB; +} + +a:hover tt { + background: #EEE; +} diff --git a/docs/_themes/kr_small/theme.conf b/docs/_themes/kr_small/theme.conf new file mode 100644 index 0000000..542b462 --- /dev/null +++ b/docs/_themes/kr_small/theme.conf @@ -0,0 +1,10 @@ +[theme] +inherit = basic +stylesheet = flasky.css +nosidebar = true +pygments_style = flask_theme_support.FlaskyStyle + +[options] +index_logo = '' +index_logo_height = 120px +github_fork = '' diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..ad90eb2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,266 @@ +# -*- coding: utf-8 -*- +# +# pythonguide documentation build configuration file, created by +# sphinx-quickstart on Wed Aug 4 22:51:11 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.append(os.path.abspath('_themes')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# 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', 'sphinx.ext.todo', 'sphinx.ext.intersphinx'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'pythonguide' +copyright = u'2012. A Kenneth Reitz Project. Creative Commons Share-Alike 3.0.' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.1' +# The full version, including alpha/beta/rc tags. +release = '0.0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'flask_theme_support.FlaskyStyle' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'kr' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ['_themes'] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'], + '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', + 'sourcelink.html', 'searchbox.html'] +} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'pythonguidedoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# 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'Python Guide Documentation', + u'Kenneth Reitz', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'pythonguide', u'Python Guide Documentation', + [u'Kenneth Reitz'], 1) +] + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'pythonguide' +epub_author = u'Kenneth Reitz' +epub_publisher = u'Kenneth Reitz' +epub_copyright = u'2010, Kenneth Reitz' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +todo_include_todos = True + +intersphinx_mapping = { + 'python': ('http://docs.python.org/', None), +} diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc new file mode 100644 index 0000000..ca36983 --- /dev/null +++ b/docs/contents.rst.inc @@ -0,0 +1,116 @@ +Getting Started +--------------- + +This part of the guide focuses on setting up your Python environment. + +.. toctree:: + :maxdepth: 2 + + starting/which-python + +- Properly Install Python + + .. toctree:: + :maxdepth: 1 + + starting/install/osx + starting/install/win + starting/install/linux + + + +Writing Great Code +------------------ + +This part of the guide focuses on best practices for writing Python code. + +.. toctree:: + :maxdepth: 2 + + writing/structure + writing/style + writing/documentation + writing/tests + writing/license + + + +Scenario Guide +-------------- + +This part of the guide focuses on tool and module advice based on +different scenarios. + +.. toctree:: + :maxdepth: 2 + + scenarios/client + scenarios/web + scenarios/cli + scenarios/gui + scenarios/db + scenarios/admin + scenarios/ci + scenarios/speed + scenarios/scientific + scenarios/imaging + scenarios/xml + + +Shipping Great Code +------------------- + +This part of the guide focuses on deploying your Python code. + +.. toctree:: + :maxdepth: 2 + + shipping/packaging + shipping/freezing + + +Development Environment +----------------------- + +.. toctree:: + :maxdepth: 2 + + dev/env + dev/virtualenvs + + + + +Additional Notes +---------------- + +This part of the guide, which is mostly prose, begins with some +background information about Python, then focuses on next steps. + +.. toctree:: + :maxdepth: 2 + + intro/duction + intro/community + intro/learning + intro/documentation + intro/news + + + + +-------------------------------------- + +Contibution notes and legal information are here (for those interested). + +.. toctree:: + :maxdepth: 2 + + notes/contribute + notes/license + notes/styleguide + + + + + diff --git a/docs/dev/env.rst b/docs/dev/env.rst new file mode 100644 index 0000000..a539a9f --- /dev/null +++ b/docs/dev/env.rst @@ -0,0 +1,295 @@ +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 +--- + +Vim is a text editor which uses keyboard shortcuts for editing instead of menus +or icons. There exist a couple of plugins and settings for the VIM editor to +aid python development. If you only develop in Python, a good start is to set +the default settings for indentation and line-wrapping to values compliant with +`PEP 8 `_. In your home directory, +open a file called `.vimrc` and add the following lines: :: + + 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. + +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. +To get the most out of Vim, you should continually check your code for syntax +errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will 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 the vim-pep8_ plugin, and for pyflakes you can +install vim-pyflakes_. Now you can map the functions `Pep8()` or `Pyflakes()` +to any hotkey or action you want in Vim. Both plugins will display errors at +the bottom of the screen, and provide an easy way to jump to the corresponding +line. It's very handy to call these functions whenever you save a file. In +order to do this, add the following lines to your `vimrc`:: + + autocmd BufWritePost *.py call Pyflakes() + autocmd BufWritePost *.py call Pep8() + +If you are already using syntastic_ you can enable it to run Pyflakes on write +and show errors and warnings in the quickfix window. An example configuration +to do that which also shows status and warning messages in the statusbar would be:: + + set statusline+=%#warningmsg# + set statusline+=%{SyntasticStatuslineFlag()} + set statusline+=%* + let g:syntastic_auto_loc_list=1 + let g:syntastic_loc_list_height=5 + + +.. _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 +.. _syntastic: https://github.com/scrooloose/syntastic + +.. todo:: add supertab notes + +TextMate +-------- + +"`TextMate `_ 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 `_ 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 `_ +is currently in beta. + +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 `_. + + +Eclipse +------- + +The most popular Eclipse plugin for Python development is Aptana's +`PyDev `_. + + +Komodo IDE +----------- +`Komodo IDE `_ is developed by +ActiveState and is a commercial IDE for Windows, Mac +and Linux. + + +Spyder +------ + +`Spyder `_ an IDE specifically geared +toward working with scientific python libraries (namely `Scipy `_). +Includes integration with pyflakes_, `pylint `_, +and `rope `_. + +Spyder is open-source (free), offers code completion, syntax highlighting, +class and function browser, and object inspection. + + +WingIDE +------- + +`WingIDE `_ a python specific IDE. Runs for Linux, +Windows, and Mac (as an X11 application, which frustrates some Mac users). + + +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 `_ 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 current 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 `_ 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 +::::::::::: + +IDLE +---- + +`IDLE `_ is an integrated +development environment that is part of Python standard library. It is +completely written in Python and uses Tkinter GUI toolkit. Though IDLE +is not suited for full-blown development using Python , it is quite +helpful to try out small Python snippets and experiment with different +features in Python. + +It provides following features: + +* Python Shell Window (interpreter) +* Multi window text editor that colorizes Python code +* Minimal debugging facility + + +IPython +------- + +`IPython `_ 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 +------- + +`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 new file mode 100644 index 0000000..ee6ace2 --- /dev/null +++ b/docs/dev/virtualenvs.rst @@ -0,0 +1,157 @@ +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 +---------- + +`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 +----------------- + +`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 `_.) + +For Windows, you can use the `virtualenvwrapper-powershell `_ clone. + +To install (make sure **virtualenv** is already installed): + +.. code-block:: console + + PS> pip install virtualenvwrapper-powershell + PS> $env:WORKON_HOME="~/Envs" + PS> mkdir $env:WORKON_HOME + PS> import-module virtualenvwrapper + +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 `_. + +autoenv +------- +When you ``cd`` into a directory containing a ``.env`` `autoenv `_ +automagically activates the environment. + +Install it on Mac OS X using ``brew``: + +.. code-block:: console + + $ brew install autoenv + +And on Linux: + +.. code-block:: console + + $ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv + $ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..90cda08 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,18 @@ +.. osxpython documentation master file, created by + sphinx-quickstart on Wed Aug 4 22:51:11 2010. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +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 `_! + +This *opinionated* guide 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. + +.. include:: contents.rst.inc \ No newline at end of file diff --git a/docs/intro/community.rst b/docs/intro/community.rst new file mode 100644 index 0000000..c9635c0 --- /dev/null +++ b/docs/intro/community.rst @@ -0,0 +1,86 @@ +.. _the_community: + +The Community +============= + +BDFL +---- + +Guido van Rossum, the creator of Python, is often referred to as the BDFL — the +Benevolent Dictator For Life. + + + +Python Software Foundation +-------------------------- + +The mission of the Python Software Foundation is to promote, protect, and +advance the Python programming language, and to support and facilitate the +growth of a diverse and international community of Python programmers. + +`Learn More about the PSF `_. + + +PEPs +---- + +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 `_): + + **Standards** + Describes a new feature or implementation. + + **Informational** + Describes a design issue, general guidelines, or information to the + community. + + **Process** + Describes a process related to Python. + + +Notable PEPs +~~~~~~~~~~~~ + +There are a few PEPs that could be considered required reading: + +- `PEP8 `_: The Python Style Guide. + Read this. All of it. Follow it. + +- `PEP20 `_: The Zen of Python. + A list of 19 statements that briefly explain the philosophy behind Python. + +- `PEP257 `_: Docstring Conventions. + Gives guidelines for semantics and conventions associated with Python + docstrings. + +You can read more at `The PEP Index `_. + +Submitting a PEP +~~~~~~~~~~~~~~~~ + + PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone + can write and submit a PEP for review. + + Here's an overview of the PEP acceptance workflow: + + .. image:: http://www.python.org/dev/peps/pep-0001/pep-0001-1.png + + +Python Conferences +-------------------------- + +The major events for the Python community are developer conferences. The two +most notable conferences are PyCon, which is held in the US, and its European +sibling, EuroPython. + +A comprehensive list of conferences is maintained `at pycon.org `_. + + +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 `_. diff --git a/docs/intro/documentation.rst b/docs/intro/documentation.rst new file mode 100644 index 0000000..cdc796d --- /dev/null +++ b/docs/intro/documentation.rst @@ -0,0 +1,21 @@ +Documentation +============= + +Official Documentation +---------------------- + +The official Python Language and Library documentation can be found here: + + - `Python 2.x `_ + - `Python 3.x `_ + + +Read the Docs +------------- + +Read the Docs is a popular community project, providing a single location for +all documentation of popular and even more exotic Python modules. + + `Read the Docs `_ + + diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst new file mode 100644 index 0000000..e0d4180 --- /dev/null +++ b/docs/intro/duction.rst @@ -0,0 +1,88 @@ +Introduction +============ + +From the `official Python website `_: + +Python is a general-purpose, high-level programming language similar +to Tcl, Perl, Ruby, Scheme, or Java. Some of its main key features +include: + +* very clear, readable syntax + + Python's philosophy focuses on readability, from code blocks + delineated with significant whitespace to intuitive keywords in + place of inscrutable punctuation + +* extensive standard libraries and third party modules for virtually + any task + + Python is sometimes described with the words "batteries included" + for its extensive + `standard library `_, which can + includes modules for regular expressions, file IO, fraction handling, + object serialization, and much more. + + Additionally, the + `Python Package Index `_ is available + for users to submit their packages for widespread use, similar to + Perl's `CPAN `_. There is a thriving community + of very powerful Python frameworks and tools like + the `Django `_ web framework and the + `NumPy `_ set of math routines. + +* integration with other systems + + Python can integrate with `Java libraries `_, + enabling it to be used with the rich Java environment that corporate + programmers are used to. It can also be + `extended by C or C++ modules `_ + when speed is of the essence. + +* ubiquity on computers + + Python is available on Windows, \*nix, and Mac. It runs wherever the + Java virtual machine runs, and the reference implementation CPython + can help bring Python to wherever there is a working C compiler. + +* friendly community + + Python has a vibrant and large :ref:`community ` + which maintains wikis, conferences, countless repositories, + mailing lists, IRC channels, and so much more. Heck, the Python + community is even helping to write this guide! + + +.. _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 +`_ 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. + + diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst new file mode 100644 index 0000000..0f38d6e --- /dev/null +++ b/docs/intro/learning.rst @@ -0,0 +1,142 @@ +Learning Python +=============== + +Beginner +-------- + +Learn Python Interactive Tutorial +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Learnpython.org is an easy non-intimidating way to get introduced to python. +The website takes the same approach used on the popular `Try Ruby `_ +website, it has an interactive python interpreter built into the site that +allows you to go through the lessons without having to install Python locally. + + `Learn Python `_ + +Learn Python the Hard Way +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is an excellent beginner programmer's guide to Python. It covers "hello +world" from the console to the web. + + `Learn Python the Hard Way `_ + + +Crash into Python +~~~~~~~~~~~~~~~~~ + +Also known as *Python for Programmers with 3 Hours*, this guide gives +experienced developers from other languages a crash course on Python. + + `Crash into Python `_ + + +Dive Into Python 3 +~~~~~~~~~~~~~~~~~~ + +Dive Into Python 3 is a good book for those ready to jump in to Python 3. It's +a good read if you are moving from Python 2 to 3 or if you already have some +experience programming in another language. + + `Dive Into Python 3 `_ + +Think Python: How to Think Like a Computer Scientist +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Think Python attempts to give an introduction to basic concepts in computer +science through the use of the python language. The focus was to create a book +with plenty of exercises, minimal jargon and a section in each chapter devoted +to the subject of debugging. + +While exploring the various features available in the python language the +author weaves in various design 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 assignments in GUI and Markov +Analysis. + + `Think Python `_ + + +Python Koans +~~~~~~~~~~~~ + +Python Koans is a port of Edgecase's Ruby Koans. It uses a test-driven +approach, q.v. TEST DRIVEN DESIGN SECTION to provide an interactive tutorial +teaching basic python concepts. By fixing assertion statements that fail in a + test script, this provides sequential steps to learning python. + +For those used to languages and figuring out puzzles on their own, this can be +a fun, attractive option. For those new to python and programming, having an +additional resource or reference will be helpful. + + `Python Koans `_ + +More information about test driven development can be found at these resources: + + `Test Driven Development `_ + +A Byte of Python +~~~~~~~~~~~~~~~~ + +A free introductory book that teaches python at the beginner level, it assumes no +previous programming experience. + + `A Byte of Python for Python 2.x `_ + `A Byte of Python for Python 3.x `_ + + +Advanced +-------- + +Pro Python +~~~~~~~~~~ + +This book is for intermediate to advanced Python programmers who are looking to understand how +and why Python works the way it does and how they can take their code to the next level. + + +Expert Python Programming +~~~~~~~~~~~~~~~~~~~~~~~~~ +Expert Python Programming deals with best practices in programming Python and +is focused on the more advanced crowd. + +It starts with topics like decorators (with caching, proxy, and context manager +case-studies), method resolution order, using super() and meta-programming, and +general PEP8 best practices. + +It has a detailed, multi-chapter case study on writing and releasing a package +and eventually an application, including a chapter on using zc.buildout. Later +chapters detail best practices with writing documentation, test-driven +development, version control, and optimization/profiling. + + `Expert Python Programming `_ + +The Python Tutorial +~~~~~~~~~~~~~~~~~~~~ + +This is the official tutorial, it covers all the basics, and offers a tour of the +language and the standard library, recommended for those who need a quickstart +guide to the language. + + `The Python Tutorial `_ + +References +---------- + +Python in a Nutshell +~~~~~~~~~~~~~~~~~~~~ + +Python in a Nutshell, written by Alex Martelli, covers most cross-platform +python's usage, from its syntax to built-in libraries to advanced topics such +as writing C extensions. + +The Python Language Reference +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is Python's reference manual, it covers the syntax and the core semantics of the +language. + + `The Python Language Reference `_ diff --git a/docs/intro/news.rst b/docs/intro/news.rst new file mode 100644 index 0000000..b24fa93 --- /dev/null +++ b/docs/intro/news.rst @@ -0,0 +1,25 @@ +News +==== + +Planet Python +~~~~~~~~~~~~~ + +This is an aggregate of Python news from a growing number of developers. + + `Planet Python `_ + +/r/python +~~~~~~~~~ + +/r/python is the Reddit Python community where users contribute and vote on +Python-related news. + + `/r/python `_ + +Python Weekly +~~~~~~~~~~~~~ + +Python Weekly is a free weekly newsletter featuring curated news, articles, +new releases, jobs, etc. related to Python. + + `Python Weekly `_ diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..39f2a68 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,155 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\osxpython.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\osxpython.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end