Change package name to pydicom about pydicom HOT 8 CLOSED

From [email protected] on June 11, 2009 20:31:06

Set difficulty. Not too hard but needs folder rename in svn repository, and a big
search and replace throughout all source files.
?Is it possible to somehow install a "dicom" as well, with a deprecation warning?

Labels: Difficulty-Medium

from pydicom.

From [email protected] on September 18, 2012 14:38:34

I've been thinking about this change and have a few thoughts.

Ideally, we would allow the users to import dicom and then get a deprecation warning; however, asking around on the Python irc and other forums, it doesn't seem to be possible (without some severe abuse of distutils).

It seems that the unanimous answer to this issue was to create a new package (pydicom) and create a new release for the old one that throws deprecation warnings in init.py and tells the user to upgrade to the new package and informs them of the name change.

There are still a few issues with this though:

• I'm not completely sure how this would work for users that get their pydicom package through package management software rather than from source (i.e. Say the person had access to the old package, they get the warnings, however, they cannot 'import pydicom' until they've downloaded the new package, which wouldn't be available concurrently through the package manager). I guess they could just stick with the old version until the repo manager upgrades to 1.0.
• Then there's the other chance that an experienced user downloads the new and improved 1.0 only to find that when they import dicom (which they already have on their system), they get 0.9.x instead and wonder why everything looks the same. They would have to read the release notes to know to use pydicom

These are just some things that probably need to be thought through. It seems that the user-base for the library is large enough that we need to be careful with these large changes. I do agree that if we make this change though, that it should accompany addition of python3 support in 1.0.

from pydicom.

Was about to close this as the package name change has been done in the repo, but was re-reading the comments. Do we want to release another "dicom" package to throw deprecation warnings? I'm thinking now that given the move to github there is a sufficient break with the past that the new name won't go unnoticed.

from pydicom.

So I was actually playing around with this idea a few weeks back and it's actually possible (using setup.py) to install pydicom into "dicom" and "pydicom" where the dicom package simply contains an init.py file that imports pydicom and throws a deprecation warning. I don't know what the best practice would be here, but from a technological standpoint this is possible and not difficult to do.

from pydicom.

I'm not sure whether to do this either. I'm trying to think of scenarios out there, here are a few:

1. "Lone progammer": someone using pydicom for a while, doing their own code to solve particular problems, upgrades to new version
2. "Temp worker": e.g. a summer student codes something, leaves, and some time later another staff member (not python knowledgable) wants to install it on another computer, or hands it off to the next student try to take it further.
3. "Dependents": other code using pydicom, like dicompyler. The current version of their package will still rely on older "dicom" pydicom, while they transition their code to the newer version.
4. Newbies: Someone completely new to pydicom, downloads latest pydicom, online searches give examples in old 'dicom' style, but they have the backwards-incompatible (in some ways, anyway) new pydicom actually installed.

Okay ... now that I have thought through all that out loud, so to speak, I have a proposal: we turn this around a bit. Everything works fine (for all those scenarios) if we can give unknowing people what they would have expected in the past. Instead of thinking pip install pydicom gets someone the new pydicom with a 'dicom' pointer package piggy-backed, we think of it the other way around. They get the latest 'dicom' with the new 'pydicom' piggy-backed onto it.

This must be possible, if only through dependencies. We could mark pydicom-1.0 as dependent on pydicom-0.9.9.1, let's say, which is just 0.9.9 with the deprecation warning added, but fully functional. Then pip would simply download and install both anyway. Then even people who know nothing of the different 'pydicom' will still get exactly what they expect to happen, with an additional 'pydicom' package that they didn't know about. We could have a separate 'pydicom'-alone version number ("less than" the other so not installed by pip by default) for those who truly want 'pydicom' installed without touching their older 'dicom' version.

I still haven't thought this completely through...e.g. tarballs, binaries etc need some thought.

I think this is the "gentlest" route to go not to confuse anyone not knowing about the new 'pydicom'. Thoughts?

EDIT: forgot to mention that this would only be for a period of time... of course under any path we choose, once 'pydicom' is well-established we can drop the old name.

from pydicom.

Gentlest perhaps, but this seems relatively confusing for transitioning. Considering the changes discussed in #168, what with an io module etc, etc, there will already be code changes to make or workarounds needed. Adding another option for programmers (dicom and pydicom) may only further confuse, say, newbies (E.g. "Darcy, I have pydicom 1.0.0 and I'm using import pydicom and my buddy is using import dicom. What's the difference? What is correct usage? Docs aren't clear.")

From another angle: pydicom 1.0 introduces quite a few changes. I would feel any programmer that heavily uses a package that rolled from <1.0 to 1.0 would probably want to at least glance at major changes (or perhaps I'm being optimistic). If dependents, e.g. dicompyler, have to update code usage like read_file, what more is an import line change? Adding this ambiguity for gaining 1 backwards-compatible item when there are plenty of other items being changes doesn't seem worth it to me. Perhaps I don't understand the intricacies of such a change...

That being said, I do understand the drive to be backwards-compatible friendly. If this route is taken, whatever version actually deprecates import dicom usage should also deprecate read_file and write_file usage. Either that or promote the workarounds suggested in the mentioned issue.

If I may gingerly offer a modified proposal: release a pydicom 0.9.9.1 as you mentioned with all the deprecation warnings intended to be included, but as its own independent package and as a "final" <1.0 release. Anyone not sure about upgrading to 1.0 could safely upgrade to the latest 0.9.x (0.9.9.1) release, use it, and see the deprecation warnings and be much better prepared for 1.0.

In any event, good documentation of 1) code changes, and 2) examples for v1.0 seems like a very important thing. For those who google pydicom usage and find <1.0 examples and find it doesn't work for 1.0, searching the release changes and official example docs should provide a nice easy transition. I'm definitely willing to help here if given a little guidance.

from pydicom.

Good comments, @jrkerns, thanks. I guess one thing to clarify is that I have been thinking of taking the backwards-incompatible changes further. The read_file change is fine: backward-compatible with a warning, but I've been thinking of bigger changes (e.g. refactoring/creating subpackages: there are now about 26 python files in the main pydicom directory, often with similar names; I often can't remember where certain things are stored). I've also been thinking about adding IODs/Modules on top of Dataset, which could certainly affect backwards compatibility, e.g. setting pixels could automatically change several other data elements. Perhaps setting some would have to become an error, e.g. ds.Rows could not be set directly but only by changing or reshaping the numpy array of pixels.

I agree that releasing the modified version with deprecation warnings is a good idea anyway. Could do that relatively soon, in fact. I've wondered about backporting some of the pydicom 1.0 changes into (0.9.9.1 / 0.9.10?) anyway (e.g. common py2/3 codebase, updated dictionaries).

And yes, I agree good documentation is critical, and thanks for the offer of help, which I'll be happy to take you up on. I'm going to have to be better at recording all the little things as we go along so we don't miss documenting some of the changes.

from pydicom.

This is what I use to make pynetdicom handle the new or old pydicom: https://github.com/cancan101/pynetdicom/tree/master/source/dicom

from pydicom.