[Feedback appreciated] New Elixir description

[Gaetan de Menten]

Hi all,

I think the current description of Elixir (which is found at many
different places: index page of our website, pypi, README, ...) is
quite out of date and does not reflect the true nature and
specificities of Elixir anymore (especially since SQLAlchemy got its
own builtin "declarative" extension).

I've come up with a draft of all the ideas I think should be mentioned
in the description, but I would appreciate some thoughts about this,
as well as some help to make this a compelling introductory text. I'm
not a linguist nor a native English speaker, so it is quite an hard
task for me.

==========
Elixir is a declarative syntax layer and "database pattern framework"
on top of the `SQLAlchemy library <http://www.sqlalchemy.org/>`_. By
database pattern framework, we mean that it can automatically generate
tables and mappers and provides a way to express "development
patterns" which require some database elements (specific columns or
tables). These patterns can then be easily reused.

Elixir provides some interesting patterns built-in: from the simple
ManyToOne (which generates columns with foreign keys to the table of
the target Entity) to the more complex ManyToMany (which generates the
intermediary table), and various other patterns: three different
inheritance patterns, versioning for entities, ...

Elixir is also highly configurable: you can configure the way (almost)
everything is generated (column, constraint and table names).

Finally, Elixir does not replace SQLAlchemy's core features: it only
alters the way to define classes, and not the way to use (query,
etc...) them afterwards.
==========

For reference, here is the current version of this text:
==========
Elixir is a declarative layer on top of the `SQLAlchemy library
<http://www.sqlalchemy.org/>`_. It is a fairly thin wrapper, which provides
the ability to create simple Python classes that map directly to relational
database tables (this pattern is often referred to as the Active Record design
pattern), providing many of the benefits of traditional databases
without losing the convenience of Python objects.

Elixir is intended to replace the ActiveMapper SQLAlchemy extension, and the
TurboEntity project but does not intend to replace SQLAlchemy's core features,
and instead focuses on providing a simpler syntax for defining model objects
when you do not need the full expressiveness of SQLAlchemy's manual mapper
definitions.

--
Gaëtan de Menten
http://openhex.org

[Kevin Ar18]

> Hi all,
>
> I think the current description of Elixir (which is found at many
> different places: index page of our website, pypi, README, ...) is
> quite out of date and does not reflect the true nature and
> specificities of Elixir anymore (especially since SQLAlchemy got its
> own builtin "declarative" extension).
 

I hope you don't mind my response; I don't want to discourage you or anything. :(
I, personally, kind of find the new description to be a little confusing.
The original description seems to target people who know very little about using objects to represent a database.
The new description seems to target people who already know a little bit about SQLAlchemy and want more details.
Is this what you had in mind?
 
I must admit that the original description seems to do a pretty good job of explaining Elixir to people who are completely new to the concept.  Still, it could always use improvement, like you talked about.
 
Ok, so maybe I should write something for you right?  :)  Well, I don't really know enough to do something like that, but maybe I can suggest something and see if you like it?
 
 
Since I don't know enough about Elixir, here's my rather poor suggestion:
Elixir is a layer on top of the SQLAlchemy library.  It simplifies much of the boilerplate code from SQLAlchemy, resulting in code that is easier to work with and is cleaner to look at.  Since Elixir is only a layer on top of SQLAlchemy, all of Elixir's core features come from SQLAlchemy.
About SQLAlchemy:
SQLAlchemy provides a way to map Python classes to the tables in a database.  <See Example> Instead of invoking SQL commands to manipulate the database, you, instead, work with the Python objects.  These objects automatically update themselves to the database.  Thus, you can work with the database using only Python.
 
Within this Python object atmosphere, SQLAlchemy supports several a range of database features, such as ManyToOne and ManyToMany relationships, versioning system for tables/rows, Pythonic querying of databases, and so on.
 
Of course, you can probably word that last paragraph better.  But anyways, even if you don't like my suggestion, my first question would be, did I describe Elixir accurately (since I'm not 100% sure I understand it all)?
 
<See Example> = for the see example link, I thought it would be really helpful if people could visually see what this means.  This could link to a page that shows two pictures:  1) a picture of a Elixir class like here: http://elixir.ematia.de/trac/wiki and 2) a picture of the SQL code that class get's translated into.   That way, people who are new to the concept can see what this whole database tables as python objects really means.

---

Bing brings you maps, menus, and reviews organized in one place. Try it now.

[Vinay Sajip]

On Nov 16, 11:48 am, Gaetan de Menten <gdemen...@gmail.com> wrote:
> ==========
> Elixir is a declarative syntax layer and "database pattern framework"
> on top of the `SQLAlchemy library <http://www.sqlalchemy.org/>`_. By
> database pattern framework, we mean that it can automatically generate
> tables and mappers and provides a way to express "development
> patterns" which require some database elements (specific columns or
> tables). These patterns can then be easily reused.

I completely agree with this description, but despite your explanation
of the term, some people might be put off by the term "database
pattern framework". I prefer Kevin Ar18's suggestion

"It simplifies much of the boilerplate code from SQLAlchemy, resulting
in code that is easier to work with and is cleaner to look at. Since
Elixir is only a layer on top of SQLAlchemy, all of Elixir's core
features come from SQLAlchemy."

which I would re-word as follows:

"It simplifies much of the boilerplate code you'd need to write
(declaring tables and mappers) if using SQLAlchemy directly. As a
result, your code, if based on Elixir, will be easier to work with and

cleaner to look at. Since Elixir is only a layer on top of

SQLAlchemy, complementing it, you lose none of SQLAlchemy's power by
using Elixir."

Also, if we assume that people using SQLA are familiar with entity
relationships, then it might be better to just list the relationship
types which Elixir makes it easy to define, and focus more on
inheritance support, versioning and perhaps things like associable() -
all which add some value on top of SQLA.

Just my $0.02,

Vinay Sajip