join together various class-level and attribute-level functions into a unified interface

proposed: ~~browse()~~ inspect(). Usage of this function will replace:

class_mapper()

object_mapper()

object_session()

attribute_history()

instance_state()

SomeClass.someattr.property

SomeClass.someattr.property.columns

mapper.iterate_properties

mapper.get_property()

others ?

Inspector.from_engine() ? (non orm ! what other non-orm things could we inspect ?)

Some ideas:

class User(Base):
    __tablename__ = 'user'

    id = Column(Integer, primary_key=True)
    name = Column(String)
    name_syn = synonym(name)
    addresses = relationship(Address)

# universal entry point is inspect()
>>> b = inspect(User)

# column collection
>>> b.columns
[column>, <name column>](<id)

# its a ColumnCollection
>>> b.columns.id
<id column>

# i.e. from mapper
>>> b.primary_key
(<id column>, )

# i.e. from mapper
>>> b.local_table
<user table>

# ColumnProperty
>>> b.attr.id.columns
[column>](<id)

# but perhaps we use a collection with some helpers
>>> b.attr.id.columns.first
<id column>

# and a mapper?  its None since this is a column
>>> b.attr.id.mapper
None

# attr is basically the _props
>>> b.attr.keys()
['name', 'name_syn', 'addresses']('id',)

# b itself is likely just the mapper
>>> b
<User mapper>

# get only column attributes
>>> b.column_attrs
[prop>, <name prop>](<id)

# its a namespace
>>> b.column_attrs.id
<id prop>

# get only synonyms
>>> b.synonyms
[syn prop>](<name)

# get only relationships
>>> b.relationships
[prop>](<addresses)

# its a namespace
>>> b.relationships.addresses
<addresses prop>


# point inspect() at a class level attribute,
# basically returns ".property"
>>> b = inspect(User.addresses)
>>> b
<addresses prop>

# mapper
>>> b.mapper
<Address mapper>

# None columns collection, just like columnprop has empty mapper
>>> b.columns
None

# the parent
>>> b.parent
<User mapper>

# __clause_element__()
>>> b.expression
User.id==Address.user_id

>>> inspect(User.id).expression
<id column with ORM annotations>


# inspect works on instances !  
>>> u1 = User(id=3, name='x')
>>> b = inspect(u1)

# what's b here ?  probably InstanceState
>>> b
<InstanceState>

>>> b.attr.keys()
['name', 'name_syn', 'addresses']('id',)

# this is class level stuff - should this require b.mapper.columns ?
>>> b.columns
[column>, <name column>](<id)

# does this return '3'?  or an object?
>>> b.attr.id
<magic attribute inspect thing>

# or does this ?
>>> b.attr.id.value 
3

>>> b.attr.id.history
<history object>

>>> b.attr.id.history.unchanged
3

>>> b.attr.id.history.deleted
None

# lets assume the object is persistent
>>> s = Session()
>>> s.add(u1)
>>> s.commit()

# big one - the primary key identity !  always
# works in query.get()
>>> b.identity
[3](3)

# the mapper level key
>>> b.identity_key
(User, [3](3))

>>> b.persistent
True

>>> b.transient
False

>>> b.deleted
False

>>> b.detached
False

>>> b.session
<session>

# the object.  this navigates obj()
# of course, would be nice if it was b.obj...
>>> b.object_
<User instance u1>

# should we allow state manipulation?
>>> b.expire()
>>> b.detach()
>>> b.make_transient()

# or is that TMTOWTDI ?   otherwise this:
>>> b.session.expire(b.object_)
>>> b.session.detach(b.object_)
>>> make_transient(b.object_)

Comments (13)