[Dev] Proposed package layout and API-creation guidelines

[Brendan O'Connor]

Thanks for the email Philip -- as developer new to Chandler, I think
such reorg to make things Easy to Find and Use would be tremendously
useful for being able to learn and hack around Chandler.

brendan



> Goals/Issues
> ------------
> 
> Given the scope, the goals of the API guidelines are to:
> 
> Make Things Easy to Find and Use
>     One of the 0.6 API goals is that someone should be able to create a 
> parcel like the Amazon or Flickr parcels without needing someone from OSAF 
> to sit over their shoulder.  Currently, however, you have to either have 
> fairly intimate knowledge of the codebase or else copy things into your 
> parcel that you don't understand and can't fix.  This is partly because we 
> don't...
> 
> Distinguish Internal Components From APIs
>     Right now, there are no organizational cues that distinguish internal 
> components from APIs in the codebase, and in many cases there are no cues 
> to even tell the difference between a module and a class within that 
> module, that can produce confusing errors for people not as familiar with 
> the codebase.  This isn't just a "newbie" problem, either; providing 
> organizational cues is more like making a handle ridged so you can get a 
> better grip on it: it makes things easier for everybody, all the time.  And 
> speaking of making things easier, we also want to...
> 
> Provide Easy API Access in Scripting/Testing Tools
>     Our API strategy needs to consider tools like "headless", CPIAScript, 
> and any future embedded-in-Chandler developing or scripting tools.  They 
> need a way to access APIs that's consistent with the way they're used in 
> Python.  If the way we're accessing APIs in Python is "too hard" to be used 
> in these other tools, then the way we're accessing APIs is too hard, 
> period, and we need to make it better, rather than making "headless" or 
> CPIAScript into isolated, training-wheels-only ghettoes.  Similarly, we 
> want to...
> 
> Follow Python Community Lessons-Learned
>     ...so that we don't create an isolated island of Chandler-only 
> rules.  We're not in a position to dictate standards, and in any case the 
> common Python practices have solid reasoning behind them.  Minor deviations 
> (like allowing "_" in module names) aren't a big deal, but the overall 
> look-and-feel of the APIs shouldn't produce any big surprises.
>