Add `__version__` attribute to Trame packages about trame HOT 22 CLOSED

Okay, trame_server and trame_client now both have __version__ on them.

Now let's take trame-vtk as an example for how we will be doing every other trame-* project.

We can add this to trame_vtk/__init__.py:

from trame_client.utils.version import get_version

__version__ = get_version("trame-vtk")

Then anywhere else we want to add it in the project, we can do something like this:

from trame_vtk import __version__

And the __version__ will be exposed in that file. So I guess we should decide if we want this on every module, ui, and widget file.

from trame.

Oh weird... But there is a __license__ there:

trame/trame/__init__.py

Line 3 in 2818473

__license__ = "Apache License 2.0"

>>> import trame
>>> trame.__license__
'Apache License 2.0'

I don't see any issues with adding a __version__ there too

But the __license__ should not be there. See here. Note in particular the section starting with "The __init__.py file for the namespace package needs to contain only the following:"

As I understand it, for namespace packages, there is ambiguity as to which __init__.py file is actually going to be present, and therefore they should all be identical. For instance, if you pip install trame-grid-layout, then the trame/__init__.py file is actually going to be the one from trame-grid-layout, not the one from trame (and then trame doesn't have a __license__ attribute anymore). Maybe there are some additional issues as well I'm not aware of since the packaging docs are pretty emphatic that the __init__.py files should only contain that line.

So as long as the root trame module is a namespace package, it should not contain any extra code, including a __version__.

However, it is also worth revisiting whether we should change the root trame to not be a namespace package. Part of the reason we needed the root trame to be a namespace package was this setuptools issue, which looks like it was resolved since the last time I checked. Before, we needed the directory structure like trame/modules and trame/ui for editable installs to work correctly. If we can use package_dir now with editable installs, we wouldn't need that directory structure, and thus can probably avoid the root trame being a namespace package. But I should verify too that the path gets extended correctly.

from trame.

I'm not against having version on trame itself, but the benefit of it will be limited. The 2 key components are server and client. So having a version on them will be much more impactful. Also I'm envisioning runtime client version which mean it can't necessarily be figured out from the packaged installed. What I mean, is I see the possibility to have 2 client version installed and at runtime we could choose one vs the other... From the Python point of view, that may seems strange, but for the web point of view not that much. We are just serving different set of files...

from trame.

But that part should be totally transparent to the user and in fact the user should not care about it.

from trame.

So, adding a __version__ is in general easy to do. But trame.__version__ is a little harder. That's because we set up trame as a namespace package, and the root trame __init__.py is not supposed to contain anything other than the __path__ extension (if it does contain anything else, the additional code is not guaranteed to be executed).

We did this mainly so that trame.widgets, trame.modules, and trame.ui could more easily be namespace packages as well.

Is it acceptable to have the root __version__ somewhere else? Or should we look into making trame.__version__ possible?

from trame.

Good point... It would be useful to have a version on the server and possibly the client. Those are the two that could be useful...

from trame.

Not sure of the benefit of having a version on trame itself.

from trame.

But trame.version is a little harder. That's because we set up trame as a namespace package, and the root trame init.py is not supposed to contain anything

Oh weird... But there is a __license__ there:

>>> import trame
>>> trame.__license__
'Apache License 2.0'

I don't see any issues with adding a __version__ there too

Is it acceptable to have the root version somewhere else?

You can put it anywhere so long as it's accessible from the top-level namespace of the package (i.e., trame.__version__)

Not sure of the benefit of having a version on trame itself.

Well, the trame package isn't empty... At the end of the day I don't need the __version__ on any of these packages but having it is really nice when debugging.

from trame.

Thanks for the clarification, @psavery! This namespacing magic is making more sense to me now.

If you can get away from trame being a namespace package and there are justifications beyond me asking for a __version__ attribute, great! If not, I don't want to request a chunk of work for this as there are plenty of other, fine ways to get the package version

from trame.

From the Python point of view, that may seems strange,

Seems very strange to me and scares me a bit...

from trame.

Another way to explain what I mean would be to do a parallel to VTK in an imaginary world were the rendering backend could be its own installable package (OpenGL, EGL, OSMesa). The idea would be that you can install one or more and then choose at runtime which one you want. Would you find that strange if you were able to do that seamlessly?

from trame.

Ahh, thanks for that analogy that, indeed, would be really nice and not all that strange. Not common, but not strange

from trame.

I'm not against having version on trame itself, but the benefit of it will be limited. The 2 key components are server and client. So having a version on them will be much more impactful. Also I'm envisioning runtime client version which mean it can't necessarily be figured out from the packaged installed. What I mean, is I see the possibility to have 2 client version installed and at runtime we could choose one vs the other... From the Python point of view, that may seems strange, but for the web point of view not that much. We are just serving different set of files...

So, for the Python versions, will they be located at trame_server.__version__ and trame_client.__version__? We could have a __version__ for every trame-* package like this.

Would the runtime client version be something different, like trame_client.__runtime_version__?

from trame.

So, I think we should have trame-xxx.__version__ but for the runtime it will be something more related to the server instance. Not sure yet, but having something along those lines server.client_version => [email protected]

from trame.

Also it could be nice if we could have that version info on trame.[modules|widgets|ui].[vuetify|client|...].__version__

from trame.

Just ideas so far, no real direction on where we should be going...

from trame.

Also it could be nice if we could have that version info on trame.[modules|widgets|ui].[vuetify|client|...].__version__

Yes, we can do that too!

from trame.

We just need to see if it is that useful.

from trame.

Okay, __version__ has been added now to most of the trame packages (including the cookiecutter). I did not yet expose it, however, in the module/ui/widget files. So for instance, right now, you can get the trame VTK version via from trame_vtk import __version__, but you couldn't get it via from trame.widgets.vtk import __version__.

Is that something we want to add right now, or revisit later?

from trame.

Can we reopen this since trame itself does not seem to have __version__ at least with the latest pip installed version?

$ pip list | grep trame
trame                         3.2.4
trame-client                  2.11.2
trame-server                  2.11.7
trame-vtk                     2.5.8
trame-vuetify                 2.3.1
$ python -c "import trame; print(trame.__version__)"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
AttributeError: module 'trame' has no attribute '__version__'

from trame.

Ahh I see above:

So as long as the root trame module is a namespace package, it should not contain any extra code, including a version.

FWIW this is surprising behavior to me (and probably others in the scientific python ecosystem) but feel free to keep closed as wontfix if you prefer!

from trame.

@larsoner I think from trame import __version__ would be nice to have! But I'm not sure if it's possible since we have it as a namespace package. I'm open to suggestions, though.

I also wonder what other projects that have a root namespace package do about things like __version__.

from trame.