Discussion to make properties and methods consistent

[Andy Somogyi]

Hi all,

I've got everyone in our group using MDAnalysis, and as I'm the only
one with a comp sci background, I'm the one answering all sorts of
Python and MDAnalysis questions.

The number one issue people have problems with is the inconsistent use
of properties and methods. I fully realize and appreciate that MDA has
an existing number of users, and its not good to break APIs. However,
I think I fixed about a 100 cases of property - method mistakes from 5
people.

So, IMO, I think this issue deserves a discussion.

MDA is pretty much ready to go Py3, I think all that's really needed
is changing the string formatting (replace % with format ), and its
mostly there. Perhaps this would be a good time to introduce the
cleanup?

As for some guidelines of when to use prop-methods, how about if it
takes args, it's a method, and no args, it's a prop? And if it uses
opt args, have the method use get/set and a prop that calls it with
the default args?

Thoughts?

[Oliver Beckstein]

On 16 Feb, 2013, at 11:13, Andy Somogyi wrote:

> I've got everyone in our group using MDAnalysis,

That's great!

> and as I'm the only one with a comp sci background, I'm the one answering all sorts of Python and MDAnalysis questions.

(Maybe encourage them to ask on the mailing list? :-) )

>
> The number one issue people have problems with is the inconsistent use
> of properties and methods. I fully realize and appreciate that MDA has
> an existing number of users, and its not good to break APIs. However,
> I think I fixed about a 100 cases of property - method mistakes from 5
> people.
>
> So, IMO, I think this issue deserves a discussion.

Ok (I hadn't seen this as a big problem because it seldom came up with me or on the mailing list but it clearly is a problem if you see it constantly).

> As for some guidelines of when to use prop-methods, how about if it
> takes args, it's a method, and no args, it's a prop? And if it uses
> opt args, have the method use get/set and a prop that calls it with
> the default args?

I think at some point the philosophy was that essentially "static" properties of a group of atom (in the sense of "does not change in a trajectory"/"is fixed by topology") were represented as properties and "dynamic" quantities or quantities that require more computation were functions. But that was never strictly observed and so we ended up with various inconsistencies.

Personally I am not a huge fan of prefixing everything with get/set; e.g. in NumPy I would find it odd to use array.get_sum() instead of array.sum() (and array.sum at least looks weird because I don't see that sum() is really a function that happens to act on the object.) Also, in many cases there would not be a set_NAME() method (e.g. set_radiusOfGyration() makes no sense) and then it seems a bit redundant to have the NAME property and the get_NAME() method – why not just have a NAME() method?

But as I said, I recognize that there are inconsistencies in how especially AtomGroups are accessed. For example, charges and masses could be usefully treated as properties that can also be assigned to. Which other classes/method would people put on the list?

My main concern is, of course, that changing some of the often-used methods/properties we will break essentially all old scripts. A workaround would be to keep the old API in place for a while (e.g. until 0.9 or 1.0), invent new names, and add deprecation warnings.

While writing this I realize that it would be really useful to have a rough list of the biggest proposed changes – maybe it's not quite as bad as it feels ;-).


re: python 3 transition:

>
> MDA is pretty much ready to go Py3, I think all that's really needed
> is changing the string formatting (replace % with format ), and its
> mostly there. Perhaps this would be a good time to introduce the
> cleanup?

For the time being I would not want to force users to go Py3. If we can make the whole package to run under ≥2.6 and 3.x then that would be great. Otherwise we would have to maintain two versions in parallel or at least have one base version that automatically converts with either 2to3 or 3to2.

Do all supporting libraries support Py3?

- numpy
- scipy
- biopython
- networkx
- matplotlib
- hdf stuff... netCDF

Is anyone interested in looking into this? We can certainly start a py3 branch to see how far one can get with the conversion process.

> Thoughts?

Oliver

--
Oliver Beckstein * orbe...@gmx.net
skype: orbeckst * orbe...@gmail.com