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

writing/documentation

writing/tests

writing/gotchas

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

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

--------------------------------------

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

.. toctree::

:maxdepth: 2

notes/contribute

notes/license

notes/styleguide

Reading Great Code

One of the core tenants behind the design of Python is creating

readable code. The motivation behind this design is simple: The number

one thing that Python programmers do is read code.

One of the secrets of becoming a great Python programmer is to read,

understand, and comprehend excellent code.

Excellent code typically follows the guidelines outlined in :ref:`code_style`,

and does its best to express a clear and consise intent to the reader.

Included below is a list of recommended Python projects for reading. Each of

these projects are paragons of excellent Python code.

- `Howdoi <https://github.com/gleitz/howdoi>`_

Howdoi is a code search tool, written in Python.

- `Flask <https://github.com/mitsuhiko/flask>`_

Flask is a microframework for Python based on Werkzeug and Jinja2.

It's intended for getting started very quickly and was developed with

best intentions in mind.

- `Werkzeug <https://github.com/mitsuhiko/werkzeug>`_

Werkzeug started as simple collection of various utilities for WSGI

applications and has become one of the most advanced WSGI utility modules.

It includes a powerful debugger, full-featured request and response objects,

HTTP utilities to handle entity tags, cache control headers, HTTP dates,

cookie handling, file uploads, a powerful URL routing system and a bunch

of community-contributed addon modules.

- `Requests <https://github.com/kennethreitz/requests>`_

Requests is an Apache2 Licensed HTTP library, written in Python,

for human beings.

- `Tablib <https://github.com/kennethreitz/tablib>`_

Tablib is a format-agnostic tabular dataset library, written in Python.

.. todo:: Embed and explain YouTube video showing python code reading: http://www.youtube.com/watch?v=Jc8M9-LoEuo This may require installing a Sphinx plugin. https://bitbucket.org/birkenfeld/sphinx-contrib/src/a09f29fc16970f34350ca36ac7f229e00b1b1674/youtube?at=default

.. todo:: Include code examples of exemplary code from each of the projects listed. Explain why it is excellent code. Use complex examples.

.. todo:: Explain techniques to rapidly identify data structures, algorithms and determine what the code is doing.