[okfn-help] Deprecating sqlobject in vdm and putting imports at top level (was: Re: vdm: improvement thoughts)

[Rufus Pollock]

On 1 September 2010 13:11, Martijn Faassen <faassen at startifact.com> wrote:
> Hi there,
>
> On Tue, Aug 31, 2010 at 8:14 PM, Rufus Pollock <rufus.pollock at okfn.org> wrote:
>
>>> of some nesting and put the actual code in 'vdm' proper, retaining
>>> 'sqlalchemy' for backwards compatibility only. I think that would
>>
>> I think that is a bad idea. there is no harm with the extra nesting
>> and it means we could add couchdb or mongodb packages if we wanted :)
>
> Already SQLObject and SQLAlchemy have significant API differences
> (making the SA docs as published broken!) and at least they're both
> about an ORM. Wouldn' t it be extremely likely that versioning with
> couchdb or mongodb is going to be very different? Would it then make
> sense to name it 'vdm'? What benefit would there be to a user that
> it's under 'vdm'? What benefit to a developer of vdm?
>
> I can see drawbacks - vdm would have a widely different set of
> possible dependencies depending on how it is to be used, and it'll be
> hard work for someone to run all the tests. And how to document it? I
> can't see a cost in just starting a new package for a new underlying
> database - in fact if that had been done with the sqlalchemy support
> there'd been no reason to get rid of the sqlobject code now, and
> someone might've ported over the docs. :)
>
> I'll tell you why the extra nesting as it is now bothers me. Normally
> I'm not bothered much by extra nesting as I can do:
>
> from foo import bar
>
> and then refer to the individual names in the code using 'bar.qux()"
> and such. This works if 'foo' is a namespace package, like 'vdm' is.
>
> it balances things nicely, not too verbose (foo.bar.qux() tends to
> become that quickly) and not too obscure where 'bar' comes from when
> you're reading the code.
>
> but doing:
>
> from vdm import sqlalchemy
>
> gives me the name sqlalchemy, which is useless as there already is a
> 'sqlalchemy'. I could add in my own 'as vdm', but that would make my
> code different from any other user's, and the job of a good library is
> to make it clear how to use it in a clean way.
>
> If we just had the code in 'vdm', we'd be able to write:
>
> import vdm
>
> and then use methods from that. Minor tweaks to an API can make quite
> a difference in how it is perceived.

Ok, you've convinced me ;)

>>> clean up the namespace and make the imports nicer. Unless we
>>> anticipate vdm working in the future with another ORM altogether, but
>>> I don't see the reason to keep the code bundled into one package
>>> anyway - such a new vdm would presumably have quite a different design
>>> and its use would be different.
>>
>> My feeling is the cost is minimal of keeping it how it is and changing
>> it will be a major pain (and deprecating the sqlalchemy subpackage
>> will be very difficult giving usage by client libraries)
>
> Changing it is easy; you just move the code from 'sqlalchemy' into
> 'vdm' and then have 'sqlalchemy' import from vdm to retain backwards
> compatibility. You can emit deprecation warnings (or just do
> documentation) telling people to fix their imports and eventually
> eliminate the sub package. It's easy to maintain the deprecated
> sub-package as it'd just be a bunch of imports (which you could test
> for).

OK. Let's do this.

Rufus

[...]

(will respond on other items in separate thread)