From b147a1c4902ecd05a73a4d27eb34661525e12633 Mon Sep 17 00:00:00 2001 From: Estevan Pequeno Date: Fri, 30 Dec 2011 11:02:43 -0600 Subject: [PATCH 01/58] Update docs/writing/style.rst --- docs/writing/style.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 216c780..e0cf87d 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -7,6 +7,12 @@ Idioms Idiomatic Python code is often referred to as being *pythonic*. +A common idiom for creating strings is to use `join `_ on an empty string.:: + + letters = ['s', 'p', 'a', 'm'] + word = ''.join(letters) + +This will set the value of the variable *word* to 'spam'. This idiom can be applied to lists and tuples. Zen of Python ------------- From d3dbd65547bc351c2ad1d62d1973b1e4c5e9f715 Mon Sep 17 00:00:00 2001 From: Estevan Pequeno Date: Fri, 30 Dec 2011 11:38:13 -0600 Subject: [PATCH 02/58] Update docs/writing/style.rst --- docs/writing/style.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index e0cf87d..54b4a10 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -14,6 +14,23 @@ A common idiom for creating strings is to use `join `_ page. + Zen of Python ------------- From 4d79aa852680a2ff4952aca54ea497ad50482f13 Mon Sep 17 00:00:00 2001 From: Luke Lee Date: Thu, 2 Feb 2012 10:31:19 -0600 Subject: [PATCH 03/58] Add snippet about PyQwt and how it compares to matplotlib --- docs/scenarios/scientific.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 52a1efe..20c43f8 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -42,9 +42,17 @@ Matplotlib .. todo:: write about matplotlib. +PyQwt +----- + +`PyQwt `_ is a solid library for plotting +numerical data. It is built on top of the popular `PyQt `_ GUI framework. +It typically has better performance than matplotlib, but the range of built-in +chart/plot types is slightly smaller than 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 +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. From 4146ed7db3acd71dbc102e0a37988572219742ca Mon Sep 17 00:00:00 2001 From: John Del Rosario Date: Tue, 14 Feb 2012 16:27:27 +0800 Subject: [PATCH 04/58] Draft for PIL in new imaging section under Scenarios. --- docs/contents.rst.inc | 1 + docs/scenarios/imaging.rst | 44 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 docs/scenarios/imaging.rst diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 6ee37ee..5af8c0f 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -53,6 +53,7 @@ different scenarios. scenarios/ci scenarios/speed scenarios/scientific + scenarios/imaging Shipping Great Code diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst new file mode 100644 index 0000000..3d86487 --- /dev/null +++ b/docs/scenarios/imaging.rst @@ -0,0 +1,44 @@ +================== +Image Manipulation +================== + +.. todo:: + Add introduction about image manipulation and its Python libraries. + +Python Imaging Library +---------------------- + +The `Python Imaging Library `_, or PIL +for short, is *the* library for image manipulation in Python. + +It works with Python 1.5.2 and above, including 2.5, 2.6 and 2.7. Unfortunately, +it doesn't work with 3.0+ yet. + +Installation +~~~~~~~~~~~~ + +PIL has a reputation of not being very straightforward to install. Listed below +are installation notes on various systems. + +Installing on Linux +~~~~~~~~~~~~~~~~~~~ + +Ubuntu 11.04 +```````````` + +.. todo:: + Notes on installing on Ubuntu 11.04 + +Installing on Mac OS X +~~~~~~~~~~~~~~~~~~~~~~ + +.. todo:: + Notes on installing on Mac OS X + +Installing on Windows +~~~~~~~~~~~~~~~~~~~~~ + +.. todo:: + Notes on installing on Windows machines + + From 80022b2b65ef6d1ff18b8ee3b361db75c7c3fd2d Mon Sep 17 00:00:00 2001 From: George Hickman Date: Mon, 12 Mar 2012 10:18:34 -0700 Subject: [PATCH 05/58] Add travis as a CI option --- docs/scenarios/ci.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index d2abfa9..e8e11c2 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -34,4 +34,10 @@ It is a generic virtualenv management and test command line tool which provides * 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 +* Acting as a frontend to Continuous Integration servers, reducing boilerplate and merging CI and shell-based testing. + + +Travis-CI +--------- + +.. todo:: Write about travis-ci From defcf02eef7248801539813d38233744ad6ee1e6 Mon Sep 17 00:00:00 2001 From: Bill Tucker Date: Mon, 12 Mar 2012 12:18:39 -0600 Subject: [PATCH 06/58] fix 2 typos --- docs/notes/styleguide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 626d4a8..a96c7b6 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -12,7 +12,7 @@ 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 + to update those parts to be 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. @@ -20,7 +20,7 @@ The Guide is written as :ref:`restructuredtext-ref`. Relevancy --------- -Stride to keep any contributions relevant to the :ref:`purpose of The Guide +Strive to keep any contributions relevant to the :ref:`purpose of The Guide `. * Avoid including too much information on subjects that don't directly From a2d1609695d187df9c7d7c6bfbc53581cacef5cc Mon Sep 17 00:00:00 2001 From: Bill Tucker Date: Mon, 12 Mar 2012 13:28:23 -0600 Subject: [PATCH 07/58] add reference to Python Koans --- docs/intro/learning.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index ecf3829..6416e47 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -53,6 +53,24 @@ 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 ` + + Advanced -------- From 06aefdbe9b12c9966c620cd1262da68b42b73803 Mon Sep 17 00:00:00 2001 From: Bill Tucker Date: Mon, 12 Mar 2012 13:55:24 -0600 Subject: [PATCH 08/58] add WingIDE to IDE list with comment about X11 on Mac --- docs/dev/env.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 99ccf7b..61b0d68 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -82,6 +82,7 @@ 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 ------- @@ -94,6 +95,7 @@ Komodo IDE `Komodo IDE `_ is developed by ActiveState and is a commerical IDE for Windows, Mac and Linux. + Spyder ------ @@ -104,6 +106,11 @@ 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 on X11 application, which frustrates some Mac users). + Interpreter Tools ::::::::::::::::: From 5464ab3c8d9d2d76d0e164f56c4280545e5f6581 Mon Sep 17 00:00:00 2001 From: Kevin Burke Date: Tue, 13 Mar 2012 00:09:13 -0700 Subject: [PATCH 09/58] refactor the style page. --- docs/writing/style.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 803dca1..e1e713d 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -38,8 +38,10 @@ Also known as PEP 20, the guiding principles for Python's design. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea -- let's do more of those! -See ``_ for some -examples. +For some examples of good Python style, see `this Stack Overflow question +`_ or `these +slides from a Python user group +`_. PEP 8 ----- @@ -48,16 +50,17 @@ 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. +Conforming your Python code to PEP 8 is generally a good idea and helps make +code more consistent when working on projects with other developers. There +exists a command-line program, `pep8 `_, +that can check your code for conformance. :: - pip install pep8 + $ pip install pep8 -Simply run it on a file or series of files and get a report of any -violations +Simply run it on a file or series of files to get a report of any violations. :: @@ -71,5 +74,3 @@ violations 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. From 07ace6f29aaa8f67386417e03fe67bd089ddd424 Mon Sep 17 00:00:00 2001 From: Kevin Burke Date: Tue, 13 Mar 2012 00:10:22 -0700 Subject: [PATCH 10/58] lead in to command --- docs/writing/style.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index e1e713d..c918874 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -53,14 +53,15 @@ PEP 8 is the de-facto code style guide for Python. Conforming your Python code to PEP 8 is generally a good idea and helps make code more consistent when working on projects with other developers. There exists a command-line program, `pep8 `_, -that can check your code for conformance. +that can check your code for conformance. Install it by running the following +command in your Terminal: :: $ pip install pep8 -Simply run it on a file or series of files to get a report of any violations. +Then run it on a file or series of files to get a report of any violations. :: From 67d6aa5dcd318aa542ef497851cc0a0c676cddb1 Mon Sep 17 00:00:00 2001 From: Kevin Burke Date: Tue, 13 Mar 2012 00:31:05 -0700 Subject: [PATCH 11/58] sharpen up vim section and spelling fixes --- docs/dev/env.rst | 43 ++++++++++++++++++---------------- docs/writing/documentation.rst | 2 +- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 61b0d68..304dba0 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -12,10 +12,12 @@ 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:: +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 linewrapping 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 @@ -24,25 +26,26 @@ settings for indentation and linewrapping to values compliant with PEP8:: set softtabstop=4 set shiftround -With these settings newlines are inserted after 79 characters and indentation +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. + +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:: +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() @@ -92,7 +95,7 @@ The most popular Eclipse plugin for Python development is Aptana's Komodo IDE ----------- -`Komodo IDE `_ is developed by ActiveState and is a commerical IDE for Windows, Mac +`Komodo IDE `_ is developed by ActiveState and is a commercial IDE for Windows, Mac and Linux. @@ -109,7 +112,7 @@ Spyder is open-source (free), offers code completion, syntax highlighting, class WingIDE ------- -`WingIDE `_ a python specific IDE. Runs for Linux, Windows, and Mac (as on X11 application, which frustrates some Mac users). +`WingIDE `_ a python specific IDE. Runs for Linux, Windows, and Mac (as an X11 application, which frustrates some Mac users). Interpreter Tools diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 6824665..5ef60da 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -1,7 +1,7 @@ Documenting Your Code ===================== -Documenting your code is extremely important. It is debatebly even +Documenting your code is extremely important. It is debatably even more important than testing. From 3268aff854518edc4097ca3d1db67e0d3a04fca5 Mon Sep 17 00:00:00 2001 From: Dan Crosta Date: Tue, 3 Jan 2012 10:03:59 -0500 Subject: [PATCH 12/58] some idioms I used this morning --- docs/writing/style.rst | 55 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 803dca1..ada5d3c 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -3,9 +3,60 @@ Code Style Idioms -:::::: +------ + +Idiomatic Python code is often referred to as being *Pythonic*. + +.. _unpacking-ref: + +Unpacking +~~~~~~~~~ + +If you know the length of a list or tuple, you can assign names to its +elements with unpacking: + +.. code-block:: python + + for index, item in enumerate(some_list): + # do something with index and item + +You can use this to swap variables, as well: + +.. code-block:: python + + a, b = b, a + +Create an ignored variable +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to assign something (for instance, in :ref:`unpacking-ref`) but +will not need that variable, use ``_``: + +.. code-block:: python + + filename = 'foobar.txt' + basename, _, ext = filename.rpartition() + +Create a length-N list of the same thing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the Python list ``*`` operator: + +.. code-block:: python + + four_nones = [None] * 4 + +Create a length-N list of lists +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Because lists are mutable, the ``*`` operator (as above) will create a list +of N references to the `same` list, which is not likely what you want. +Instead, use a list comprehension: + +.. code-block:: python + + four_lists = [[] for _ in xrange(4)] -Idiomatic Python code is often referred to as being *pythonic*. Zen of Python From 8587cf6a951f9434dd8bddbe9f03cd701a527636 Mon Sep 17 00:00:00 2001 From: Dan Crosta Date: Thu, 5 Jan 2012 11:00:50 -0500 Subject: [PATCH 13/58] per feedback from @ejucovy, warn about shadowing gettext with "_" --- docs/conf.py | 6 +++++- docs/writing/style.rst | 7 +++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 7aa0223..ad90eb2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,7 @@ sys.path.append(os.path.abspath('_themes')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo'] +extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo', 'sphinx.ext.intersphinx'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -260,3 +260,7 @@ epub_copyright = u'2010, Kenneth Reitz' #epub_tocdup = True todo_include_todos = True + +intersphinx_mapping = { + 'python': ('http://docs.python.org/', None), +} diff --git a/docs/writing/style.rst b/docs/writing/style.rst index ada5d3c..666ac6c 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -37,6 +37,13 @@ will not need that variable, use ``_``: filename = 'foobar.txt' basename, _, ext = filename.rpartition() +.. note:: + + "``_``" is commonly used as an alias for the :func:`~gettext.gettext` + function. If your application uses (or may someday use) :mod:`gettext`, + you may want to avoid using ``_`` for ignored variables, as you may + accidentally shadow :func:`~gettext.gettext`. + Create a length-N list of the same thing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From d5a5e545c7ddbaac90233c2825aab6b46d138448 Mon Sep 17 00:00:00 2001 From: Kevin Burke Date: Fri, 16 Mar 2012 01:11:42 -0700 Subject: [PATCH 14/58] add examples of python idioms. --- docs/writing/style.rst | 172 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index c918874..6071b02 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -75,3 +75,175 @@ Then run it on a file or series of files to get a report of any violations. optparse.py:472:29: E221 multiple spaces before operator optparse.py:544:21: W601 .has_key() is deprecated, use 'in' +Conventions +::::::::::: + +Here are some conventions you should follow to make your code easier to read. + +Check if variable equals a constant +----------------------------------- + +You don't need to explicitly compare a value to True, or None, or 0 - you can +just add it to the if statement. + +**Bad**: + +.. code-block:: python + + if attr == True: + print 'True!' + + if attr == None: + print 'attr is None!' + +**Good**: + +.. code-block:: python + + # Just check the value + if attr: + print 'True!' + + # or check for the opposite + if not attr: + print 'attr is None!' + +Access a Dictionary Element +--------------------------- + +Don't use the ``has_key`` function. Instead use ``x in d`` syntax, or pass +a default argument to ``get``. + +**Bad**: + +.. code-block:: python + + d = {'hello': 'world'} + if d.has_key('hello'): + print d['hello'] # prints 'world' + else: + print 'default_value' + +**Good**: + +.. code-block:: python + + d = {'hello': 'world'} + + print d.get('hello', 'default_value') # prints 'world' + print d.get('thingy', 'default_value') # prints 'default_value' + + # Or: + if 'hello' in d: + print d['hello'] + +Short Ways to Manipulate Lists +------------------------------ + +`List comprehensions +`_ +provide a powerful, concise way to work with lists. Also, the `map +`_ and `filter +`_ functions can perform +operations on lists using a different concise syntax. + +**Bad**: + +.. code-block:: python + + # Filter elements less than 5 + a = [3, 4, 5] + b = [] + for i in a: + if a > 4: + b.append(a) + +**Good**: + +.. code-block:: python + + b = [i for i in a if i > 4] + b = filter(lambda x: x > 4, a) + +**Bad**: + +.. code-block:: python + + # Add three to all list members. + a = [3, 4, 5] + count = 0 + for i in a: + a[count] = i + 3 + count = count + 1 + +**Good**: + +.. code-block:: python + + a = [3, 4, 5] + a = [i + 3 for i in a] + # Or: + a = map(lambda i: i + 3, a) + +Use `enumerate `_ to +keep a count of your place in the list. + +.. code-block:: python + + for i, item in a: + print i + ", " + item + # prints + # 0, 3 + # 1, 4 + # 2, 5 + +Read From a File +---------------- + +Use the ``with open`` syntax to read from files. This will automatically close +files for you. + +**Bad**: + +.. code-block:: python + + f = open('file.txt') + a = f.read() + print a + f.close() + +**Good**: + +.. code-block:: python + + with open('file.txt') as f: + for line in f: + print line + +Returning Multiple Values from a Function +----------------------------------------- + +Python supports returning multiple values from a function as a comma-separated +list, so you don't have to create an object or dictionary and pack multiple +values in before you return + +**Bad**: + +.. code-block:: python + + def math_func(a): + return {'square': a ** 2, 'cube': a ** 3} + + d = math_func(3) + s = d['square'] + c = d['cube'] + +**Good**: + +.. code-block:: python + + def math_func(a): + return a ** 2, a ** 3 + + square, cube = math_func(3) + From b80f05a16e0793c35f279356e2c58dab2278569a Mon Sep 17 00:00:00 2001 From: Lee Trout Date: Sun, 25 Mar 2012 13:07:09 -0300 Subject: [PATCH 15/58] Added missing call to enumerate. --- docs/writing/style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index c50c345..e54e6be 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -248,7 +248,7 @@ keep a count of your place in the list. .. code-block:: python - for i, item in a: + for i, item in enumerate(a): print i + ", " + item # prints # 0, 3 From 7ad589a03c6817b77388348d409f88bda2738602 Mon Sep 17 00:00:00 2001 From: Lee Trout Date: Sun, 25 Mar 2012 13:25:00 -0300 Subject: [PATCH 16/58] Updated value checking in style guide with more explicit example for None. --- docs/writing/style.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index e54e6be..c35ad49 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -142,7 +142,9 @@ Check if variable equals a constant ----------------------------------- You don't need to explicitly compare a value to True, or None, or 0 - you can -just add it to the if statement. +just add it to the if statement. See `Truth Value Testing +`_ for a +list of what is considered false. **Bad**: @@ -160,10 +162,14 @@ just add it to the if statement. # Just check the value if attr: - print 'True!' + print 'atter is truthy!' # or check for the opposite if not attr: + print 'attr is falsey!' + + # or, since None is considered false, explicity check for it + if attr is None: print 'attr is None!' Access a Dictionary Element From e9339cca50639ba56a255ab746e44ea73c07d0d8 Mon Sep 17 00:00:00 2001 From: Lee Trout Date: Sun, 25 Mar 2012 13:28:53 -0300 Subject: [PATCH 17/58] Corrected atter typo in style. --- docs/writing/style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index c35ad49..6ca8f22 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -162,7 +162,7 @@ list of what is considered false. # Just check the value if attr: - print 'atter is truthy!' + print 'attr is truthy!' # or check for the opposite if not attr: From 1b082fd8d7a3c390f3de1a2a0f25c14b24d8cbdb Mon Sep 17 00:00:00 2001 From: Mark Simpson Date: Mon, 2 Apr 2012 22:40:21 +1200 Subject: [PATCH 18/58] Updated the OSX install guide to fix a broken link to the homebrew install script --- docs/starting/install/osx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index f0cd8fd..f2cdbd6 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -20,7 +20,7 @@ While Lion comes with a large number of UNIX utilities, those familiar with Linu To `install Homebrew `_, simply run:: - $ ruby -e "$(curl -fsS https://raw.github.com/gist/323731)" + $ ruby -e "$(curl -fsS https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)" Then, insert the hombrew directory at the top of your ``PATH`` enviornment variable. You can do this by adding the following line at the bottom of your ``~/.bashrc`` file:: From 60a206f20f2eab2f405e16e48ce6ae0a606b034a Mon Sep 17 00:00:00 2001 From: Mark Simpson Date: Tue, 3 Apr 2012 00:05:24 +1200 Subject: [PATCH 19/58] The wrong variable is checked and appended in this example code block. --- docs/writing/style.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 6ca8f22..79223e0 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -219,8 +219,8 @@ operations on lists using a different concise syntax. a = [3, 4, 5] b = [] for i in a: - if a > 4: - b.append(a) + if i > 4: + b.append(i) **Good**: From 5479b2f70cdf073c3c5cbae4e9179cb9ee4bf77d Mon Sep 17 00:00:00 2001 From: gregmalcolm Date: Mon, 2 Apr 2012 23:53:00 -0400 Subject: [PATCH 20/58] Corrected Python Koan's URL. Mike's fork of Python Koan's is no longer being maintained, my fork is much more up-to-date --- docs/intro/learning.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 6416e47..6578f4c 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -64,7 +64,7 @@ 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 `_ + `Python Koans `_ More information about test driven development can be found at these resources: From aeb8a0b51f3f0a3a853e6b4eb84aafaa852e0fca Mon Sep 17 00:00:00 2001 From: Trey Hunner Date: Tue, 3 Apr 2012 22:32:30 -0700 Subject: [PATCH 21/58] pocco was renamed to pycco --- docs/writing/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 5ef60da..60be079 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -85,7 +85,7 @@ Other Tools that old thing -------------- -pocco / docco / shocco +pycco / docco / shocco ---------------------- Ronn From 6e2bd3e7cf53a0604e1bf2338bddb73efca286b8 Mon Sep 17 00:00:00 2001 From: William Ting Date: Tue, 17 Apr 2012 00:06:21 -1000 Subject: [PATCH 22/58] Fix list manipulation comments and for loop --- docs/writing/style.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 6ca8f22..dbe4d9b 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -215,12 +215,12 @@ operations on lists using a different concise syntax. .. code-block:: python - # Filter elements less than 5 + # Filter elements greater than 4 a = [3, 4, 5] b = [] for i in a: - if a > 4: - b.append(a) + if i > 4: + b.append(i) **Good**: @@ -256,7 +256,7 @@ keep a count of your place in the list. for i, item in enumerate(a): print i + ", " + item - # prints + # prints # 0, 3 # 1, 4 # 2, 5 From 3960776228df9313db04f7dc0416a300cea42908 Mon Sep 17 00:00:00 2001 From: Sateesh Kumar Date: Fri, 20 Apr 2012 00:00:36 +0530 Subject: [PATCH 23/58] Added a paragraph on IDLE (Section Development Environment:Other Tools) --- docs/dev/env.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 304dba0..61c473d 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -213,6 +213,23 @@ This will prevent your virtualenvs from relying on your (global) site packages d 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 ------- @@ -248,4 +265,3 @@ BPython $ pip install bpython - From 6892dc3e0ff1d19dccde785ce602fde4a77910c9 Mon Sep 17 00:00:00 2001 From: daler Date: Fri, 20 Apr 2012 10:59:52 -0400 Subject: [PATCH 24/58] add description for matplotlib --- docs/scenarios/scientific.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 20c43f8..3b038ad 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -40,7 +40,12 @@ scientific python has never been easier (one click to install about 100 scientif Matplotlib ---------- -.. todo:: write about matplotlib. +`matplotlib `_ is a flexible plotting library +for creating interactive 2D and 3D plots that can also be saved as manuscript-quality +figures. The API in many ways reflects that of `MATLAB `_, easing transition of MATLAB +users to Python. Many examples, along with the source code to re-create them, +can be browsed at the `matplotlib gallery `_. + PyQwt ----- From a029da354221a27fd1ae03bc89f73700ace9592b Mon Sep 17 00:00:00 2001 From: daler Date: Fri, 20 Apr 2012 11:30:51 -0400 Subject: [PATCH 25/58] add description of expert python programming --- docs/intro/learning.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 6578f4c..c2a31fb 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -81,5 +81,16 @@ Pro Python Expert Python Programming ~~~~~~~~~~~~~~~~~~~~~~~~~ +Expert Python Programming deals with best practices in programming Python and +is focused on the more advanced crowd. -.. todo:: Write about `Expert Python Programming `_ +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 `_ From 6e9b37cc37b852ee277e1a567306f3c85091d7f9 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 18:15:10 +0800 Subject: [PATCH 26/58] add some explanations to style guide --- docs/writing/style.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index dbe4d9b..cc2e8c9 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -261,6 +261,9 @@ keep a count of your place in the list. # 1, 4 # 2, 5 +The ``enumerate`` function has better readability than handling a counter manually. Moreover, +it is better optimized for iterators. + Read From a File ---------------- @@ -284,6 +287,9 @@ files for you. for line in f: print line +The ``with`` statement is better because it will ensure you always close the file, +even if an exception is raised. + Returning Multiple Values from a Function ----------------------------------------- From 877d87892d3d55d5c70e2a389846b51e7c18f403 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 19:34:28 +0800 Subject: [PATCH 27/58] A bit more precise on web framworks: they are not only libraries and you built your app inside them --- docs/scenarios/web.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 04c36e7..e3eb2ab 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -21,10 +21,10 @@ 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: +Broadly speaking, a web framework consist of a set of libraries and a main +handler within 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 From 6ccfb2fff52173bbe0babd5e5ecb0e60b388c8d0 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 19:42:37 +0800 Subject: [PATCH 28/58] Adding a sample and explanation for doctests --- docs/writing/documentation.rst | 2 +- docs/writing/tests.rst | 29 ++++++++++++++++++++++++++++- 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 60be079..28edaf4 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -33,7 +33,7 @@ Inline comments are used for individual lines and should be used sparingly.: :: But sometimes, this is useful: :: x = x + 1 # Compensate for border -Doc Strings +Docstrings ----------- PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 90a63df..306c25d 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -37,9 +37,36 @@ 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 +sessions in docstrings, and then executes those sessions to verify that they work exactly as shown. +Doctests have a different use case than proper unit tests: they are usually less +detailed and don't catch special cases or obscure regression bugs. They are +useful as an expressive documentation of the main use cases of a module and +its components. However, doctests should run automatically each time +the full test suite runs. + +A simple doctest in a function: + +:: + + def square(x): + """Squares x. + + >>> square(2) + 4 + >>> square(-2) + 4 + """ + + return x * x + + if __name__ == '__main__': + import doctest + doctest.testmod() + +When running this module from the command line as in ``python module.py``, the doctests +will run and complain if anything is not behaving as described in the docstrings. Tools ::::: From 9944385417ffd63d2976f5d86a92f44798a288e6 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 21:35:04 +0800 Subject: [PATCH 29/58] Adding a bunch on unit tests --- docs/writing/tests.rst | 63 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 306c25d..d7fed0a 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -3,6 +3,69 @@ Testing Your Code Testing your code is very important. +Getting used to writting the testing code and the running code in parallel is +now considered a good habit. Used wisely, this method helps you define more +precisely your code's intent and have a more decoupled architecture. + +Some general rules of testing: + +- A testing unit should focus on one tiny bit of functionality and prove it + correct. + +- Each test unit must be fully independent. Each of them must be able to run + alone, and also within the test suite, regardless of the order they are called. + The implication of this rule is that each test must be loaded with a fresh + dataset and may have to do some cleanup afterwards. This is usually + handled by setUp() and tearDown() methods. + +- Try hard to make tests that run fast. If one single test needs more than a + few millisecond to run, development will be slowed down or the tests will not + be run as often as desirable. I some cases, test can't be fast because they + need a complex data structure to work on, and this data structure must be loaded + every time the test runs. Keep this heavier tests in a separate test suite + that is run by some scheduled task, and run all other tests as often as needed. + +- Learn your tools and learn how to run a single test or a test case. Then, + when developing a function inside a module, run this function's tests very + often, ideally automatically when you save the code. + +- Always run the full test suite before a coding session, and run it again + after. This will give you more confidence that you did not break anything in + the rest of the code. + +- It is a good idea to implement a hook that runs all test before pushing code + to a shared repository. + +- If you are in the middle of a development and have to interrupt your work, it + is a good idea to write a broken unit test about what you want to develop next. + When comming back to work, you will have a pointer to where you were and get + faster on tracks. + +- The first step when you are debugging your code is to write a new test pinpointing + the bug. While it is not always possible to do, those bug catching test are among + the most valuable piece of code in your project. + +- Use long and descriptive names for testing functions. The style guide here is + slighlty different than that of running code, where short names are often + preferred. The reason is testing functions are never called explicitely. + ``square()`` or even ``sqr()`` is ok in running code, but in testing code you + would has names such as ``test_square_of_number_2()``, + ``test_square_negative_number()``. These function names are displayed when a + test fail, and should be as descriptive as possible. + +- When something goes wrong or has to be changed, and if your code has a good + set of tests, you or other maintainers will rely largely on the testing suite + to fix the problem or modify a given behavior. Therefore the testing code will + be read as much as or even more than the running code. A unit test whose + purpose is unclear is not very helpful is this case. + +- Another use of the testing code is as an introduction to new developpers. When + someone will have to work on the code base, runnning and reading the related + testing code is often the best they can do. They will or should discover the + hot spots, where most difficulties arise, and the corner cases. If they have to + add some functionality, the first step should be to add a test and, by this mean, + ensure the new functionality is not already a working path that has not been + plugged in the interface. The Basics :::::::::: From 9a27906007485ad5b5e42b6fe844ac43b61446fa Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sat, 21 Apr 2012 09:45:46 -0400 Subject: [PATCH 30/58] No more epio :( --- docs/scenarios/web.rst | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index e3eb2ab..bd65373 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -190,24 +190,6 @@ See the `DotCloud documentation on Python 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 ~~~~~~ From dd0615e9e73d6a4774276ed8755eaf07c6ce8973 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 21:49:05 +0800 Subject: [PATCH 31/58] Add a reference section with Python in a Nutshell --- docs/intro/learning.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index c2a31fb..9a9bada 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -94,3 +94,13 @@ chapters detail best practices with writing documentation, test-driven development, version control, and optimization/profiling. `Expert Python Programming `_ + + +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. From ce3e50a9132bfb03ff9b53fc720ce48f0bb7747e Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 22:02:59 +0800 Subject: [PATCH 32/58] typo --- docs/starting/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 09afe52..c22ced8 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -8,7 +8,7 @@ If so, you do not need to install or configure anything else to use Python. Havi Installation Guides ------------------- -These guides go over the proper installation of :ref:`Python 2.7 ` for development purproses, as well as distribute, pip, and virtualenv setup. +These guides go over the proper installation of :ref:`Python 2.7 ` for development purposes, as well as distribute, pip, and virtualenv setup. - :ref:`Mac OS X `. - :ref:`Microsoft Windows`. From f860d3e982615d086ee1072dfff9de1f7537ff03 Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 22:43:54 +0800 Subject: [PATCH 33/58] add line continuations in style --- docs/writing/style.rst | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index cc2e8c9..67a9b1f 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -317,3 +317,40 @@ values in before you return square, cube = math_func(3) +Line Continuations +~~~~~~~~~~~~~~~~~~ + +When a logical line of code is longer than the accepted limit, you need to split it over multiple +physical lines. Python interpreter will join consecutive lines if the last character of the line is +a backslash. This is helpful sometime but is preferably avoided, because of its fragility: a white +space added to the end of the line, after the backslash, will break the code and may have unexpected +results. + +A prefered solution is to use parenthesis around your elements. Left with an unclosed parenthesis on an end-of-line +the Python interpreter will join the next line until the parenthesis is closed. The same behavior holds for +curly and square braces. + +**Bad**: + +.. code-block:: python + + my_very_big_string = """For a long time I used to go to bed early. Sometimes, \ + when I had put out my candle, my eyes would close so quickly that I had not even \ + time to say “I’m going to sleep.”""" + + from some.deep.module.inside.a.module import a_nice_function, another_nice_function, \ + yet_another_nice_functio + +**Good**: + +.. code-block:: python + + my_very_big_string = ("For a long time I used to go to bed early. Sometimes, " + "when I had put out my candle, my eyes would close so quickly that I had not even " + time to say “I’m going to sleep.”") + + from some.deep.module.inside.a.module import (a_nice_function, another_nice_function, + yet_another_nice_functio) + +However, more often than not having to split long logical line is a sign that you +are trying to do too many things at the same time, which may hinder readability. From 2d48df09fc363b6e705d7dcc235071bf2304f0ad Mon Sep 17 00:00:00 2001 From: guibog Date: Sat, 21 Apr 2012 23:40:35 +0800 Subject: [PATCH 34/58] Adding poor project structuration examples --- docs/writing/structure.rst | 52 +++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index b83f09a..a640277 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -8,6 +8,56 @@ Structuring your project properly is extremely important. Structure is Key ---------------- +Thanks to the way imports and module are handled in Python, it is +relatively easy to structure a python project. Easy, here, means +actually that you have not many constraints and that the module +importing model is easy grasp. Therefore, you are left with the +pure architectural task of drawing the different parts of your +project and their interactions. + +Easy structuration of a project means it is also easy +to do it poorly. Some signs of a poorly structured projects +include: + +- Multiple and messy circular dependencies: if your classes + Table and Chair in furn.py need to import Carpenter from workers.py + to answer to a question such as table.isdoneby(), + and if convertly the class Carpenter need to import Table and Chair, + for example to answer to carpenter.whatdo(), then you + have a circular dependency, and will have to resort to + fragile hacks such has using import statements inside + methods or functions. + +- Hidden coupling. Each and every change in Table implementation + breaks 20 tests in unrelated test cases because it breaks Carpenter's code, + which requires very careful surgery to adapt the change. This means + you have too many assumptions about Table in Carpenter's code or the + reverse. + +- Heavy usage of global state or context: Instead of explicitely + passing ``(height, width, type, wood)`` to each other, Table + and Carpenter rely on global variables that can be modified + and are modified on the fly by different agent. You need to + scrutinize all access to this global variables to understand why + a rectangular table became a sqaure, and discover that a remote + template code is also modifying this context, messing with + table dimensions. + +- Spaghetti code: Multiple pages of nested if clauses and for loops + with a lot of copy-pasted procedural code and no + proper segmentation are known as spaghetti code. Python's + meaningful indentation (one of its most controversial feature) make + it very hard to maintain this kind of code. So the good news is that + you might not see too much of it. + +- Ravioli code is more likely in Python: it consists of hundreds of + similar little pieces of logic, often classes or objects, without + proper structure. If you never can remember if you have to use + FurnitureTable, AssetTable or Table, or even TableNew for your + task at hand, you might be swimming in ravioli code. + + + Vendorizing Dependencies @@ -20,4 +70,4 @@ Runners Further Reading ---------------- \ No newline at end of file +--------------- From 1fb99e52425de4bde02d9bf2ae86245fb2d87555 Mon Sep 17 00:00:00 2001 From: Juarez Bochi Date: Sat, 21 Apr 2012 17:39:23 -0300 Subject: [PATCH 35/58] Fixed some typos in writing/tests --- docs/writing/tests.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index d7fed0a..81e7e32 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -20,9 +20,9 @@ Some general rules of testing: - Try hard to make tests that run fast. If one single test needs more than a few millisecond to run, development will be slowed down or the tests will not - be run as often as desirable. I some cases, test can't be fast because they + be run as often as desirable. In some cases, test can't be fast because they need a complex data structure to work on, and this data structure must be loaded - every time the test runs. Keep this heavier tests in a separate test suite + every time the test runs. Keep these heavier tests in a separate test suite that is run by some scheduled task, and run all other tests as often as needed. - Learn your tools and learn how to run a single test or a test case. Then, @@ -59,7 +59,7 @@ Some general rules of testing: be read as much as or even more than the running code. A unit test whose purpose is unclear is not very helpful is this case. -- Another use of the testing code is as an introduction to new developpers. When +- Another use of the testing code is as an introduction to new developers. When someone will have to work on the code base, runnning and reading the related testing code is often the best they can do. They will or should discover the hot spots, where most difficulties arise, and the corner cases. If they have to From ee148df82e8d855e830572dc88a04bd5e2c43da9 Mon Sep 17 00:00:00 2001 From: guibog Date: Mon, 23 Apr 2012 22:02:28 +0800 Subject: [PATCH 36/58] Add Templating section in scenario/web --- docs/scenarios/web.rst | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index bd65373..3a81cd6 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -2,6 +2,9 @@ Web Applications ================ +As a powerful scripting language adapted to both fast prototyping +and bigger projects, Python is widely used in Web applications +development. Context ::::::: @@ -203,6 +206,44 @@ Gondor publishes guides to deploying `Django projects `_ on their platform. +Templating +:::::::::: + +Most WSGI applications are responding to HTTP requests to serve +content in HTML or other markup languages. Instead of generating directly +textual content from Python, the concept of separation of concerns +advise us to use templates. A template engine manage a suite of +template files, with a system of hierarchy and inclusion to +avoid unnecessary repetition, and is in charge of rendering +(generating) the actual content, filling the static content +of the templates with the dynamic content generated by the +application. + +As template files are +sometime written by designers or front-end developpers, +it can be difficult to handle increasing complexity. + +Some general good pratices apply to the part of the +application passing dynamic content to the template engine, +and to the templates themselves. + +- Template files should be passed only the dynamic + content that is needed for rendering the template. Avoid + to be tempted to pass additional content "just in case": + it is easier to add some missing variable when needed than to remove + a likely unused variable later. + +- Many template engine allow for complex statements + or assignments in the template itself, and many + allow some Python code to be evaluated in the + templates. This convenience can lead to uncontrolled + increase in complexity, and often harder to find bugs. + +- It is often possible or necessary to mix javascript templates with + HTML templates. A sane approach to this design is to isolate + the parts where the HTML template passes some variable content + to the javascript code. + .. rubric:: References .. [1] `The mod_python project is now officially dead `_ From 15de2679a380accfa202d6a15a1a4bbeff35e579 Mon Sep 17 00:00:00 2001 From: guibog Date: Mon, 23 Apr 2012 23:11:34 +0800 Subject: [PATCH 37/58] Adding some generalities to Style --- docs/writing/style.rst | 127 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 67a9b1f..77efc37 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -1,6 +1,133 @@ Code Style ========== +If you ask to Python programmers what they like the most in Python, they will +often say it is its high readability. Indeed, a high level of readability of +the code is at the heart of the design of the Python language, following the +recognised fact that code is read much more often than it is written. + +One reason for Python code to be easily read and understood is its relatively +complete set of Code Style guidelines and "Pythonic" idioms. + +On the opposite, when a veteran Python developper (a Pythonistas) point to some +parts of a code and say it is not "Pythonic", it usually means that these lines +of code do not follow the common guidelines and fail to express the intent is +what is considered the best (hear: most readable) way. + +On some border cases, no best way has been agreed upon on how to express +an intent in Python code, but these cases are rare. + +General concepts +---------------- + +Explicit code +~~~~~~~~~~~~~ + +While any kind of black magic is possible with Python, the +most explicit and straightforward manner is preferred. + +**Bad** + +.. code-block:: python + + def make_complex(\*args): + x, y = args + return dict(\**locals()) + +**Good** + +.. code-block:: python + + def make_complex(x, y): + return {'x': x, 'y': y} + +In the good code above, x and y are explicitely received from +the caller, and an explicit dictionary is returned. The developer +using this function knows exactly what to do by reading the +first and last lines, which is not the case with the bad example. + +One statement per line +~~~~~~~~~~~~~~~~~~~~~~ + +While some compound statements such as list comprehensions are +allowed and appreciated for their brevity and their expressivity, +it is bad practice to have two disjoint statements on the same line. + +**Bad** + +.. code-block:: python + + print 'one'; print 'two' + + if x == 1: print 'one' + + if and : + # do something + +**Good** + +.. code-block:: python + + print 'one' + print 'two' + + if x == 1: + print 'one' + + cond1 = + cond2 = + if cond1 and cond2: + # do something + + +Avoid the magical wand +~~~~~~~~~~~~~~~~~~~~~~ + +A powerful tool for hackers, Python comes with a very rich set of hooks and +tools allowing to do almost any kind of tricky tricks. For instance, it is +possible to change how objects are created and instanciated, it is possible to +change how the Python interpreter imports modules, it is even possible (and +recommended if needed) to embed C routines in Python. + +However, all these options have many drawbacks and it is always better to use +the most straightforward way to achieve your goal. The main drawback is that +readability suffers deeply from them. Many code analysis tools, such as pylint +or pyflakes, will be unable to parse this "magic" code. + +We consider that a Python developer should know about these nearly infinite +possibilities, because it grows the confidence that no hard-wall will be on the +way. However, knowing how to use them and particularly when **not** to use +them is the most important. + +Like a Kungfu master, a pythonistas knows how to kill with a single finger, and +never do it. + +We are all consenting adults +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As seen above, Python allows many tricks, and some of them are potentially +dangerous. A good example is that any client code can override an object's +properties and methods: There is no "private" keyword in Python. This +philosophy, very different from highly defensive languages like Java, which +give a lot of mechanism to prevent any misuse, is expressed by the saying: "We +are consenting adults". + +This doesn't mean that, for example, no properties are considered private, and +that no proper encapsulation is possible in Python. But, instead of relying on +concrete walls erected by the developers between their code and other's, the +Python community prefers to rely on a set of convention indicating that these +elements should not be accessed directly. + +The main convention for private properties and implementation details is to +prefix all "internals" with an underscore. If the client code breaks this rule +and access to these marked elements, any misbehavior or problems encountered if +the code is modified is the responsibility of the client code. + +Using this convention generously is encouraged: any method or property that is +not intended to be used by client code should be prefixed with an underscore. +This will guarantee a better separation of duties and easier modifications of +existing code, and it will always be possible to publicize a private property, +while privatising a public property might be a much harder operation. Idioms ------ From 9a221d08ac02af460e4a2e1b5a95b1cfb52cd721 Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 19:38:43 +0200 Subject: [PATCH 38/58] add small section about autoenv, asked for in #97 --- docs/dev/virtualenvs.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 7a35e9b..ee6ace2 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -137,3 +137,21 @@ Other useful commands 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 From 25b1614707e47da7a05418c0132b0aa3f38e464c Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 19:44:33 +0200 Subject: [PATCH 39/58] fix lines should be less than 80 chars --- docs/dev/env.rst | 45 +++++++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 61c473d..65225a5 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -63,7 +63,10 @@ order to do this, add the following lines to your `vimrc`:: 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." +"`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 ------------ @@ -75,7 +78,8 @@ 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. +`Sublime Text 2 `_ +is currently in beta. IDEs :::: @@ -83,7 +87,9 @@ 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 `_. +`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 @@ -95,24 +101,28 @@ The most popular Eclipse plugin for Python development is Aptana's Komodo IDE ----------- -`Komodo IDE `_ is developed by ActiveState and is a commercial IDE for Windows, Mac +`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 `_). +`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. +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). +`WingIDE `_ a python specific IDE. Runs for Linux, +Windows, and Mac (as an X11 application, which frustrates some Mac users). Interpreter Tools @@ -122,8 +132,10 @@ 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 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 @@ -195,7 +207,8 @@ 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. +`Virtualenvwrapper `_ makes +virtualenv a pleasure to use by wrapping the command line API with a nicer CLI. :: @@ -208,7 +221,8 @@ 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.. +This will prevent your virtualenvs from relying on your (global) site packages +directory, so that they are completely separate.. Other Tools ::::::::::: @@ -233,10 +247,12 @@ It provides following features: IPython ------- -`IPython `_ provides a rich toolkit to help you make the most out of using Python interactively. Its main components are: +`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. +* 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. @@ -250,7 +266,8 @@ IPython BPython ------- -`bpython `_ is an alternative interface to the Python interpreter for Unix-like operating systems. It has the following features: +`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. From db0f65a24e57d8818b94d6913d4fcc8cd2c48bb3 Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 19:51:47 +0200 Subject: [PATCH 40/58] lines less than 80 chars in /intro/ --- docs/intro/community.rst | 29 ++++++++++++++------ docs/intro/documentation.rst | 3 +- docs/intro/learning.rst | 53 +++++++++++++++++++++--------------- 3 files changed, 53 insertions(+), 32 deletions(-) diff --git a/docs/intro/community.rst b/docs/intro/community.rst index be1176e..329d867 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -4,14 +4,17 @@ The Community BDFL ---- -Guido van Rossum, the creator of Python, is often referred to as the BDFL — the Benevolent Dictator For Life. +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. +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 `_. @@ -19,7 +22,8 @@ The mission of the Python Software Foundation is to promote, protect, and advanc PEPs ---- -PEPs are *Python Enhancement Proposals*. They describe changes to Python itself, or the standards around it. +PEPs are *Python Enhancement Proposals*. They describe changes to Python itself, +or the standards around it. There are three different types of PEPs (as defined by `PEP1 `_): @@ -27,7 +31,8 @@ There are three different types of PEPs (as defined by `PEP1 `_: Docstring Conventions. - Gives guidelines for semantics and conventions associated with Python docstrings. + 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. + 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 +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. +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 `_. @@ -70,4 +79,6 @@ A comprehensive list of conferences is maintained `at pycon.org `_. +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 index 3359f37..cdc796d 100644 --- a/docs/intro/documentation.rst +++ b/docs/intro/documentation.rst @@ -13,7 +13,8 @@ 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. +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/learning.rst b/docs/intro/learning.rst index 9a9bada..c04a28e 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -7,14 +7,18 @@ 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. +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. +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 `_ @@ -22,7 +26,8 @@ This is an excellent beginner programmer's guide to Python. It covers "hello wor 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. +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 `_ @@ -30,8 +35,8 @@ Also known as *Python for Programmers with 3 Hours*, this guide gives experience 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 +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 `_ @@ -39,30 +44,33 @@ 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. +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. +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. +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 ~~~~~~~~~~~~ -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. +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. +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 `_ @@ -102,5 +110,6 @@ 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. +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. From 18cae70452b29fd532d0ef6cc060b1ce486b29fd Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 19:56:08 +0200 Subject: [PATCH 41/58] lines less than 80 chars in /shipping/ --- docs/shipping/packaging.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index a54bd97..5e970fe 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -8,7 +8,8 @@ You'll need to package your code first before sharing it with other developers. 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. +If you're writing an open source Python module, `PyPI `_, +more properly known as *The Cheeseshop*, is the place to host it. @@ -27,7 +28,8 @@ 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 +Say if you are after installing a package called MyPackage.tar.gz, and +assuming this is your directory structure: - archive @@ -40,14 +42,17 @@ 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: +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: +**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 @@ -55,7 +60,9 @@ $ 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. +`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 :::::::::::::::::::::::: From 102f7255461928011101795f6cee10f9b9a8a2dd Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 19:59:00 +0200 Subject: [PATCH 42/58] correct syntax highlighting for code-blocks --- docs/shipping/packaging.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 5e970fe..dc83496 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -37,25 +37,28 @@ assuming this is your directory structure: - MyPackage.tar.gz Go to your command prompt and type: -:: -$ cd archive -$ python -m SimpleHTTPServer 9000 +.. code-block:: console + + $ 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 +.. code-block:: console + + $ 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 +.. code-block:: console + + $ pip install http://127.0.0.1:9000/MyPackage.tar.gz Chishop +++++++ From 38d0e634a6b97bf816f28d1cd4e9646b0f1d4547 Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 20:08:43 +0200 Subject: [PATCH 43/58] lines less than 80 chars in /starting/ --- docs/starting/install/linux.rst | 48 +++++++++++++++++----- docs/starting/install/osx.rst | 73 +++++++++++++++++++++++++-------- docs/starting/install/win.rst | 70 ++++++++++++++++++++++++------- docs/starting/installation.rst | 10 ++++- docs/starting/which-python.rst | 3 +- 5 files changed, 161 insertions(+), 43 deletions(-) diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index ed8680d..a3d88bf 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -5,17 +5,29 @@ Installing Python on Linux The latest version of Ubuntu, **comes with Python 2.7 out of the box**. -You do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the next section before you start building Python applications for real-world use. In particular, you should always install Distribute, as it makes it much easier for you to use other third-party Python libraries. +You do not need to install or configure anything else to use Python. Having +said that, I would strongly recommend that you install the tools and libraries +described in the next section before you start building Python applications +for real-world use. In particular, you should always install Distribute, as +it makes it much easier for you to use other third-party Python libraries. Distribute & Pip ---------------- -The most crucial third-party Python software of all is Distribute, which extends the packaging and installation facilities provided by the distutils in the standard library. Once you add Distribute to your Python system you can download and install any compliant Python software product with a single command. It also enables you to add this network installation capability to your own Python software with very little work. +The most crucial third-party Python software of all is Distribute, which +extends the packaging and installation facilities provided by the distutils +in the standard library. Once you add Distribute to your Python system you can +download and install any compliant Python software product with a single +command. It also enables you to add this network installation capability to +your own Python software with very little work. -To obtain the latest version of Distribute for Linux, run the python script available here: +To obtain the latest version of Distribute for Linux, run the python script +available here: http://python-distribute.org/distribute_setup.py -The new``easy_install`` command you have available is considered by many to be deprecated, so we will install its replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. +The new``easy_install`` command you have available is considered by many to be +deprecated, so we will install its replacement: **pip**. Pip allows for +uninstallation of packages, and is actively maintained, unlike easy_install. To install pip, simply open a command prompt and run:: @@ -25,22 +37,38 @@ To install pip, simply open a command prompt and run:: Virtualenv ---------- -After Distribute & Pip, the next development tool that you should install is `virtualenv `_. Use pip:: +After Distribute & Pip, the next development tool that you should install is +`virtualenv `_. Use pip:: $ pip install virtualenv -The virtualenv kit provides the ability to create virtual Python environments that do not interfere with either each other, or the main Python installation. If you install virtualenv before you begin coding then you can get into the habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. +The virtualenv kit provides the ability to create virtual Python environments +that do not interfere with either each other, or the main Python installation. +If you install virtualenv before you begin coding then you can get into the +habit of using it to create completely clean Python environments for each +project. This is particularly important for Web development, where each +framework and application will have many dependencies. -To set up a new Python environment, change the working directory to where ever you want to store the environment, and run the virtualenv utility in your project's directory:: +To set up a new Python environment, change the working directory to where ever +you want to store the environment, and run the virtualenv utility in your +project's directory:: $ virtualenv --distribute venv -To use an environment, run ``source venv/bin/activate``. Your command prompt will change to show the active environment. Once you have finished working in the current virtual environment, run ``deactivate`` to restore your settings to normal. +To use an environment, run ``source venv/bin/activate``. Your command prompt +will change to show the active environment. Once you have finished working in +the current virtual environment, run ``deactivate`` to restore your settings +to normal. -Each new environment automatically includes a copy of ``pip``, so that you can setup the third-party libraries and tools that you want to use in that environment. Put your own code within a subdirectory of the environment, however you wish. When you no longer need a particular environment, simply copy your code out of it, and then delete the main directory for the environment. +Each new environment automatically includes a copy of ``pip``, so that you can +setup the third-party libraries and tools that you want to use in that +environment. Put your own code within a subdirectory of the environment, +however you wish. When you no longer need a particular environment, simply +copy your code out of it, and then delete the main directory for the environment. -------------------------------- -This page is a remixed version of `another guide `_, which is available under the same license. +This page is a remixed version of `another guide `_, +which is available under the same license. diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index f2cdbd6..006f2e0 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -5,24 +5,37 @@ Installing Python on Mac OS X The latest version of Mac OS X, Lion, **comes with Python 2.7 out of the box**. -You do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the next section before you start building Python applications for real-world use. In particular, you should always install Distribute, as it makes it much easier for you to use other third-party Python libraries. +You do not need to install or configure anything else to use Python. Having +said that, I would strongly recommend that you install the tools and libraries +described in the next section before you start building Python applications +for real-world use. In particular, you should always install Distribute, as it +makes it much easier for you to use other third-party Python libraries. -The version of Python that ships with OS X is great for learning, but it's not good for development. It's slightly out of date, and Apple has made significant changes that can cause hidden bugs. +The version of Python that ships with OS X is great for learning, but it's not +good for development. It's slightly out of date, and Apple has made significant +changes that can cause hidden bugs. Doing it Right -------------- Let's install a real version of Python. -First, you'll need to have GCC installed to compile Python. You can either get this from `XCode `_ or the smaller `OSX-GCC-Installer `_ package. +First, you'll need to have GCC installed to compile Python. You can either get +this from `XCode `_ or the smaller +`OSX-GCC-Installer `_ package. -While Lion comes with a large number of UNIX utilities, those familiar with Linux systems will notice one key component missing: a decent package manager. `Homebrew `_ fills this void. +While Lion comes with a large number of UNIX utilities, those familiar with +Linux systems will notice one key component missing: a decent package manager. +`Homebrew `_ fills this void. -To `install Homebrew `_, simply run:: +To `install Homebrew `_, +simply run:: $ ruby -e "$(curl -fsS https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)" -Then, insert the hombrew directory at the top of your ``PATH`` enviornment variable. You can do this by adding the following line at the bottom of your ``~/.bashrc`` file:: +Then, insert the hombrew directory at the top of your ``PATH`` enviornment +variable. You can do this by adding the following line at the bottom of your +``~/.bashrc`` file:: export PATH=/usr/local/bin:$PATH @@ -30,19 +43,31 @@ Now, we can install Python 2.7: :: $ brew install python --framework -This will take a minute or two. Once that's complete, you'll have to add the new Python scripts directory to your ``PATH``:: +This will take a minute or two. Once that's complete, you'll have to add the +new Python scripts directory to your ``PATH``:: export PATH=/usr/local/share/python:$PATH -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. +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. Distribute & Pip ---------------- -The most crucial third-party Python software of all is Distribute, which extends the packaging and installation facilities provided by the distutils in the standard library. Once you add Distribute to your Python system you can download and install any compliant Python software product with a single command. It also enables you to add this network installation capability to your own Python software with very little work. +The most crucial third-party Python software of all is Distribute, which +extends the packaging and installation facilities provided by the distutils +in the standard library. Once you add Distribute to your Python system you can +download and install any compliant Python software product with a single +command. It also enables you to add this network installation capability to +your own Python software with very little work. -Hombrew already installed Distribute for you. Its ``easy_install`` command is considered by many to be deprecated, so we will install its replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. +Hombrew already installed Distribute for you. Its ``easy_install`` command is +considered by many to be deprecated, so we will install its replacement: +**pip**. Pip allows for uninstallation of packages, and is actively maintained, +unlike easy_install. To install pip, simply open a command prompt and run:: @@ -52,21 +77,37 @@ To install pip, simply open a command prompt and run:: Virtualenv ---------- -After Distribute & Pip, the next development tool that you should install is `virtualenv `_. Use pip:: +After Distribute & Pip, the next development tool that you should install is +`virtualenv `_. Use pip:: $ pip install virtualenv -The virtualenv kit provides the ability to create virtual Python environments that do not interfere with either each other, or the main Python installation. If you install virtualenv before you begin coding then you can get into the habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. +The virtualenv kit provides the ability to create virtual Python environments +that do not interfere with either each other, or the main Python installation. +If you install virtualenv before you begin coding then you can get into the +habit of using it to create completely clean Python environments for each +project. This is particularly important for Web development, where each +framework and application will have many dependencies. -To set up a new Python environment, change the working directory to where ever you want to store the environment, and run the virtualenv utility in your project's directory:: +To set up a new Python environment, change the working directory to where ever +you want to store the environment, and run the virtualenv utility in your +project's directory:: $ virtualenv --distribute venv -To use an environment, run ``source venv/bin/activate``. Your command prompt will change to show the active environment. Once you have finished working in the current virtual environment, run ``deactivate`` to restore your settings to normal. +To use an environment, run ``source venv/bin/activate``. Your command prompt +will change to show the active environment. Once you have finished working in +the current virtual environment, run ``deactivate`` to restore your settings +to normal. -Each new environment automatically includes a copy of ``pip``, so that you can setup the third-party libraries and tools that you want to use in that environment. Put your own code within a subdirectory of the environment, however you wish. When you no longer need a particular environment, simply copy your code out of it, and then delete the main directory for the environment. +Each new environment automatically includes a copy of ``pip``, so that you can +setup the third-party libraries and tools that you want to use in that +environment. Put your own code within a subdirectory of the environment, +however you wish. When you no longer need a particular environment, simply +copy your code out of it, and then delete the main directory for the environment. -------------------------------- -This page is a remixed version of `another guide `_, which is available under the same license. +This page is a remixed version of `another guide `_, +which is available under the same license. diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index 3d3602c..c6ec8b9 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -3,13 +3,24 @@ Installing Python on Windows ============================ -First, download the `latest version `_ of Python 2 from the official Website. +First, download the `latest version `_ +of Python 2 from the official Website. -The Windows version is provided as an MSI package. To install it manually, just double-click the file. The MSI package format allows Windows administrators to automate installation with their standard tools. +The Windows version is provided as an MSI package. To install it manually, just + double-click the file. The MSI package format allows Windows administrators to + automate installation with their standard tools. -By design, Python installs to a directory with the version number embedded, e.g. ``C:\Python27\``, so that you can have multiple versions of Python on the same system without conflicts. Of course, only one interpreter can be the default application for Python file types. It also does not automatically modify the ``PATH`` environment variable, so that you always have control over which copy of Python is run. +By design, Python installs to a directory with the version number embedded, +e.g. ``C:\Python27\``, so that you can have multiple versions of Python on the +same system without conflicts. Of course, only one interpreter can be the +default application for Python file types. It also does not automatically +modify the ``PATH`` environment variable, so that you always have control over +which copy of Python is run. -Typing the full path name for a Python interpreter each time quickly gets tedious, so add the directories for your default Python version to the PATH. Assuming that your Python installation is in ``C:\Python27\``, add this to your PATH:: +Typing the full path name for a Python interpreter each time quickly gets +tedious, so add the directories for your default Python version to the PATH. +Assuming that your Python installation is in ``C:\Python27\``, add this to your +PATH:: C:\Python27\;C:\Python27\Scripts\ @@ -17,18 +28,31 @@ You can do this easily by running the following in ``powershell``:: [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27\;C:\Python27\Scripts\", "User") -You do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the next section before you start building Python applications for real-world use. In particular, you should always install Distribute, as it makes it much easier for you to use other third-party Python libraries. +You do not need to install or configure anything else to use Python. Having +said that, I would strongly recommend that you install the tools and libraries +described in the next section before you start building Python applications for +real-world use. In particular, you should always install Distribute, as it +makes it much easier for you to use other third-party Python libraries. Distribute + Pip ---------------- -The most crucial third-party Python software of all is Distribute, which extends the packaging and installation facilities provided by the distutils in the standard library. Once you add Distribute to your Python system you can download and install any compliant Python software product with a single command. It also enables you to add this network installation capability to your own Python software with very little work. +The most crucial third-party Python software of all is Distribute, which +extends the packaging and installation facilities provided by the distutils in +the standard library. Once you add Distribute to your Python system you can +download and install any compliant Python software product with a single +command. It also enables you to add this network installation capability to +your own Python software with very little work. -To obtain the latest version of Distribute for Windows, run the python script available here: +To obtain the latest version of Distribute for Windows, run the python script +available here: http://python-distribute.org/distribute_setup.py -You'll now have a new command available to you: **easy_install**. It is considered by many to be deprecated, so we will install its replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. +You'll now have a new command available to you: **easy_install**. It is +considered by many to be deprecated, so we will install its replacement: +**pip**. Pip allows for uninstallation of packages, and is actively maintained, +unlike easy_install. To install pip, simply open a command prompt and run:: @@ -38,23 +62,41 @@ To install pip, simply open a command prompt and run:: Virtualenv ---------- -After Distribute & Pip, the next development tool that you should install is `virtualenv `_. Use pip:: +After Distribute & Pip, the next development tool that you should install is +`virtualenv `_. Use pip:: > pip install virtualenv -The virtualenv kit provides the ability to create virtual Python environments that do not interfere with either each other, or the main Python installation. If you install virtualenv before you begin coding then you can get into the habit of using it to create completely clean Python environments for each project. This is particularly important for Web development, where each framework and application will have many dependencies. +The virtualenv kit provides the ability to create virtual Python environments +that do not interfere with either each other, or the main Python installation. +If you install virtualenv before you begin coding then you can get into the +habit of using it to create completely clean Python environments for each +project. This is particularly important for Web development, where each +framework and application will have many dependencies. -To set up a new Python environment, change the working directory to where ever you want to store the environment, and run the virtualenv utility in your project's directory:: +To set up a new Python environment, change the working directory to where ever +you want to store the environment, and run the virtualenv utility in your +project's directory:: > virtualenv --distribute venv -To use an environment, run the ``activate.bat`` batch file in the ``Scripts`` subdirectory of that environment. Your command prompt will change to show the active environment. Once you have finished working in the current virtual environment, run the ``deactivate.bat`` batch file to restore your settings to normal. +To use an environment, run the ``activate.bat`` batch file in the ``Scripts`` +subdirectory of that environment. Your command prompt will change to show the +active environment. Once you have finished working in the current virtual +environment, run the ``deactivate.bat`` batch file to restore your settings to +normal. -Each new environment automatically includes a copy of ``pip`` in the ``Scripts`` subdirectory, so that you can setup the third-party libraries and tools that you want to use in that environment. Put your own code within a subdirectory of the environment, however you wish. When you no longer need a particular environment, simply copy your code out of it, and then delete the main directory for the environment. +Each new environment automatically includes a copy of ``pip`` in the +``Scripts`` subdirectory, so that you can setup the third-party libraries and +tools that you want to use in that environment. Put your own code within a +subdirectory of the environment, however you wish. When you no longer need a +particular environment, simply copy your code out of it, and then delete the +main directory for the environment. -------------------------------- -This page is a remixed version of `another guide `_, which is available under the same license. +This page is a remixed version of `another guide `_, +which is available under the same license. diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index c22ced8..6698172 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -3,12 +3,18 @@ Properly Installing Python There's a good chance that you already have Python on your operating system. -If so, you do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the guides below before you start building Python applications for real-world use. In particular, you should always install Distribute, Pip, and Virtualenv — they make it much easier for you to use other third-party Python libraries. +If so, you do not need to install or configure anything else to use Python. +Having said that, I would strongly recommend that you install the tools and +libraries described in the guides below before you start building Python +applications for real-world use. In particular, you should always install +Distribute, Pip, and Virtualenv — they make it much easier for you to use +other third-party Python libraries. Installation Guides ------------------- -These guides go over the proper installation of :ref:`Python 2.7 ` for development purposes, as well as distribute, pip, and virtualenv setup. +These guides go over the proper installation of :ref:`Python 2.7 ` + for development purposes, as well as distribute, pip, and virtualenv setup. - :ref:`Mac OS X `. - :ref:`Microsoft Windows`. diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index f5be900..42e1ca3 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -16,7 +16,8 @@ Which Python to use? 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. +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 From 6978c5a1ae39404a2bbb1a41f2dc71fe74a3e95c Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 20:15:00 +0200 Subject: [PATCH 44/58] correct code-block highlighting and link formatting --- docs/starting/install/linux.rst | 15 ++++++++++----- docs/starting/install/osx.rst | 24 ++++++++++++++++++------ docs/starting/install/win.rst | 15 ++++++++++----- 3 files changed, 38 insertions(+), 16 deletions(-) diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index a3d88bf..06aeb9e 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -22,14 +22,15 @@ command. It also enables you to add this network installation capability to your own Python software with very little work. To obtain the latest version of Distribute for Linux, run the python script -available here: - http://python-distribute.org/distribute_setup.py +available here: `python-distribute `_ The new``easy_install`` command you have available is considered by many to be deprecated, so we will install its replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. -To install pip, simply open a command prompt and run:: +To install pip, simply open a command prompt and run + +.. code-block:: console $ easy_install pip @@ -38,7 +39,9 @@ Virtualenv ---------- After Distribute & Pip, the next development tool that you should install is -`virtualenv `_. Use pip:: +`virtualenv `_. Use pip + +.. code-block:: console $ pip install virtualenv @@ -51,7 +54,9 @@ framework and application will have many dependencies. To set up a new Python environment, change the working directory to where ever you want to store the environment, and run the virtualenv utility in your -project's directory:: +project's directory + +.. code-block:: console $ virtualenv --distribute venv diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 006f2e0..ec8c9a8 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -29,13 +29,17 @@ Linux systems will notice one key component missing: a decent package manager. `Homebrew `_ fills this void. To `install Homebrew `_, -simply run:: +simply run + +.. code-block:: console $ ruby -e "$(curl -fsS https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)" Then, insert the hombrew directory at the top of your ``PATH`` enviornment variable. You can do this by adding the following line at the bottom of your -``~/.bashrc`` file:: +``~/.bashrc`` file + +.. code-block:: console export PATH=/usr/local/bin:$PATH @@ -44,7 +48,9 @@ Now, we can install Python 2.7: :: $ brew install python --framework This will take a minute or two. Once that's complete, you'll have to add the -new Python scripts directory to your ``PATH``:: +new Python scripts directory to your ``PATH`` + +.. code-block:: console export PATH=/usr/local/share/python:$PATH @@ -69,7 +75,9 @@ considered by many to be deprecated, so we will install its replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. -To install pip, simply open a command prompt and run:: +To install pip, simply open a command prompt and run + +.. code-block:: console $ easy_install pip @@ -78,7 +86,9 @@ Virtualenv ---------- After Distribute & Pip, the next development tool that you should install is -`virtualenv `_. Use pip:: +`virtualenv `_. Use pip + +.. code-block:: console $ pip install virtualenv @@ -91,7 +101,9 @@ framework and application will have many dependencies. To set up a new Python environment, change the working directory to where ever you want to store the environment, and run the virtualenv utility in your -project's directory:: +project's directory + +.. code-block:: console $ virtualenv --distribute venv diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index c6ec8b9..5ce42f7 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -45,8 +45,7 @@ command. It also enables you to add this network installation capability to your own Python software with very little work. To obtain the latest version of Distribute for Windows, run the python script -available here: - http://python-distribute.org/distribute_setup.py +available here: `python-distribute `_ You'll now have a new command available to you: **easy_install**. It is @@ -54,7 +53,9 @@ considered by many to be deprecated, so we will install its replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. -To install pip, simply open a command prompt and run:: +To install pip, simply open a command prompt and run + +.. code-block:: console > easy_install pip @@ -63,7 +64,9 @@ Virtualenv ---------- After Distribute & Pip, the next development tool that you should install is -`virtualenv `_. Use pip:: +`virtualenv `_. Use pip + +.. code-block:: console > pip install virtualenv @@ -77,7 +80,9 @@ framework and application will have many dependencies. To set up a new Python environment, change the working directory to where ever you want to store the environment, and run the virtualenv utility in your -project's directory:: +project's directory + +.. code-block:: console > virtualenv --distribute venv From 70ca1a8cef2590931cdd258d0ac0d83c09d78e01 Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 20:24:39 +0200 Subject: [PATCH 45/58] lines less than 80 chars in /writing/ --- docs/writing/documentation.rst | 12 ++++++--- docs/writing/license.rst | 6 +++-- docs/writing/style.rst | 30 ++++++++++++--------- docs/writing/tests.rst | 48 ++++++++++++++++++---------------- 4 files changed, 55 insertions(+), 41 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 28edaf4..7ec1ce2 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -38,7 +38,8 @@ Docstrings 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. +There are two types of docstrings, one-line and multi-line. Their names +should be fairly self explanatory. One-line docstrings: :: def kos_root(): @@ -63,7 +64,9 @@ Multi-line docstrings: :: Sphinx ------ -Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text. +Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` +markup language into a range of output formats including HTML, LaTeX (for +printable PDF versions), manual pages and plain text. .. note:: This Guide is built with Sphinx_ @@ -75,7 +78,10 @@ Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref reStructuredText ---------------- -Most Python documentation is written with reStructuredText_. The `reStructuredText Primer `_ and the `reStructuredText Quick Reference `_ should help you familiarize yourself with its syntax. +Most Python documentation is written with reStructuredText_. The +`reStructuredText Primer `_ and the +`reStructuredText Quick Reference `_ +should help you familiarize yourself with its syntax. .. _reStructuredText: http://docutils.sourceforge.net/rst.html diff --git a/docs/writing/license.rst b/docs/writing/license.rst index e7c8ae3..a66e137 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -3,9 +3,11 @@ Choosing a License Open source. -There are plenty of `open source licenses `_ available to choose from. +There are plenty of `open source licenses `_ +available to choose from. -To help you choose one for your project, there's a `license chooser `_, use it. +To help you choose one for your project, there's a `license chooser `_, +use it. Non-Restrictive diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 67a9b1f..7793b85 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -261,7 +261,8 @@ keep a count of your place in the list. # 1, 4 # 2, 5 -The ``enumerate`` function has better readability than handling a counter manually. Moreover, +The ``enumerate`` function has better readability than handling a counter +manually. Moreover, it is better optimized for iterators. Read From a File @@ -287,8 +288,8 @@ files for you. for line in f: print line -The ``with`` statement is better because it will ensure you always close the file, -even if an exception is raised. +The ``with`` statement is better because it will ensure you always close the +file, even if an exception is raised. Returning Multiple Values from a Function ----------------------------------------- @@ -320,15 +321,17 @@ values in before you return Line Continuations ~~~~~~~~~~~~~~~~~~ -When a logical line of code is longer than the accepted limit, you need to split it over multiple -physical lines. Python interpreter will join consecutive lines if the last character of the line is -a backslash. This is helpful sometime but is preferably avoided, because of its fragility: a white -space added to the end of the line, after the backslash, will break the code and may have unexpected -results. +When a logical line of code is longer than the accepted limit, you need to +split it over multiple physical lines. Python interpreter will join consecutive +lines if the last character of the line is a backslash. This is helpful +sometime but is preferably avoided, because of its fragility: a white space +added to the end of the line, after the backslash, will break the code and may +have unexpected results. -A prefered solution is to use parenthesis around your elements. Left with an unclosed parenthesis on an end-of-line -the Python interpreter will join the next line until the parenthesis is closed. The same behavior holds for -curly and square braces. +A prefered solution is to use parenthesis around your elements. Left with an +unclosed parenthesis on an end-of-line the Python interpreter will join the +next line until the parenthesis is closed. The same behavior holds for curly +and square braces. **Bad**: @@ -352,5 +355,6 @@ curly and square braces. from some.deep.module.inside.a.module import (a_nice_function, another_nice_function, yet_another_nice_functio) -However, more often than not having to split long logical line is a sign that you -are trying to do too many things at the same time, which may hinder readability. +However, more often than not having to split long logical line is a sign that +you are trying to do too many things at the same time, which may hinder +readability. diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 81e7e32..717d26e 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -21,9 +21,10 @@ Some general rules of testing: - Try hard to make tests that run fast. If one single test needs more than a few millisecond to run, development will be slowed down or the tests will not be run as often as desirable. In some cases, test can't be fast because they - need a complex data structure to work on, and this data structure must be loaded - every time the test runs. Keep these heavier tests in a separate test suite - that is run by some scheduled task, and run all other tests as often as needed. + need a complex data structure to work on, and this data structure must be + loaded every time the test runs. Keep these heavier tests in a separate test + suite that is run by some scheduled task, and run all other tests as often + as needed. - Learn your tools and learn how to run a single test or a test case. Then, when developing a function inside a module, run this function's tests very @@ -41,9 +42,9 @@ Some general rules of testing: When comming back to work, you will have a pointer to where you were and get faster on tracks. -- The first step when you are debugging your code is to write a new test pinpointing - the bug. While it is not always possible to do, those bug catching test are among - the most valuable piece of code in your project. +- The first step when you are debugging your code is to write a new test + pinpointing the bug. While it is not always possible to do, those bug + catching test are among the most valuable piece of code in your project. - Use long and descriptive names for testing functions. The style guide here is slighlty different than that of running code, where short names are often @@ -62,10 +63,10 @@ Some general rules of testing: - Another use of the testing code is as an introduction to new developers. When someone will have to work on the code base, runnning and reading the related testing code is often the best they can do. They will or should discover the - hot spots, where most difficulties arise, and the corner cases. If they have to - add some functionality, the first step should be to add a test and, by this mean, - ensure the new functionality is not already a working path that has not been - plugged in the interface. + hot spots, where most difficulties arise, and the corner cases. If they have + to add some functionality, the first step should be to add a test and, by this + mean, ensure the new functionality is not already a working path that has not + been plugged in the interface. The Basics :::::::::: @@ -99,15 +100,15 @@ 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 in docstrings, and then executes those sessions to verify that they work exactly as -shown. +The doctest module searches for pieces of text that look like interactive +Python sessions in docstrings, and then executes those sessions to verify that +they work exactly as shown. -Doctests have a different use case than proper unit tests: they are usually less -detailed and don't catch special cases or obscure regression bugs. They are -useful as an expressive documentation of the main use cases of a module and -its components. However, doctests should run automatically each time -the full test suite runs. +Doctests have a different use case than proper unit tests: they are usually +less detailed and don't catch special cases or obscure regression bugs. They +are useful as an expressive documentation of the main use cases of a module and +its components. However, doctests should run automatically each time the full +test suite runs. A simple doctest in a function: @@ -128,8 +129,9 @@ A simple doctest in a function: import doctest doctest.testmod() -When running this module from the command line as in ``python module.py``, the doctests -will run and complain if anything is not behaving as described in the docstrings. +When running this module from the command line as in ``python module.py``, the +doctests will run and complain if anything is not behaving as described in the +docstrings. Tools ::::: @@ -144,7 +146,7 @@ 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 +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 @@ -205,8 +207,8 @@ 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 +tox is a tool for automating test environment management and testing against +multiple interpreter configurations :: From 4d12bfed0cac5603fab2c22902147cf955eb57f4 Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 20:32:00 +0200 Subject: [PATCH 46/58] lines less than 80 chars in /scenarios/ --- docs/scenarios/ci.rst | 32 +++++++++++++----- docs/scenarios/client.rst | 21 +++++++++--- docs/scenarios/db.rst | 12 ++++--- docs/scenarios/gui.rst | 10 +++--- docs/scenarios/scientific.rst | 62 +++++++++++++++++++++-------------- docs/scenarios/speed.rst | 30 ++++++++++------- docs/scenarios/web.rst | 20 +++++------ 7 files changed, 118 insertions(+), 69 deletions(-) diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index e8e11c2..659f440 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -5,20 +5,29 @@ Continuous Integration Why? ---- -Martin Fowler, who first wrote about `Continuous Integration `_ (short: CI) together with Kent Beck, describes the CI as follows: +Martin Fowler, who first wrote about `Continuous Integration `_ +(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. + 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. +`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. +`Buildbot `_ is a Python system to +automate the compile/test cycle to validate code changes. Mule? @@ -29,12 +38,17 @@ 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: +`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. +* 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. Travis-CI diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst index db0d28a..e2d8202 100644 --- a/docs/scenarios/client.rst +++ b/docs/scenarios/client.rst @@ -6,14 +6,23 @@ Network Applications HTTP :::: -The Hypertext Transfer Protocol (HTTP) is an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web. +The Hypertext Transfer Protocol (HTTP) is an application protocol for +distributed, collaborative, hypermedia information systems. HTTP is the +foundation of data communication for the World Wide Web. Requests -------- -Python’s standard urllib2 module provides most of the HTTP capabilities you need, but the API is thoroughly broken. It was built for a different time — and a different web. It requires an enormous amount of work (even method overrides) to perform the simplest of tasks. +Python’s standard urllib2 module provides most of the HTTP capabilities you +need, but the API is thoroughly broken. It was built for a different time — +and a different web. It requires an enormous amount of work (even method +overrides) to perform the simplest of tasks. -Requests takes all of the work out of Python HTTP — making your integration with web services seamless. There’s no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by urllib3, which is embedded within Requests +Requests takes all of the work out of Python HTTP — making your integration +with web services seamless. There’s no need to manually add query strings to +your URLs, or to form-encode your POST data. Keep-alive and HTTP connection +pooling are 100% automatic, powered by urllib3, which is embedded within +Requests. - `Documention `_ - `PyPi `_ @@ -27,4 +36,8 @@ Distributed Systems ZeroMQ ------ -ØMQ (also spelled ZeroMQ, 0MQ or ZMQ) is a high-performance asynchronous messaging library aimed at use in scalable distributed or concurrent applications. It provides a message queue, but unlike message-oriented middleware, a ØMQ system can run without a dedicated message broker. The library is designed to have a familiar socket-style API. +ØMQ (also spelled ZeroMQ, 0MQ or ZMQ) is a high-performance asynchronous +messaging library aimed at use in scalable distributed or concurrent +applications. It provides a message queue, but unlike message-oriented +middleware, a ØMQ system can run without a dedicated message broker. The +library is designed to have a familiar socket-style API. diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index b77ddd6..2c4c17b 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -14,9 +14,9 @@ Nearly all Python database modules such as `sqlite3`, `psycopg` and 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. +`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. :: @@ -25,8 +25,10 @@ database-agnostic code without SQL. Django ORM ---------- -The Django ORM is the interface used by `Django `_ to provide database access. +The Django ORM is the interface used by `Django `_ +to provide database access. -It's based on the idea of models, an abstraction that makes it easier to manipulate data in Python. +It's based on the idea of models, an abstraction that makes it easier to +manipulate data in Python. Documentation can be found `here `_ \ No newline at end of file diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 2490d98..8a08e68 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -4,7 +4,8 @@ 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. +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 ------ @@ -30,15 +31,16 @@ WXPython Install (Stable) ---------------- -*Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.* +*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. +recommended that PyGTK is not used for new projects and existing applications +be ported from PyGTK to PyGObject. Tk :: diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 3b038ad..c549190 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -5,59 +5,71 @@ 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. +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 +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 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 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+. +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. +`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. +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 ---------- -`matplotlib `_ is a flexible plotting library -for creating interactive 2D and 3D plots that can also be saved as manuscript-quality -figures. The API in many ways reflects that of `MATLAB `_, easing transition of MATLAB -users to Python. Many examples, along with the source code to re-create them, -can be browsed at the `matplotlib gallery `_. +`matplotlib `_ is a flexible plotting +library for creating interactive 2D and 3D plots that can also be saved as +manuscript-quality figures. The API in many ways reflects that of `MATLAB `_, +easing transition of MATLAB users to Python. Many examples, along with the +source code to re-create them, can be browsed at the `matplotlib gallery `_. PyQwt ----- `PyQwt `_ is a solid library for plotting -numerical data. It is built on top of the popular `PyQt `_ GUI framework. -It typically has better performance than matplotlib, but the range of built-in -chart/plot types is slightly smaller than matplotlib. +numerical data. It is built on top of the popular `PyQt `_ +GUI framework. It typically has better performance than matplotlib, but the +range of built-in chart/plot types is slightly smaller than 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. +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. diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index bd83cde..f0d6c78 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -1,13 +1,16 @@ Speed ===== -CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. `PyPy`_ is fast. +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. +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 $ ./pypy -V Python 2.7.1 (7773f8fc4223, Nov 18 2011, 18:47:10) [PyPy 1.7.0 with GCC 4.4.3] @@ -23,7 +26,7 @@ Using a slightly modified version of `David Beazleys`_ CPU bound test code(added CPython $ ./python -V Python 2.7.1 - $ ./python measure2.py + $ ./python measure2.py 1.06774401665 1.45412397385 1.51485204697 @@ -37,13 +40,16 @@ 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. +`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. +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 ------------ @@ -52,8 +58,8 @@ C Extentions The GIL ------- -`Special care`_ must be taken when writing C extensions to make sure you register your threads -with the interpreter. +`Special care`_ must be taken when writing C extensions to make sure you r +egister your threads with the interpreter. C Extentions :::::::::::: diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index bd65373..7b20c7d 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -14,8 +14,8 @@ 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 `_. +can be deployed in any :ref:`WSGI-compliant web server `. +WSGI is documented in `PEP-3333 `_. Frameworks @@ -71,8 +71,8 @@ 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. +**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 @@ -126,8 +126,8 @@ 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 +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 @@ -158,10 +158,10 @@ Heroku `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 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 From d69bbe07222d16f7453b0837744081b8dc0bcd50 Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Mon, 23 Apr 2012 20:32:41 +0200 Subject: [PATCH 47/58] lines less than 80 chars in index.rst --- docs/index.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index a1b1d4d..325eedd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,8 +8,11 @@ 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 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. +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 From 8ad935e6098bc2b33322bf248bcda3283381021c Mon Sep 17 00:00:00 2001 From: guibog Date: Tue, 24 Apr 2012 22:44:30 +0800 Subject: [PATCH 48/58] About module and packages in Structure --- docs/writing/structure.rst | 112 +++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index a640277..c1478bc 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -57,8 +57,120 @@ include: task at hand, you might be swimming in ravioli code. +Modules +------- + +Python modules are one of the main abstraction layer available and probably the +most natural one. Abstraction layers allow separating code into parts holding +related data and functionalities. + +For example, a layer of a project can handle interfacing with user actions, +while another would handle low-level manipulation of data. The most natural way +to separate these two layers is to regroup all interfacing functionalities +in one file, and all low-level operations in another file. In this case, +the interface file need to import the low-level file. This is done with the +`import` and `from ... import` statements. + +As soon as you use `import` statements you use modules, either builtin modules +such as `os` and `sys`, or third-party modules you have installed in your +environment, or project's internal modules. + +Nothing special is required for a Python file to be a module, but the import +mechanism need to be understood in order to use this concept properly and avoid +some issues. + +Concretely, the `import modu` statement will look for the proper file, which is +`modu.py` in the same directory as the caller if it exists. If it is not +found, the Python interpreter with search for `modu.py` in the "path" +recursively and raise an ImportError exception if it is not found. + +Once `modu.py` is found, the Python interpreter will execute the module in an +isolated scope. Any top-level statement in `modu.py` will be executed, +including other imports if any. Function and classes definitions are stored in +the module's dictionary. + +Then modules variables, functions and classes will be available to the caller +through the module's namespace, a central concept in programming that is +particularly helpful and powerful in Python. + +In many languages, a `include file` directive is used by the preprocessor to +take all code found in the file and 'copy' it in the caller's code. It is +different in Python: the included code is isolated in a module namespace, which +means that you generally don't have to worry that the included code could have +unwanted effect, eg override an existing function with the same name. + +It is possible to simulate the more standard behavior by using a special syntax +of the import statement: `from modu import *`. This is generally considered bad +practice, **using import * makes code harder to read and dependencies less +compartimented**. + +Using `from modu import func` is a way to pinpoint the function you want to +import and put it is the global namespace. While much less harmful than `import +*` because it shows explicitely what is imported in the global namespace, it's +advantage over a simpler `import modu` is only that it will save some typing. + +**Very bad** + +.. code-block:: python + + [...] + from modu import * + [...] + x = sqrt(4) # Is sqrt part of modu? A builtin? Defined above? + +**Better** + +.. code-block:: python + + from modu import sqrt + [...] + x = sqrt(4) # sqrt may be part of modu, if not redefined in between + +**Best** + +.. code-block:: python + + import modu + [...] + x = modu.sqrt(4) # sqrt is visibly part of modu's namespace + +As said in the section about style, readability is one of the main feature of +Python. Readability means to avoid useless boilerplate text and clutter, +therefore some efforts are spent trying to achieve a certain level of brevity. +But terseness and obscurity are the limits where brevity should stop: being +able to tell immediately from where comes a class or a function, as in the +`modu.func` idiom, improves greatly code readability and understandability in +most cases but the simplest single file projects. +Packages -------- + +Python provides a very straightforward packaging system, which is simply an +extension of the module mechanism to a directory. + +Any directory with a __init__.py file is considered a Python package. The +different modules in the package are imported in a similar manner as plain +modules, will a special behavior for the __init__.py file, that is used to +gather all package-wide definitions. + +A file modu.py in the directory pack/ is imported with the statement `import +pack.modu`. This statement will look for a __init__.py file in `pack`, execute +all its top-level statements. Then it will look for a file `pack/modu.py` and +execute all its top-level statements. After these operations, any variable, +function or class defined in modu.py is available in pack.modu namespace. + +A commonly seen issue is to add too many code and functions in __init__.py +files. When the project complexity grows, there may be sub-packages and +sub-sub-packages in a deep directory structure, and then, import a single item +from a sub-sub-package will require to execute all __init__.py file met while +descending the tree. + +Leaving a __init__.py file empty is considered normal and even a good pratice, +if the package's modules and sub-packages do not need to share any code. + +Lastly, a convenient syntax is available for importing deeply nested packages: +`import very.deep.module as mod` allow to use `mod` in place of the verbose +repetition of `very.deep.module` in front of each calls to module items. Vendorizing Dependencies ------------------------ From 8777ae2ae700ecd7b7de362777727af1ebd645af Mon Sep 17 00:00:00 2001 From: Paul Smith Date: Tue, 24 Apr 2012 14:07:37 -0400 Subject: [PATCH 49/58] Fix typos --- docs/starting/install/osx.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index ec8c9a8..136a4bb 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -35,7 +35,7 @@ simply run $ ruby -e "$(curl -fsS https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)" -Then, insert the hombrew directory at the top of your ``PATH`` enviornment +Then, insert the Homebrew directory at the top of your ``PATH`` enviornment variable. You can do this by adding the following line at the bottom of your ``~/.bashrc`` file @@ -70,7 +70,7 @@ download and install any compliant Python software product with a single command. It also enables you to add this network installation capability to your own Python software with very little work. -Hombrew already installed Distribute for you. Its ``easy_install`` command is +Homebrew already installed Distribute for you. Its ``easy_install`` command is considered by many to be deprecated, so we will install its replacement: **pip**. Pip allows for uninstallation of packages, and is actively maintained, unlike easy_install. From caf217407600a6f892f0c565cea3972c9fef849d Mon Sep 17 00:00:00 2001 From: Andrew Szeto Date: Wed, 25 Apr 2012 01:51:18 -0700 Subject: [PATCH 50/58] done with docs --- docs/intro/duction.rst | 51 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 0bd99e7..6a6b62c 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -1,7 +1,56 @@ Introduction ============ -.. todo:: write a general blurb introducing the Python language +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 + `stanadard 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 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: From 50cd751e840dcc71c0a164ca9fcc336ec96da0d8 Mon Sep 17 00:00:00 2001 From: Andrew Szeto Date: Wed, 25 Apr 2012 01:58:07 -0700 Subject: [PATCH 51/58] done with introduction --- docs/intro/community.rst | 2 ++ docs/intro/duction.rst | 8 ++++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/intro/community.rst b/docs/intro/community.rst index 329d867..c9635c0 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -1,3 +1,5 @@ +.. _the_community: + The Community ============= diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 6a6b62c..83b3aa7 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -46,10 +46,10 @@ include: * friendly community - Python has a vibrant and large 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! + 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: From 68fc11453ae12f890255564f016c44e32da6a0b7 Mon Sep 17 00:00:00 2001 From: guibog Date: Wed, 25 Apr 2012 23:17:40 +0800 Subject: [PATCH 52/58] Add on documentation and comments --- docs/writing/documentation.rst | 124 ++++++++++++++++++++++++++++++++- 1 file changed, 122 insertions(+), 2 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 7ec1ce2..b27f8da 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -1,8 +1,128 @@ Documenting Your Code ===================== -Documenting your code is extremely important. It is debatably even -more important than testing. +With readability of the code being a main focus for Python developers, proper +commenting is naturally important. Some best practice apply to code comments +and project documents, depending on the scope of the project. + +Project documents +----------------- + +A README file at the root directory give general information to the users and +the maintainers. It should be raw text or written in some very easy to read +markup, such as reStructuredText and Markdown. It should contain a few lines +explaining the purpose of the project or the library (without assuming the user +knows anything about the project), the url of the main source for the software, +and some basic credit information. This file is the main entry point for +readers of the code. + +An INSTALL file is less often necessary with python, except if the dependencies +are complex or unusual, or if some C modules need to be compiled before use. +The installation instructions are often reduced to one command, such as ``pip +install module`` or ``python setup.py install`` and added to the README file. + +A LICENSE file should always be present and specify the license under which the +software is made available to the public. + +A TODO file or a TODO section in README should list the planned modifications +of the code. + +A CHANGELOG file or section in README should compile a short overview of the +changes in the code base for the latest versions. + +Documentation +------------- + +As the project or library reaches a certain level of complexity, it may require +a fuller documentation, which can be of different flavors: + +The introduction may show a very short overview of what can be done with the +product, using one or two extremely simplified use cases. + +The tutorials will show in more details some main use cases. The reader will +follow a step-by-step procedure to set-up a working prototype. + +The API reference, which is often generated automatically from the code, will +list all publicly available interfaces, their parameters and their return +values, with an explanation of their use. + +Some documents intended for developers might give guidance about code +convention and general design decision of the project. + +Comments +-------- + +Comments are written directly inside the code, either using the hash sign (#) +or a docstring_. + +Finding the correct balance between undocumented code and verbose and useless +comment boilerplates is difficult, and is the subject of heated discussion +among developers. + +The following guidelines seem to be most commonly agreed upon: + +**Wrong or outdated comments are worse than no comments at all.** Following the +saying that it is better, on a boat, to know that we do not know were we are +than to wrongly believe we know where we are, wrong or outdated comments can be +misleading for the maintainers, slow down considerably bug hunting or +refactoring, and then, when discovered wrong, they will throw suspicion on all +other comments in the code, regardless of their individual correctness. + +**No need comments for perfect code...** An hypothetical perfectly readable +code, with a crystal clear logic stream, expressive variable and function +names, orthogonal segmentation passing exactly between the flesh and the bones, +and no implicit assumptions of any kind, would not require any comment at all. +When striving for coding excellence, it is useful to see any existing comment, +or any feeling of a need for a comment, as the sign that the code do not +express clearly enough its intent and can be improved. + +**.. but no code is perfect.** Perfect code is a chimere, it exists only in +our dreams. In real life, a code base is full of trade offs, and comments are +often needed in the most difficult parts. Moreover, any special case, any +obscure hack, any monkey patch and any ugly workaround MUST be signaled and +explained by a proper comment. This should be enforced by the law! + +**TODOs** are special comments that a developer write as a reminder for later +use. It is said that its original intent was that someone might, one day, +search for the string "TODO" in the code base and actually roll their sleeves +and start *to do the TODOs*. There is no avalaible record that it ever +happened. However, TODOs comment are still very useful, because they mark the +current limits of the code, and it is not unlikely that, when required to add a +new behavior to the actual code, looking at the TODOs will show where to start. + +**Do not use triple-quote strings to comment code.** A common operation when +modifiying code is to comment out some lines or even a full function or class +definition. This can be done by adding triple-quotes around the code block to +be skipped, but this is not a good pratice, because line-oriented command-line +tools such as ``grep`` will not be aware that the commented code is inactive. +It is better to add hashes at the proper indentation level for every commented +line. Good editors allow to do this with few keystrokes (ctrl-v on Vim). + +**Bad** + +.. code-block:: python + + def tricky_function(): + ''' + if foo: + do_bar() + ''' + return baz + + def tricky_function(): + #if foo: + #do_bar() + return baz + +**Good** + +.. code-block:: python + + def tricky_function(): + #if foo: + # do_bar() + return baz + The Basics From 3d16bf82633c0563fb9d72bb2831693704ff2ddc Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 26 Apr 2012 02:53:21 -0400 Subject: [PATCH 53/58] panic not --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index a1b1d4d..31b6648 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ The Hitchhiker's Guide to Python! ================================= -Welcome to The Hitchhiker's Guide to Python. **DON'T PANIC!** +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 `_! From 61e948e8874bd2e11da5b6034ea59d01f9d75cfc Mon Sep 17 00:00:00 2001 From: guibog Date: Fri, 27 Apr 2012 21:40:25 +0800 Subject: [PATCH 54/58] Clarifying a bit on commented code --- docs/writing/documentation.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index b27f8da..c4cb0fd 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -104,26 +104,38 @@ line. Good editors allow to do this with few keystrokes (ctrl-v on Vim). def tricky_function(): ''' + Commented out because its breaks something. if foo: do_bar() ''' return baz def tricky_function(): + # Commented out because its breaks something. #if foo: #do_bar() return baz + + def tricky_function(): + # Commented out because its breaks something. + # if foo: + # do_bar() + return baz + **Good** .. code-block:: python def tricky_function(): + # Commented out because its breaks something. #if foo: # do_bar() return baz - +Note that comment text is properly written and separated from the hash by a +space. Commented code is not separated from the hash by an additional space; +this helps when uncommented the code. The Basics :::::::::: From b1bb63071f357a83c63ab5b58ad40b5464a72dfe Mon Sep 17 00:00:00 2001 From: guibog Date: Fri, 27 Apr 2012 22:40:21 +0800 Subject: [PATCH 55/58] About OOP --- docs/writing/structure.rst | 77 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index c1478bc..a0afbaf 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -172,6 +172,83 @@ Lastly, a convenient syntax is available for importing deeply nested packages: `import very.deep.module as mod` allow to use `mod` in place of the verbose repetition of `very.deep.module` in front of each calls to module items. +Object-oriented programming +--------------------------- + +Python is sometime described as an object-oriented programming language. This +can be somewhat misleading and need to be clarified. + +In Python, everything is an object, and can be handled as such. This is what is +meant when we say that, for example, functions are first-class objects. +Functions, classes, strings, and even types are objects in Python: like any +objects, they have a type, they can be passed as function arguments, they may +have methods and properties. In this understanding, Python is an +object-oriented language. + +However, unlike Java, Python do not impose object-oriented programming as the +main programming paradigm. It is perfectly viable for a Python project to not +be object-oriented, ie. to use no or very few class definitions, class +inheritance, and any other mechanism that are specific to object-oriented +programming. + +Moreover, as seen in the modules_ section, the way Python handles modules and +namespaces gives directly to the developer a natural way to ensure +encapsulation and separation of abstraction layers, both being the most common +reasons to use object-orientation. Therefore, Python programmers have more +latitude to not use object-orientation, when it is not required by the business +model to be constructed. + +There are some reasons to avoid unnecessary object-orientation. Definining +custom classes is useful when we want to glue together some state and some +functionality. The problem, as pointed out by the discussions about functional +programming, comes from the "state" part of the equation. + +In some architectures, typically web applications, instances of Python +processes are spawned simultaneously to answer to external requests that can +happen at the same time. In this case, holding some state into instanciated +objects, which means keeping some static information about the world, is prone +to concurrency problems or race-conditions: between the initialization of the +state of an object, usually done with the __init__() method, and the actual use +of the object state through one of its method, the world may have changed, and +the retained state may be outdated. For example, a request may load an item in +memory and mark it as read by a user. If another request requires the deletion +of this item at the same, it may happen that the deletion actually occur after +the first process loaded the item, and then we have to mark as read a deleted +object. + +This and other issues led to the idea that using stateless functions is a +better programming paradigm. + +Another way to say the same thing is to propose to use functions and procedures +with as few implicit context and side-effects as possible. A function's +implicit context is decelable when the function body refers to some global +variables or fetches data from the persistence layer. Side-effects are the +opposite: if a function body modifies the global context or save or delete data +on the persistence layer, it is said to have side-effect. + +Isolating carefully functions with context and side-effects from functions with +logic (called pure functions) allow the following benefits: + +- Pure functions are more likely to be deterministic: given a fixed input, + the output will always be the same. + +- Pure functions are much easier to change or replace if they need to + be refactored or optimized. + +- Pure functions are easier to test with unit-tests: There is less + need for complex context setup and data cleaning afterwards. + +- Pure functions are easier to manipulate, decorate_, pass-around. + +In summary, pure functions, without any context or side-effects, are more +efficient building blocks than classes and objects for some architectures. + +Obviously, object-orientation is useful and even necessary in many cases, for +example when developing graphical desktop applications or games, where the +things that are manipulated (windows, buttons, avatars, vehicles) have a +relatively long life of their own in the computer's memory. + + Vendorizing Dependencies ------------------------ From cbb365b6644aa4c911826e50ae723e5b89c81586 Mon Sep 17 00:00:00 2001 From: ajinkyadot Date: Mon, 30 Apr 2012 17:02:34 +0530 Subject: [PATCH 56/58] stylized wxPython correctly --- docs/scenarios/gui.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 8a08e68..90d882a 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -25,10 +25,9 @@ PyObjC ------ .. note:: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application. -WXPython +wxPython :::::::: - Install (Stable) ---------------- *Go to http://www.wxpython.org/download.php#stable and download the appropriate From 489d97e357ec4fa10847492ffc6f4c29ca7d67ee Mon Sep 17 00:00:00 2001 From: Vincent Noel Date: Thu, 3 May 2012 18:05:29 +0300 Subject: [PATCH 57/58] Missing double quote --- docs/writing/style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index d298ba4..47d3e52 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -500,7 +500,7 @@ and square braces. my_very_big_string = ("For a long time I used to go to bed early. Sometimes, " "when I had put out my candle, my eyes would close so quickly that I had not even " - time to say “I’m going to sleep.”") + "time to say “I’m going to sleep.”") from some.deep.module.inside.a.module import (a_nice_function, another_nice_function, yet_another_nice_functio) From 9b8752be34ecf6e93a736624100212b5b5550814 Mon Sep 17 00:00:00 2001 From: Christian Stefanescu Date: Thu, 3 May 2012 19:54:20 +0200 Subject: [PATCH 58/58] Added Scenario "XML parsing" and untangle lib. --- docs/contents.rst.inc | 1 + docs/scenarios/xml.rst | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 docs/scenarios/xml.rst diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 5af8c0f..ca36983 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -54,6 +54,7 @@ different scenarios. scenarios/speed scenarios/scientific scenarios/imaging + scenarios/xml Shipping Great Code diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst new file mode 100644 index 0000000..df89d58 --- /dev/null +++ b/docs/scenarios/xml.rst @@ -0,0 +1,34 @@ +XML parsing +=========== + +untangle +-------- + +`untangle `_ is a simple library which takes +an XML document and returns a Python object which mirrors the nodes and +attributes in its structure. + +For example, an xml file like this: + +.. code-block:: xml + + + + + + +can be loaded like this: + +.. code-block:: python + + import untangle + obj = untangle.parse('path/to/file.xml') + +and then you can get the child elements name like this: + +.. code-block:: python + + obj.root.child['name'] + +untangle also supports loading XML from a string or an URL. +