PEP 3101

This directory is where sample code to support PEP 3101 and do
related things is being developed.

Current developers:

    Patrick Maupin (pmaupin@gmail.com)
    Eric V. Smith (eric@trueblade.com)
    Pete Shinner

The code is only half-baked at present.  Development was started at
PyCon 2007 and is steadily progressing.  The feature set targeted
for the initial release is documented in pep_differences.txt in
this directory.

The current plan of record is to make a pep3101 extension module.
It will have at least the following features:

    - contains a format function which takes a string and parameters,
      (but which is easily portable to a string method for Py3k)
    - can be compiled against 2.4, 2.5, and Py3K
    - Works with the string object as well as unicode

Files:

    - loadpep.py -- Attempts to add the appropriate build directory
      to the Python path, then runs the tests.
    - makefile -- At least one of the developers is a Luddite who
      can barely make setup.py function.
    - pep3101.h contains definitions for the functions in stringformat
      and unicodeformat
    - pep3101.c contains a module implementation which can be linked
      with these method files for testing and/or use with earlier
      Python versions.
    - pep_differences.txt documents differences between what is
      built in this directory, and the original PEP
    - README.txt -- this file.
    - setup.py  -- Use "build" option to make the extension module
    - test_simpleformat.py  -- initial unittests
    - StringFormat.py -- Talin's original implementation in Python.
      This is only for historical interest: it doesn't exactly match
      the PEP or C implementation.
    - stringformat.c is a wrapper around unicodeformat.c, which
      "templatizes" the entire file to make it easy to add to Python
      as a method of the string object.
    - unicodeformat.c is designed to be easily added to Python
      as a method of the unicode object.

Todo:

    - finish up format specifier handling
    - document differences between PEP and implementation
        (in pep_differences.txt)
    - Add docstrings to module
    - Should we have stricter checking on format strings?  For example
      type "s" doesn't allow a sign character.  Should specifying one
      be an error?
    - Test suite needs to check for specific exceptions.
    - Add capability to control exception handling to pep_differences
      and to code:  1) ability to dump exceptions into string, 2)
      ability to re-do lower exceptions or "pile-on"
    - Test suite needs to test different locales for 'n' formatting.