clarify documents to better explain what is a table / class / instance

[Former user]

I'm trying to understand the advanced datamapping, and the examples in docs are increasingly confusing to decipher

# class
class User(object):

# instance
user = User()
user = usermapper.select_by

# table
users = Table('users', engine, 
    Column('user_id', Integer, primary_key = True),
    Column('user_name', String(16), nullable = False),
    Column('email_address', String(60), key='email'),
    Column('password', String(20), nullable = False)
)

the standard doc formatting isn't quite clear, as we have python objects and sql objects

it would be really helpful if there was a bit of semantic naming in here {{[

class ( fine as-is )

class User(object):

instance ( change to user_a to represent an instance (or aUser a_user myUser my_user user_instance ) )

user_a = User() user_a = usermapper.select_by

table ( what if the representation was soemthing like _tabledef and the sql was _table

users_tabledef = Table('users_table', engine, ) }}}

I'm sure someone can figure out a better system than I can. things just get a bit confusing as the examples go on, and it becomes hard to tell what is exactly being referenced . there are some parts that I had to read 4x to figure out if i was looking at an object instance, a table def, or what might be a direct link to the sql structure

[Mike Bayer]

heh, good point.

i would go with:

# classes start with Caps
class User(object):

# instances are lowercase and mimic the class name
user = User()

# tables have the word 'table' in them and generally
# are pluralized
users_table

hows that sound ?

[Former user]

that works.'

what do you think of this as well:

always end tables in 's_table' mapper instancase always end with '_mapper'

[Mike Bayer]

this change has been implemented in the 0.2 docs. explicit references to mappers are now very rare since querying is performed off the Query object via the Session.