diff --git a/docs/dev/env.rst b/docs/dev/env.rst deleted file mode 100644 index a539a9f..0000000 --- a/docs/dev/env.rst +++ /dev/null @@ -1,295 +0,0 @@ -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 deleted file mode 100644 index ee6ace2..0000000 --- a/docs/dev/virtualenvs.rst +++ /dev/null @@ -1,157 +0,0 @@ -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/intro/community.rst b/docs/intro/community.rst deleted file mode 100644 index c9635c0..0000000 --- a/docs/intro/community.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _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 deleted file mode 100644 index cdc796d..0000000 --- a/docs/intro/documentation.rst +++ /dev/null @@ -1,21 +0,0 @@ -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 deleted file mode 100644 index e0d4180..0000000 --- a/docs/intro/duction.rst +++ /dev/null @@ -1,88 +0,0 @@ -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 deleted file mode 100644 index 0f38d6e..0000000 --- a/docs/intro/learning.rst +++ /dev/null @@ -1,142 +0,0 @@ -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 deleted file mode 100644 index b24fa93..0000000 --- a/docs/intro/news.rst +++ /dev/null @@ -1,25 +0,0 @@ -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 `_