mirror of
https://github.com/kennethreitz/python-guide.git
synced 2026-06-05 23:00:18 +00:00
Added new Reading section.
If readability is so important to python, why don't python guides have a list of recommended awesome code to read? Why don't they explain that code? The idea behind this reading section is to provide such a guide. The idea here is to start with something small and useful, with a vision for the future, and iterate quickly.
This commit is contained in:
David Echols
+119
-118
@@ -1,118 +1,119 @@
|
|||||||
Getting Started
|
Getting Started
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
This part of the guide focuses on setting up your Python environment.
|
This part of the guide focuses on setting up your Python environment.
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
starting/which-python
|
starting/which-python
|
||||||
|
|
||||||
- Properly Install Python
|
- Properly Install Python
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
starting/install/osx
|
starting/install/osx
|
||||||
starting/install/win
|
starting/install/win
|
||||||
starting/install/linux
|
starting/install/linux
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Writing Great Code
|
Writing Great Code
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
This part of the guide focuses on best practices for writing Python code.
|
This part of the guide focuses on best practices for writing Python code.
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
writing/structure
|
writing/structure
|
||||||
writing/style
|
writing/style
|
||||||
writing/documentation
|
writing/reading
|
||||||
writing/tests
|
writing/documentation
|
||||||
writing/gotchas
|
writing/tests
|
||||||
writing/license
|
writing/gotchas
|
||||||
|
writing/license
|
||||||
|
|
||||||
|
|
||||||
Scenario Guide
|
|
||||||
--------------
|
Scenario Guide
|
||||||
|
--------------
|
||||||
This part of the guide focuses on tool and module advice based on
|
|
||||||
different scenarios.
|
This part of the guide focuses on tool and module advice based on
|
||||||
|
different scenarios.
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
scenarios/client
|
|
||||||
scenarios/web
|
scenarios/client
|
||||||
scenarios/cli
|
scenarios/web
|
||||||
scenarios/gui
|
scenarios/cli
|
||||||
scenarios/db
|
scenarios/gui
|
||||||
scenarios/network
|
scenarios/db
|
||||||
scenarios/admin
|
scenarios/network
|
||||||
scenarios/ci
|
scenarios/admin
|
||||||
scenarios/speed
|
scenarios/ci
|
||||||
scenarios/scientific
|
scenarios/speed
|
||||||
scenarios/imaging
|
scenarios/scientific
|
||||||
scenarios/xml
|
scenarios/imaging
|
||||||
|
scenarios/xml
|
||||||
|
|
||||||
Shipping Great Code
|
|
||||||
-------------------
|
Shipping Great Code
|
||||||
|
-------------------
|
||||||
This part of the guide focuses on deploying your Python code.
|
|
||||||
|
This part of the guide focuses on deploying your Python code.
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
shipping/packaging
|
|
||||||
shipping/freezing
|
shipping/packaging
|
||||||
|
shipping/freezing
|
||||||
|
|
||||||
Development Environment
|
|
||||||
-----------------------
|
Development Environment
|
||||||
|
-----------------------
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
dev/env
|
|
||||||
dev/virtualenvs
|
dev/env
|
||||||
|
dev/virtualenvs
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Additional Notes
|
|
||||||
----------------
|
Additional Notes
|
||||||
|
----------------
|
||||||
This part of the guide, which is mostly prose, begins with some
|
|
||||||
background information about Python, then focuses on next steps.
|
This part of the guide, which is mostly prose, begins with some
|
||||||
|
background information about Python, then focuses on next steps.
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
intro/duction
|
|
||||||
intro/community
|
intro/duction
|
||||||
intro/learning
|
intro/community
|
||||||
intro/documentation
|
intro/learning
|
||||||
intro/news
|
intro/documentation
|
||||||
|
intro/news
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
--------------------------------------
|
|
||||||
|
--------------------------------------
|
||||||
Contribution notes and legal information are here (for those interested).
|
|
||||||
|
Contribution notes and legal information are here (for those interested).
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
notes/contribute
|
|
||||||
notes/license
|
notes/contribute
|
||||||
notes/styleguide
|
notes/license
|
||||||
|
notes/styleguide
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,44 @@
|
|||||||
|
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.
|
||||||
+614
-613
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user