Documenting sqlalchemy objects via sphinx automodule

[Sean Davis]

I'm not sure there is a solution to this problem without changes to sphinx, but here is what I've got.  In my __init__.py, I have:

Session = sessionmaker()

Base = declarative_base()

def init_model(**kwargs):

    """Initialize the database model

    """

    mydb = URL(drivername='mysql',

               database='solexa',

               query= { 'read_default_file' : '~/.my.cnf' },

               **kwargs)

    engine = create_engine(mydb)

                 

    Session.configure(bind=engine)

    

    Base.metadata.bind=engine

    import meltzdbtools.solexa.objects as objects

Then, I have a bunch of classes in objects.py that look like:

from meltzdbtools.solexa import Base

class StudyFile(Base):

    __tablename__ = 'solexa_study_file'

    __table_args__ = (

        ForeignKeyConstraint(['study_id'], ['solexa_study.ID']),

        ForeignKeyConstraint(['basecalllane_id'], ['solexa_file.BasecallLane_ID']),

        ForeignKeyConstraint(['library_id'], ['solexa_file.Library_ID']),

        {"autoload":True})

    study = relationship('Study')

When I try to run automodule documentation on meltzdbtools.solexa.objects, of course init_model() has not been run, so autoloading fails and Base is not bound to an engine.  Any suggestions as to how to deal with this problem?

Thanks,

Sean

[Robert Forkel]

I've been hitting the same wall, and decided that autoload was the
wrong way to go. Once you want to generate documentation for a
database from the models, you typically do not want allow frequent
changes of the DB structure anymore. So at this point, I just wrote a
script to create basic model classes via inspecting the db. These
basic model classes get documented, enhanced with relationships, ...
afterwards.
So I'd say if your use case is not "being able to use the same
application code with changing db structure", but only "there's too
many tables to handcode the model classes", it's better to jump-start
the model classes via inspection.

> --
> You received this message because you are subscribed to the Google Groups
> "sqlalchemy" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/sqlalchemy/-/TeQSqXqJTz0J.
> To post to this group, send email to sqlal...@googlegroups.com.
> To unsubscribe from this group, send email to
> sqlalchemy+...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/sqlalchemy?hl=en.

[Michael Bayer]

So the thoughts I can offer here are, it depends obviously if you want all the autoloaded mapped attributes to be part of your Sphinx documentation or not. If you did, then your sphinx build would need a database connection in order to work, and actually that seems like kind of a keen idea in some ways...but let's assume you just want the top-level classes documented.

We do have a feature you can use now which will do the reflection of all the tables after the models have been set up entirely. In 0.7, it's a usage example under examples/declarative_reflection/declarative_reflection.py, and in 0.8 it moves to be a fully supported feature of declarative. If you converted your Base to be against DeclarativeReflectedBase, you can import all the classes anytime, and just need to do a prepare() step in your init_model. A doc example is at http://docs.sqlalchemy.org/en/rel_0_7/orm/extensions/declarative.html#using-reflection-with-declarative .