API discussion

[henryiii]

This is a place to discuss API. Some things could change a bit before the first release, or the first "1.0" release.

[henryiii]

@jpivarski The first think I noticed is the "quick constructor" functions. I'm not fond of vector.obj, as it's really bad in the from vector import obj, which many people use. But I think it's fine for now, I'm rather hoping to try a different idea here soon. But I do not like array vs. Array! I think the awkward constructor should either be in an awkward submodule, or at least have a name like awk or awkward or awkarray, etc. Also, PEP 8 naming for functions. How about obj, arr, and awk for now?

[jpivarski]

You can rename them; this was a suggestion. Although differing by capitalization might seem too close, it's already established that NumPy's constructor is np.array and Awkward's constructor is ak.Array (not planned, but convenient that they differ in this way). I think it would be good to recommend use as

>>> import vector
>>> v1 = vector.construct_a_thing(...)

and maybe someday add

>>> vector.deltaR(v1, v2)

that simply goes to v1.deltaR(v2) (so the symmetry is more evident).

Since most of the functionality is in the methods and the vector name is only needed to construct something, it doesn't really need a 2-letter abbreviation or from vector import .... But if people's preferences differ from what I anticipated, that's fine.

[henryiii]

There's nothing wrong with np.array vs ak.Array; np.Array and ak.Array would have been fine too - the np/ak makes the difference. (also, np.array is not a class. But then again, np.ndarray is not correctly capitalized). But having two functions in the same module that differ only by one of them not following pep8 capitalization is not helping.

I have no problem with making all examples vector.something (and am okay with .obj, at least until I try something).

[henryiii]

I don't like the repr showing a quick-create function instead of a class. It is much more informative to see the "advanced" (actual) constructor, rather than a shortcut that tells you nothing about the types involved. Can I replace the vector.obj constructor with self.__class__.__name__, please? At least for the __repr__.

[jpivarski]

The actual constructor is a thing I expect would almost never get used. It's very verbose. Its structure is good for software engineering purposes (by containing three coordinate objects, rather than parameterizing the classes, we get more cases with less code), but not good for analysis.

Typical analysis use-cases would have a lot of vectors floating around, so the __repr__ should be succinct. Since we want the factory function to be succinct, too, I thought it made the most sense for them to be one and the same. That way, it also serves as a remainder of how to construct it (the preferred way for users, not the actual constructor).

[henryiii]

There is a precedent; np.array is shown instead of np.ndarray. And, now with static typing, it's a pain, because now users have to know np.ndarray is the type that np.array returns. Showing the real name for repr helps slowly teach users what's happening behind the scenes, while hiding it makes the library more mysterious. If the facade is perfect, and there's really no difference between the types, then it's okay, but there's already at least one; vector.obj is not the type of vector.obj() and there's no indication what the real type or a valid type is. Let me try a few things before coming back to this.