PyPortMidi for Python 3000 (i.e. Python version 3.1)
Roger B. Dannenberg
based on library by John Harrison

PyPortMidi details for Python 3.1
---------------------------------

Using PyPortMidi
----------------
Running the test31.py sample script and looking at the test31.py 
code is the easiest way to start. The classes and functions are 
mostly documented, or seem self-explanatory. miniTest.py is 
another test program.

There are slight differences between PyPortMidi for Python 2.x and
Python 3000: Input and Output classes take an optional buflen
parameter to set buffer sizes. The defaults should be fine unless 
you want to send/receive long sysex messages. (The buffer length 
should be greater than or equal to the longest sysex message size
divided by 4.)

Also, in PyPortMidi for Python 3000, channel numbering is from 0 to 15.
(In the Python 2.x version, an offset is used so you must use channel
numbers from 1 to 16.) The Python 3000 channel numbering is consistent
with PortMidi.

You can also look at the portmidi.h header, which heavily documents all
of PortMidi's functions.


Installing PyPortMidi from source code:
---------------------------------------

- WINDOWS INSTALLATION

1. Choose to rebuild the PortMidi C library...or not:
   compiled binaries of the PortMidi package are included for Win32,
   so you might be able to skip this step. If you need
   to rebuild:
        - download and extract PortMidi from SourceForge
           http://sourceforge.net/projects/portmedia/files/

        - compile PortMidi with MS VC 2008 Express (free download)
        - build the project, creating
          portmidi/Release/portmidi.{lib,dll}

2. Build _pypmbase.pyd:
        - open a "command prompt" (shell)
        - cd portmidi/pm_python
        - run build31.bat
        - copy build\lib.win32-3.1\_pypmbase.pyd 
          to <python3.1 base directory>\Lib\site-packages\
        - copy pypmbase.py
          to <python3.1 base directory>\Lib\site-packages\
        - copy pypm.py
          to <python3.1 base directory>\Lib\site-packages\

3. Test (optional of course)
        - open a "command prompt" (shell)
        - cd portmidi/pm_python
        - python test31

- OS X INSTALLATION: *** NOT SUPPORTED ***

The following notes are as far as I got. When I used MacPorts (port install), I 
could not find libpython3.1.a to link against. When I tried installing manually
from sources (described below), I got a link error that _environ is undefined.
I might be able to add some code to define _environ in terms of *_NSGetEnviron(),
but I haven't tried that. (Or maybe there's some way to configure Python3.1.1 
differently.) -RBD

0. Install Python3.1.1: Get Python-3.1.1.tgz from http://www.python.org/download/
   Follow the README: ./configure, make, 
       make test (doesn't pass all tests), make install

1. Choose to rebuild the PortMidi C library...or not:
   compiled binaries of the PortMidi package are included for OS X,
   so you might be able to skip this step. If you need
   to rebuild:
   - change to PortMidi subdirectory pm_mac
   - compile. Type: xcodebuild -project portmidi.xcodeproj -target libportmidi.dylib -configuration Release

2. Build _pypmbase.so:
   open pm_python/macpypm/macpypm.xcodeproj
   build the _pypmbase.so target. 
       NOTE: THIS IS WHERE THESE DIRECTIONS BREAK DOWN. YOU WILL ENCOUNTER
       AN ERROR THAT _environ IS UNDEFINED.
       It should build on OS X 10.5 using Python 3.1.1, but you
       may need to adjust some directories
   copy (by hand) pm_python/macpypm/build/Release/_pypmbase.so to the
       appropriate python directory, e.g.
       /usr/local/lib/python3.1/site-packaages/_pypmbase.so
   open a terminal and cd portmidi/pm_python

3. Test (optional of course)
        - open a "command prompt" (shell)
        - cd portmidi/pm_python
        - python3.1 test31


- LINUX INSTALLATION

1. Rebuild the PortMidi C library:
        - follow directions in portmidi/pm_linux/README_LINUX.txt
        - copy libportmidi.a
          from portmidi's pm_linux directory
          to PyPortMidi's linux directory

2. 

Overview of Files and Architecture
----------------------------------

PyPortMidi for Python 3000 (version 3.1) is a reimplementation 
using SWIG rather than Pyrex to build the bridge from Python to
PortMidi. The SWIG file is pypmbase.i, which creates pypmbase.py
(an inteface to the dynamic library) and pypmbase.c (a
dynamic library that makes calls to PortMidi). Apparently, the
pypmbase.py code serves to find and load _pypmbase.pyd and deal
with some differences between Python 2.x and Python 3.x. Since
we're only using this code for Python 3.x, this seems to add an
extra layer of stubs to the overall interface, but since I'm not
a Python extensions expert, I decided to leave in all the stuff
generated by SWIG. Unfortunately, it is not simple to use SWIG
to reproduce the PyPortMidi interface created for Python 2.6, so
this version uses an intermediary, pypm.py, to recreate a 
compatible interface. That's why the SWIG-generated interface
is named pypmbase. The lower-level pypmbase is wrapped by pypm.

Summary: The interface is pypm.py. It uses pypmbase.py which uses
_pypmbase.pyd which calls the PortMidi library functions.

