Sorry it took me so long to respond to this. I knew this message was
full of points that needed to be addressed, and wanted to take time to
consider my response.
> What would everyone think of some sort of "Philosophy" for the
> project? In particular, I think it's essential to get something out
> there that describes the scope of the project. I think everyone saw
> Ben Bangert's blog post about this; my first impression was that he
> didn't get the point of Elixir
On this, I think you are absolutely right. A statement of purpose would
go a long way toward clarifying the intent of Elixir, and guiding our
decisions as we move forward. I have read some great books on business
that often mention that a company's mission statement and how well they
follow it are a good predictor of success. So, I believe that we do
need a mission statement of sorts for Elixir.
This also goes along with the revamp of the website, trac, and
documentation for the upcoming 0.4 release, and I think we should aim to
have a simple statement of philosophy / mission statement on the front
page of the website as soon as possible.
> to allow the programmer to write persisted classes naturally using a
> good low-level library.
I am not sure that I agree with this particular mission statement, but I
think its at least somewhat on track. I'd love to hear other people's
suggestions as well, and I will attempt to come up with a few of my own.
> So getting some sort of statement of philosophy up would, I think it
> would help clear up a lot of the ambiguity about what Elixir is trying
> to do.
Agreed, 100%.
> So, here's something I threw together. (I have a thick skin, throw it
> away if you wish, it's just a thought.)
Excellent, this is obviously a lot longer than a one-sentence mission
statement. That being said, something like this might be a good
click-through from the mission statement on the website. So, lets break
it down a bit.
> ## SQL Is Hard
>
> Next to HTML, SQL is the the language that many programmers spend
> the most time interacting with, but not actually writing. Relational
> databases are a massive topic whose full breadth is outside the
> reach of most programmers. Nevertheless, they provide an essential
> abstraction of the data store for programmers, and are not "optional"
> for use in modern systems.
A good start, except maybe for two things:
1. The header. I don't want to imply that Elixir is about not learning
SQL. I believe that this is a common misconception that I'd like to
clear up. To me, Elixir and SQLAlchemy are both about helping you
harness the power of relational databases.
2. The assertion about HTML. I think your point would be just as well
conveyed without drawing this particular association.
> ## What SQLAlchemy Provides
>
> SQLAlchemy provides a fantastic interface between object-oriented
> Python and the primarily declarative SQL. Making full use of Python's
> extensive introspection, SQLAlchemy is able to provide a surprisingly
> complete model of SQL in Python. This allows Python programmers to
> write models - in Python - of their database, and to store, retrieve
> and query objects in their application code with a far more natural
> interface than was the case with the multitude of DBAPI libraries.
>
> However, while SQLAlchemy provides an interface in Python, the
> interface is not particularly *Pythonic*. When programmers are trying
> to define a persistent object, they must explicitly define table and
> column names they typically don't care about, "naked" classes without
> any mapping to a database, and then assign mappers to those objects in
> a third location to handle the ORM step.
Again, I see your points, but have a few issues with the phrasing and
a few of the statements:
1. You need to touch on SQLAlchemy being more than an ORM, and providing
a fantastic low-level interface to relational databases. You touch
on this, but kind of lump it in with the ORM.
2. I'd prefer not to call out the SQLAlchemy API for mappers as not
being Pythonic. I find it fairly Pythonic, just highly verbose, and
tailored to solve every kind of problem for every kind of person.
Elixir draws a line in the sand, and tries to solve certain kinds of
problems for certain kinds of people.
Maybe a rephrasing of these two paragraphs would be in order? Do my
points make sense to you here?
> ## What Elixir Does
>
> In complex situations, this fine-grained control over what happens
> where is extremely useful. For many situations, however, this isn't
> the case. Many times, a programmer merely wants their ORM to take
> their objects and persist them; how that task gets accomplished is
> something the programmer should not have to decide at the early stage
> of writing their object models.
>
> This is what Elixir does: using Python's abstractions, Elixir allows
> programmers to write Python class definitions, which Elixir will
> then use to create SQLAlchemy objects. It does not attempt to be a
> database library; it is merely a way of using SQLAlchemy through a
> Pythonic, class-based interface. When the programmer needs to define
> more complex relationships, Elixir "gets out of the way" so that she
> can use SQLAlchemy to it's full power.
This section is interesting, because again you start discussing how
Elixir helps you not think about the SQL, and its a point that I'd like
to shy away from. Yes, its true that Elixir can be used to persist your
objects without you knowing how it happens, but I think one of Ben's
really good points in his recent blog post is that this can be a pitfall
for new users when they have to start going beyond what Elixir offers
out of the box, because they don't understand what Elixir is doing.
I think this section needs a big rework, to reflect that Elixir isn't
about hiding the details, or disguising what is going on under the
covers. I'd like to encourage our users to have a full understanding
of what any given Elixir model will generate for their schema. I want
them to be able to drop down to the table objects, if needed, and write
complicated queries.
To me, this is the biggest deficiency and misunderstanding with Elixir
that we need to address both in statements of philosophy and in
documentation of what Elixir does "under the covers."
> Because of this, Elixir is extremely well suited to rapid prototyping
> by programmers who are already familiar with SQLAlchemy. Please
> note that using Elixir *requires* knowledge of SQLAlchemy; Elixir
> simply provides a slightly different entry point. However, when going
> through rapid changes in object and table structure, Elixir can save
> the programmer time by not requiring her to update code that may
> be defined in three places in SQLAlchemy: in the table definition,
> the object mapper, and in any object methods that make use of the
> column. While raw SQLAlchemy provides facilities for doing clever
> things in all three locations, Elixir is ideal for the use case of a
> plain, simple table definition to be used in an application prototype.
>
> While the point can certainly be made that the time spent defining and
> updating the tables, mappers and objects in SQLAlchemy is relatively
> low compared to the time spent in application logic, it is also
> true that in the early stages of development, this definition is
> not a "one-shot deal" - the programmer is constantly revising and
> refining the architecture. In these situations, turnaround time takes
> precedence over the low-level power of SQLAlchemy.
I like this section, for the most part, and I think its more focused
upon the real ideas behind why we created Elixir.
> In other words, in production systems we expect complex relationships,
> performance-based normalizations, and oftentimes tight integration
> with legacy systems. However, the programmer should not be burdened
> with these implementation details when building an application
> prototype, or when only simple relations are needed.
Hmm, rephrasing required here, again, I think :) Again, because of the
point about discussing hiding the details. Maybe focus a bit more on
the compactness of the code, and the quickness with which you can get
things done with Elixir.
> This is the niche that Elixir intends to fill: by providing a thin
> layer on top of SQLAlchemy, applications in prototype stage or with
> only simple relationships can be modeled quickly and with a Pythonic
> syntax. When fine-grained control is needed, the library that Elixir
> is built on top of will come to the forefront.
Close -- I really think this paragraph could hit the spot if it
expounded a little bit on the underlying library coming to the
forefront.
Thanks for this initial foray into writing documentation, Adam. Keep
up the good work! Daniel has something up his sleeve for the API
documentation that we should be seeing more of in the near future, and
I'd love to get someone like you involved in updating the API docs
to reflect the new syntax, show diagrams and pictures of what table
definitions will look like, and more.
--
Jonathan LaCour
http://cleverdevil.org
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"SQLElixir" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/sqlelixir?hl=en
-~----------~----~----~----~------~----~------~--~---
