#5 SQLObject documentation

[Michel Albert]

Hi,

SQLObject is a brilliant project and it's much fun
working with it..... Once you figured out the details.
SQLObject suffers from a *horrid* documentation.

Starting a project from scratch is explained well
enough. But if you have to re-use an existing
database. It's inevitable that you need to use more
advanced features of SQLObject. And those are only
badly (if at all) documented. For example:

You can use a different "Style" object to indicate
a different naming convention.

But which "Style" objects exist? What are the
parameters? Is it possible to create a Style object
yourself? If so, how? What methods need to be
overridden and what do they need to do?

You might say: "Hey, it's open-source. Browse the
source code and see for yourself." And that's fine by
me. But then, *please* document the code! My first try
was to open up the python interpreter and do a
>>> help(SQLObject)
and go from there. Nothing useful showed up.

Honestly, for me time is money, and I was really close
to giving up with SQLObject for this reason. However I
like SQLObject. So I'll take a sip of vinegar and
stick with it. After doing a lot of digging, I got
most things to work. But not necessarily the way I
want them to. Alas, it works.

The gist of this message is: There might be people
less willing to do some research, and drop SQLObject
quickly. It would be sad, if SQLObject suffers from
it's lack of documentation. And if I understood more
of it's inner-workings, I would offer you to write
some documentation, and even redesign the web-page, as
-- quite frankly -- it has a bit of a chaotic look.
The way I understand it, it's automatically generated,
so it's not your fault.

Anyhow, I hope you read this message as positive
criticism and not as a rant/flame. As it was not
intended as such.

Best regards,

Michel Albert

p.s.: is it possible to do a naming style that works
like mixed-case, but keeps the first letter small? Or
even better, one that completely keeps the style of
the variable (does no modifications whatsoever)?

[Paul Benedikt Bittmann]

Hi

I've been playing with SQLObject for just some hours and have just one little recommedation.
In the documentation on One-to-Many Relationships there is a passage:
[quote]
>>> class Address(SQLObject):
...
... street = StringCol()
... city = StringCol()
... state = StringCol(length=2)
... zip = StringCol(length=9)
... person = ForeignKey('Person')
>>> Address.createTable()

Note the column person = ForeignKey("Person"). This is a reference to a Person object. We refer to other classes by name (with a string). In the database there will be a person_id column, type INT, which points to the person column.
[/quote]
If I figured out right in that its important that the column person is named exactly "person" corrosponding to the class Person it would be nice if that could be made clearer in that passage.

I hope I explained myself well and my english is understandable, sorry if not.

I just had to get that out after it took me some time and nerve to figure the thing out myself.