Daniel Robbins wrote: > On Tue, Mar 16, 2010 at 8:08 AM, Michael Bayer <[email protected]> > wrote: >> >> we definitely should because I am amazed at how often this question gets >> asked. But the more puzzling thing is that it means the central tenet >> of >> declarative isn't getting across to people, which is that nothing >> changes >> at all when using declarative, its strictly a syntactical shortcut - >> everything you do when not using declarative is still 100% doable, in >> exactly the same way. I'm not sure why I see so many questions from >> others of the form "but I'm using declarative!" > > My advice to you is to embrace the feedback and use it to make the > project better.
I'm sure if you review our mailing list history for the past five years you'll be pleased to know that the virtually all of the progress made on the SQLAlchemy project post version 0.1 has been driven completely by end-user need, but at the same time not turning the project into a PHP-soup of flags and switches, distilling what end users need into an ever expanding but coherent system that attempts to be as consistent as possible. Rest assured that if we didn't do a pretty good job of balancing these sides we wouldn't still be a prominent project today. > People want to *start* with declarative, whereas you > as the architect started with the core parts of the framework and > recently added declarative. So you know all the underpinnings, but > most users don't, and they want to remain on as high a level > (declarative) as possible without having to get sidetracked by being > forced to master the lower-level parts in order to simply create an > index for their declarative tables. Make sense? How to tie the two > together is not always documented clearly. Think from the new user's > perspective and try to accommodate them via the docs. I appreciate the rant but we're only talking about adding a distinct section to the declarative documentation regarding indexes, which is already accepted, and specific examples regarding remote_side and such are non-controversial as well and we shall review the cases you present. Declarative doesn't *require* that arguments are passed as strings, either, this is optional. There's some discussion of some common gotchas here on the FAQ at http://www.sqlalchemy.org/trac/wiki/FAQ#ImusingDeclarativeandsettingprimaryjoinsecondaryjoinusinganand_oror_andIamgettinganerrormessageaboutforeignkeys , but we can integrate this into the declarative docs too. It doesn't make much sense for the declarative documentation to completely duplicate the entire mapping/relation/metadata sections of the documentation, however. It's still expected that users who want to deal with Index, Sequence, etc. constructs will have read these sections. Better hyperlinking, a constant work in progress (and very open to outside contribution via patches, we transitioned to Sphinx largely for this reason) also makes the docs easier to follow. > > Index('endp_grp_ix', Endpoint.__table__.c.samplegroup_id, > Endpoint.__table__.c.name) Index to my knowledge does accept declarative columns these days. You can pass in Endpoint.samplegroup_id and Endpoint.name directly. The above workaround was for a bug. > # But it would be nice to access them as a dictionary, so we could > grab a particular interface by typing: > # myhost.interfaces["eth0"]. Here's how we create an "interfaces" > reference in dictionary mode. This must be done > # outside of the class after both tables have been defined: > > Host.interfaces = relation("HostInterface", > collection_class=column_mapped_collection(HostInterface.name)) I'm not aware of this requirement. you should be able to create the "interfaces" relation inside of Host, using a string to define "collection_class" or otherwise use attribute_mapped_collection("name"). If this is not possible, then its a bug. > I am working on a pretty simple DB project, with only about 12 tables, > but here is my supporting/helper code, which is an order of magnitude > more complex than the samples in the docs, but got declarative to the > point where 1) I could actually use it with Oracle by adding > auto-sequences to the declarative model (a BIG hurdle for new users > who just want to dive in and are using it with a db that doesn't have > auto-increment sequences) I wouldn't consider Oracle to be a good candidate for "diving in". But we do have a prominent sidebox in the ORM tutorial now, describing the need for the Sequence construct when using Firebird or Oracle, which you can see at http://www.sqlalchemy.org/docs/ormtutorial.html#define-and-create-a-table . > and 2) where I could significantly reduce > duplicated code, which is generally one of the benefits of using a > class heirarchy. > > It took me quite a bit of time to piece this all together, where more > complex examples in the docs would have helped me along: I'd note that the metaclass stuff you've done has been worked into a simple built in feature, using our new "mixin" capability, which is described at: http://www.sqlalchemy.org/docs/reference/ext/declarative.html#mix-in-classes This feature was contributed by Chris Withers who showed up to our sprints to help, and we gave him all the access he needed to get it done. > > # Easy unique string creation: > > def UniqueString(length=80,index=True): > return Column(String(length), unique=True, index=index, > nullable=False) > > # Easy ManyToOne relationship - returns a column plus a relation - see > example below: > > def ManyToOne(myclass,nullable=True, backref=None, index=False): > return Column(Integer, ForeignKey(myclass.__tablename__ + > ".id"), nullable=nullable, index=index), relation(myclass, > backref=backref) We mention prominently in the intro and on the wiki that there's a place for recipes like these, which is the UsageRecipes section: http://www.sqlalchemy.org/trac/wiki/UsageRecipes Recipes on that section that are of extreme general usefulness eventually become built in features. In particular the ManyToOne etc. idea I've considered, the only issue is how to present without adding to its being overwhelming. - mike -- You received this message because you are subscribed to the Google Groups "sqlalchemy" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/sqlalchemy?hl=en.
