[pygame] constructor nomenclature

["Pete Shinners" <pete@visionart.com>]

i've gone through the source and pulled out all the functions which
are used to create objects. hopefully wordwrapping doesn't mangle the
little table, but if it does i've attached the text as well.

take a look at the list, the "normal" objects are objects that
work like you'd expect. "shared" objects are individual objects,
but much of their data and 'state' is shared among object constructed
with the same values.


pygame constructor-ish functions...

current name              new name?                 type      wrapped
----------------------------------------------------------------------------------
[normal object construction]
pygame.new_rect           pygame.Rect (*)           Rect      n/a
pygame.new_surface        pygame.Surface (*?)       Surface   SDL_CreateRGBSurface
pygame.event.new_event    pygame.event.Event        Event     malloc(SDL_Event)
pygame.font.new_font      pygame.font.Font          Font      TTF_OpenFont
pygame.mixer.load         pygame.mixer.Sound        Sound     MIX_LoadWAV
pygame.display.get_info   pygame.display.Info       VidInfo   SDL_GetVidInfo

[shared object construction]
pygame.cdrom.open         pygame.cdrom.CD           CD        SDL_CDOpen
pygame.joystick.open      pygame.joystick.Joystick  Joystick  SDL_JoystickOpen
pygame.mixer.get_channel  pygame.mixer.Channel      Channel   n/a

(*) this function also in pygame.locals


note that the "wrapped" column isn't really important, but you can
start to see where pygame got it's original naming structure.

looking at all these. i see if we change all these constructor type
functions, the capitalization really starts to make things clearer.
instead of mixer.load, just use mixer.Sound to create your sound objects.
the only thing this doesn't take into account are other module-level
functions that simply create a new object. the only one i can think 
of is pygame.image.load(). (surely there must be a couple others?)

before i thought only 3 objects from this list would be good candidates
for the capitalization. switching just those to caps would make them
stick out. but by adding all these constructors to the list, it actually
makes things more consistent.

i hate to be toggling like a switch on this issue, but i am liking
the capitalized constructor functions. when i switched the functions
to "new_" it was certainly not a closed issue. i feel kinda silly after
having just changed them and now going back. i do remember that it was
only changing 3 functions to something consistent as opposed to changing
many functions (in this list, 9) to something i wasn't sure about yet.

the interface for cdrom and joystick are still a little up in the air,
but if everything goes in this direction, it makes it pretty easy for
me to lock down the main cdrom and joystick stuff in the same style.

well, i won't be comitting it yet, but if/when these changes are made,
i'm gonna let them sit in CVS for a week or two before releasing. that
should help you fix the breaking changes at your own 'leisure' :]

also, what about the functions going into pygame.locals. it seems like
"Rect" should, since creating rectangles quickly is really helpful. i'm
thinking that Surface should not be a member of locals, but i'm not 100%
sure. the surface constructor function is an orphan, need to find him a
good parent.

if the pygame examples are any indicator, it has been fairly simple to
keep them up-to-date with all my pygame changes. i'm hoping the code
you guys are working on out there is similar. for the most part these
breaks should just be a matter of search&replace. (still a pain though)

does this sound all thought through? need a couple external viewpoints.

pygame constructor-ish functions...

current                   newname?                  type      wrapped
----------------------------------------------------------------------------------
[normal object construction]
pygame.new_rect           pygame.Rect (*)           Rect      n/a
pygame.new_surface        pygame.Surface (*?)       Surface   SDL_CreateRGBSurface
pygame.event.new_event    pygame.event.Event        Event     malloc(SDL_Event)
pygame.font.new_font      pygame.font.Font          Font      TTF_OpenFont
pygame.mixer.load         pygame.mixer.Sound        Sound     MIX_LoadWAV
pygame.display.get_info   pygame.display.Info       VidInfo   SDL_GetVidInfo

[shared object construction]
pygame.cdrom.open         pygame.cdrom.CD           CD        SDL_CDOpen
pygame.joystick.open      pygame.joystick.Joystick  Joystick  SDL_JoystickOpen
pygame.mixer.get_channel  pygame.mixer.Channel      Channel   n/a

(*) this function also in pygame.locals