I've just been given the go-ahead to create "Spike", a prototype Python API for Chandler. "Spike" is a common name for a dog, but it's also an XP term meaning a simple, narrowly-focused prototype to test feasibility and build understanding of a subject. The Spike project will be testing the feasibility of various ideas for creating a simple Python API for developing Chandler data types and services, as well as building my understanding of Chandler's requirements.

Although it's a prototype, it will be heavily documented and tested. I expect lines of documentation and tests to be roughly 2-3 times the actual code size, although that ratio will vary from time to time. Spike's development will be completely test-driven: no new functionality will be added without tests, thus virtually guaranteeing 100% test coverage.

The principal goal of Spike is to design an API usable by persons with basic knowledge of Python, and which is idiomatic for more experienced Python programmers. Where appropriate, it will follow established conventions of the Python language or of popular open-source Python libraries. It will also translate Chandler's internal terms and concepts into more commonly-used equivalents. For example, "kinds" will become classes, and repository items will become objects. It's possible that I will make mistakes in translation, and then need to make adjustments later on. So if you're watching and you see such a mistake, please let me know.

Anyway, the idea is simple: make it possible for a programmer to become fluent in Chandler development as quickly as possible. This is a kind of user interface design, it's just that the target user is a programmer, not an end user. And of course in any user interface design, a key point is to present the user with a simple model of how the system works, even if the internals are more complex. So, Spike will be presenting a simplified version of Chandler's internals, that will not necessarily expose 100% of existing internals' functionality. For example, the repository has a lot of features that are not currently used by higher layers of Chandler, and Spike will therefore not expose those features.

Because Spike will be designed via TDD (Test-Driven Development), its API will be very evolutionary, and may change rapidly from one week to the next. However, these changes will be anchored in tests and documentation, especially doctests. This guarantees that examples presented in Spike's documentation will always be up-to-date with the current state of the API. The tests will also guarantee that existing functionality is not affected by a change, unless changing that functionality was the point of the change. Having this degree of flexibility is particularly important for a prototype, since it needs to be able to change quickly as I learn things about Chandler's requirements and how best to shape them into an "intuitive" API.

As I go along, I am sure there will be plenty of holes in my coverage of needed functionality, and I'll be relying on the Chandler development community to point those out to me. Since the purpose of the project is to be a prototype, I'll try to address your concerns and requirements by adding new tests and code, rather than by engaging in abstract design discussions. That way, we can ground our discussions by reference to actual pieces of code. And, we can work together to turn requirements into tests, that will prove whether a particular solution works. Once there are tests, we can then experiment with more than one way to address the requirement, and we can then choose the simplest way.

Per an IRC discussion with Bear, I'll be starting Spike as a project directory under 'internals' in CVS; specifically 'internals/Spike'. My hope is that this prototype will provide the Chandler community with a useful testing ground for ideas for Chandler 0.6, as well as providing a focal point for my learning more about Chandler.