Python Best Practices Agile shortcut

Motivation

Over the years, I've come to realize that programmers who have learned traditional languages have a hard time understanding the role that packaging systems play in agile languages. That conceptual difficulty seems to pose a major barrier to them mastering agile languages. This shortcut is one of several tools/tutorials designed to help newcomers to agile past this barrier.

Paths

Step-by-step

1. Install python (Chapter 1, "Installing Python")
2. Install setuptools (Chapter 1, "Installing Setuptools") yes, this is out of order. Trust me...
3. Absolutely critical (I learned after blowing it the first time, doh!), go back and do the second section in Chapter 1, on customizing the prompt.
   • In particular, install ipython. Says Tarek "Since the prompt interactive mode will play an important role in the coding process, we need to make it very easy to use."
   • While installing ipython, the installation instructions list a number of 'basic optional dependencies'. Go ahead and install everything you can, including the stuff for parallel computing (we're into scientific programming here, and most of you have, or will work on, multi-core computers, or will have access to clusters, so it just makes sense to get started on it. Besides which, it's largely transparent.)
   • The optional dependencies gets you nose, which is important later.
4. IPython provides a complete working environment. Of the alternatives, Python + Emacs is the only one you should seriously consider at this point. Why? Because you are trying to learn Python software engineering. That means you want a tool that thinks in python. Eclipse thinks in Java. Python gurus don't find that a problem, and it's an excellent tool (so I'm told) for Python/Java integration, although an equal number of Python gurus swear by Emacs for the same thing. I can't speak to either at this point.
5. Read the summary in Chapter 1. (Note that the order in the summary is the order I gave you, not the order of the sections in the book. Hmmm....)
6. Read the summary for Chapter 2, Syntax Best Practices—Below the Class Level
7. Read the last two section of Chapter 3:Syntax Best Practices—Above the Class Level
   1. Meta-programming
      • Meta-programming is what differentiates a truly object-oriented language from a language which does not offer the full range of power of object-oriented programming. In other words, this feature is what differentiates Python, Perl, Ruby, etc., from C++, Java, etc. Go ahead and read it so that you recognize what you are seeing when you see it. Don't worry about fulling understanding it at this point.
   2. Syntax Best Practices—Above the Class Level > Summary
8. Read at least the last three sections of Chapter 4: Choosing Good Names
   1. Working on APIs (pay special attention to the section on eggs - you may want to go back and read about decorators in chapter 2 now. Eggs and decorators are both tools that support aspect-oriented design.) Take a few minutes and read about eggs on the PythonEggs page at PEAK, the Python Enterprise Application Kit (note the entry for DecoratorTools at PEAK, too!)
   2. Useful tools (go ahead and install both PyLint and CloneDigger)
   3. Summary
9. Read all of Chapter 5: Writing a Package. Most of what you would think of as a program is best developed as a package in an agile language. The packaging systems provide a rich set of tools for developing code.
   1. A Common Pattern for All Packages - Read this, but don't try to run the commands, as you do not have acme.sql!
   2. The Template-Based Approach - Read this. Install PasteScript from http://pythonpaste.org. (In our comparison set, paster is the equivalent to module-starter in PerL and package.skeleton() in [FreeOpenSrc.RisCool][R]]) Go ahead and play with the basic-package a bit if you'd like, however, that is not the template that we are interested in! Don't worry about the complexities of Cheetah for the moment, or making sense of the stuff at the bottom of the page, just read it over once and move on.
   3. Creating the Package Template - This section explains how they created the template that was used to create acme.sql. Read the first paragraph, then only read the rest if you really want to, however, make sure that you install pbp.skels. These are the templates we want.

      easy_install pbp.skels

      After you install the templates, rerun the command from the previous section to list the templates you have

      paster create --list-templates

      you should see

      Available templates:
        basic_package:     A basic setuptools-enabled package
        paste_deploy:      A web application deployed through paste.deploy
        pbp_design_doc:    A Design document
        pbp_module_doc:    A Module helper document
        pbp_package:       A namespaced package
        pbp_recipe_doc:    A recipe document
        pbp_tutorial_doc:  A Tutorial document
      

      The pbp_package is the one you want.
   4. Development Cycle - Read it, lots of good info.
   5. Summary - read, as always.
10. Jump forward to Chapter 11: Test-Driven Development. I'm going to have you read all three sections, but not all of all three sections, in this shortcut.
    1. I Don't Test - read all of this section, paying particular attention to doctest
    2. I Do Test - skip the parts on py and fakes and mocks for now.
    3. Summary - read this section, as always.
11. Making better sense of names and namespaces (now this is HilaryHolz speaking.)
    1. You've got all the package bits installed (if you're on a Mac, you need to upgrade to 2.6, btw), you've read through the material on nose, and you're ready to create your workspace for wumpus. You hop into emacs (or IPython) and, in emacs, at least, you type

       paster create -t pbp_package wumpus

       and it starts asking you questions! Argh!
    2. You need to develop a deeper understanding of what modules and packages mean, and the role they play in python code development. Read:
       • http://docs.python.org/distutils/introduction.html#general-python-terminology
       • http://docs.python.org/distutils/introduction.html#distutils-specific-terminology
       • http://peak.telecommunity.com/DevCenter/PkgResources
       • and the section on Module and Package Names from Chapter 4: Choosing Good Names, of Tarek's book.

Brave co-pilot

NateDelgado has been play testing this shortcut with/for me, and chronicling the process. He is working on RefactoringWumpus for the students in ArtificialIntelligenceSpr09 so as to have a real project in hand. For better or worse, of course, we are doing all of this against the backdrop of California's budget collapse, so no funding, no graders, no anything. It's, well, it's way, way, better than retreating to just shoving decontextualized info at students for them to memorize, regurgitate and forget, but it isn't what we were accomplishing a year ago when we still had some resources.

Sections of Tarek's book covered

• Chapter 1. Getting started
  • all sections
• Chapter 2. Syntax Best Practices—Below the Class Level
  • Decorators
  • Summary
• Chapter 3. Syntax Best Practices—Above the Class Level
  • Meta-programming
  • Summary
• Chapter 4. Choosing Good Names
  • at least the following
  • Working on APIs
  • Useful Tools
  • Summary
• Chapter 5. Writing a Package
  • all sections
• Chapter 11. Test-Driven Development
  • all sections, although not all of all sections

Python projects / software installed

I just started compiling this, so it is wildly incomplete

• http://pypi.python.org/pypi/setuptools setuptools
• http://peak.telecommunity.com/DevCenter/EasyInstall EasyInstall, however, actually came with setuptools, above
• PyLint easy_install logilab.pylintinstaller
• http://clonedigger.sourceforge.net CloneDigger
• http://ipython.scipy.org/moin/ IPython itself, plus readline, nose, and pexpect
• http://pythonpaste.org template engine PasteScript
• Python Best Practices templates easy-install pbp.skels