python-soundfile
python-soundfile copied to clipboard
bastibe
Getting rid of the "PySoundFile" brand name
This is already in progress, see 2e80ec45fcc20f834984d29a2799eb0e482f7e37, but I think we should go a bit further.
I don't think the capitalization "SoundFile" makes any sense. It's the spelling of the soundfile.SoundFile class, but I think the PyPI package should rather be named like the module, i.e. "soundfile".
The PyPI URL should therefore be changed from https://pypi.python.org/pypi/SoundFile to https://pypi.python.org/pypi/soundfile.
AFAIK, pip is case-insensitive, but I still think having the lower-case module name makes much more sense and is less confusing.
In addition to PyPI, it would probably also make sense to rename the readthedocs subdomain. I don't know if a rename is possible. I tried it once for a different project by sending an e-mail to the readthedocs support address, but I never heard back from them. But it should be easy to create a new project and phase out the old one.
We could use http://soundfile.readthedocs.io/ or use something that points out the relation to Python, like e.g. http://python-soundfile.readthedocs.io/. Any other suggestions?
The Github project has already be renamed to https://github.com/bastibe/SoundFile, but here I also think the capitalization doesn't make too much sense.
And I personally like pre- or suffixing Github names with python- or -python, respectively.
But the Github name is the least problematic renaming, because it's easy and Github conveniently provides URL forwarding for renamed projects.
I think it would be best to make a new release and upload it only to https://pypi.python.org/pypi/soundfile.
Once this is done, we could create a PySoundFile branch, where we can change the project name accordingly and change the documentation to explain that the name "PySoundFile" is deprecated and all the good stuff can be found at https://pypi.python.org/pypi/soundfile.
We could also try to generate warning messages when installing and/or importing the module.
Then we could make a special release, probably marked with "post" or something, and upload it only to https://pypi.python.org/pypi/PySoundFile.
We could probably create only an installation warning first, and with a later minor release, we can add an import warning.
I agree with everything you said.
Regarding whether to prefix the project name with python- or not, I haven't formed an opinion, yet. It is probably fine to mention Python in the subtitle, though.
The only thing I am unsure about is how to deal with the PySoundFile PyPi package. In my opinion, it would be safe to upload a "new version" that issues a warning when it is imported that the PySoundFile package will be discontinued, and that users should migrate to the soundfile package. But I just know that people will be upset about it.
As I mentioned above, we could first issue an installation warning.
This could be done easily in setup.py, but it would only be shown when installing directly from Git or when using a "sdist".
However, most people will use wheels and I don't think it's possible to show an installation warning there.
As a minor hint, we could probably include the word "deprecated" in the version string.
Either way, it's probably less annoying if we don't generate an import warning right away. A few months later, we could make a minor release that only adds the import warning.
And much later, we could make a final release that only contains a single "sdist" that completely breaks installation and only displays an error message, just to make sure nobody uses the old name anymore.
How about tackling this soon-ish?
I've just created a new RTD project with the name I would suggest:
https://python-soundfile.readthedocs.io/
Good idea!
So, just to recap; the idea is to
- rename the RTD project from pysoundfile to python-soundfile
- rename the PyPi entry from SoundFile to soundfile if possible
- clearly deprecate PySoundFile on PyPi with an installation warning and import warning
Right?
Could we accomplish the last point by creating a new wrapper library pysoundfile that has soundfile as a dependency but does not contain any meaningful code itself?
Are you doing well?
Yes, those three points plus renaming the Github project.
Could we accomplish the last point by creating a new wrapper library pysoundfile that has soundfile as a dependency but does not contain any meaningful code itself?
I'm not sure whether this would work.
Because the actual module name is already soundfile. I don't think we can create a new soundfile module that wraps the existing soundfile module.
And if we create a module named pysoundfile, nobody would use it. And they shouldn't anyway.
Or am I misunderstanding something?
BTW, the "PySoundFile" package on PyPI is already outdated since 3 years (https://pypi.org/project/PySoundFile/#history), so it's high time that we warn those people that are still using the old name!
Are you doing well?
Yes, thanks. Just staying at home ...
I hope you are fine, too!
Oh, right, I forgot that PySoundFile is imported as import soundfile. My idea doesn't work, then.
I hope you are fine, too!
Crazy busy, I'm in the last few months of my PhD, all the while daycare is closed... But I'm doing fine, thank you.
By the way, 300k downloads per months, that's a crazy thing we built, there!
I see PyPi now has the option to designate collaborators. Could you tell me your PyPi user name, to give you access to our two projects?
Sure, that's me: https://pypi.org/user/Matthias.Geier/
If you like the new URL https://python-soundfile.readthedocs.io/, can you please re-sync the webhook on https://readthedocs.org/dashboard/python-soundfile/integrations/? I don't have the necessary rights to do that.
If you don't like the URL, please tell me, then I'll delete the RTD project again.
BTW, I just saw a blog post in the PyCoder's newsletter which should be relevant for us to deprecate the PySoundFile package: https://www.dampfkraft.com/code/how-to-deprecate-a-pypi-package.html.
OK, I added you as a maintainer on PyPi, and hopefully? maybe? set up the RTD webhook. The resync didn't work, but I added it manually and got a 200 response, so it should be fine?
I like the idea in the PyCoder's newsletter of providing a redirect. If I understand this correctly, we would simply bump PySoundFile's version number once and push essentially an empty project with no code except for a setup.py that depends on SoundFile.
And probably issues a deprecation warning on install. Can you even have a project that does not contain any code?
That sounds like a good solution to me, unless I'm missing something.
Thanks, looks like the RTD webhook works, at least the warning message I got before is gone now.
we would simply bump PySoundFile's version number once and push essentially an empty project with no code except for a setup.py that depends on SoundFile.
We could create a branch named e.g. PySoundFile-is-deprecated and a tag named e.g. 0.10.4.PySoundFile.is.deprecated or something like that.
The "real" soundfile package could then continue with version 0.11.
And probably issues a deprecation warning on install.
We can wait a bit with that, we could do that in 0.10.5.PySoundFile.is.deprecated.
Also, I guess this wouldn't work for wheel packages, so we should make sure not to upload wheels for that version.
See https://github.com/bastibe/SoundFile/issues/217#issuecomment-347160236.
Can you even have a project that does not contain any code?
No idea, I've never tried that. But according to the blog post it should work.
We can wait a bit with that, we could do that in
0.10.5.PySoundFile.is.deprecated.
Why would we wait?
Also, I guess this wouldn't work for wheel packages, so we should make sure not to upload wheels for that version.
Very good point.
Would you like to try create the new (empty) PySoundFile version?
Do you know how to rename a package on PyPi? A cursory search didn't turn up any obvious ways to do that.
Why would we wait?
We don't have to.
I just thought we could start with a subtle hint (a strange version string containing "deprecated"), which could already inform a few users, which then can switch calmly at their own pace. We would also change the docs of the old version at that point, gently informing users that they should switch.
The next, less subtle step would be to issue an installation warning. This is more disruptive, but it can still be ignored. It might be annoying, though, if it comes out of the blue.
The next, much stronger step would probably be to issue a runtime warning on import. Very annoying.
And the last step would be to completely break the package, forcing users to switch.
I think we should spread those steps out over time (many months), but we don't have to. We can also make a hard break. Or anything in between. It's your call.
Would you like to try create the new (empty) PySoundFile version?
I would prefer you doing it. But I'm happy to review, if you want me to.
I guess the first step would be to create a branch for "PySoundFile", right? Or do we already have such a branch?
Do you know how to rename a package on PyPi?
I'm not sure if I ever did that, but I guess "renaming" an existing package doesn't make much sense, because it would break all installations with pinned versions.
I guess one would just change the name in setup.py and upload a new version of the package with the new name.
But you have already done that:
- https://pypi.org/project/SoundFile/
- https://pypi.org/project/PySoundFile/
I would just prefer to have soundfile instead of SoundFile, but I guess this would be just a matter of how it is displayed on the web page, because installation is case-insensitive anyway.
And, I would also prefer to have the name of this repo changed, as I already mentioned above.
I think I'd prefer an installation warning right away. PySoundFile has been outdated for a long time now, and it's time to get rid of it.
Would you like to try create the new (empty) PySoundFile version?
I would prefer you doing it. But I'm happy to review, if you want me to.
OK, no problem. I'll get right on it.
I guess the first step would be to create a branch for "PySoundFile", right? Or do we already have such a branch?
To make the distinction clearer, I will try to create a new Repo called PySoundFile that clearly states that it is deprecated in favor of SoundFile.
I set up a repository here: https://github.com/bastibe/PySoundFile
However, I found that newer versions of pip apparently now build a wheel before installing, which means the DeprecationWarning is never shown during installation. So far, I haven't been able to figure out a way of preventing that.
Sadly, we can't append ".deprecated" or anything like that to the version identifier, as the spec only allows .devN and .postN.
How should we proceed from here?
I would love to find a way of consistently issuing an installation warning, or clearly marking PySoundFile as deprecated (beyond the README).
On the other hand, the empty setup.py-stub seems to work beautifully, and should at least absolve us from having to maintain two separate versions on PyPi. The only downside to PySoundFile is that you can't specify a particular version any more. But I don't suspect that to lead to big problems for our users.
You still seem to be using the confusing capitalization "SoundFile" (for things other than the soundfile.SoundFile class), is this intentional?
I think using "the soundfile module" or "python-soundfile" (or something along those lines) would be much more consistent and less confusing for users.
I agree with you on the whole renaming thing, but that will come later.
I wanted to tackle the hard part first, which is the new PySoundFile module, and how to deal with the deprecation warning. The current state of https://github.com/bastibe/PySoundFile implements an installation warning, but the warning is not issued by default, which kind of makes it pointless.
Apart from that however, it seems to work well, and would elegantly switch over all existing users of PySoundFile to the proper version without us having to maintain two separate code branches.
I would say these advantages outweigh the lack of visible deprecation warnings. Do you agree?
I agree with you on the whole renaming thing,
OK, cool, good to know.
but that will come later.
It will be more work to change it later, but if you prefer to do it that way, that's of course your call.
I found that newer versions of pip apparently now build a wheel before installing, which means the DeprecationWarning is never shown during installation. So far, I haven't been able to figure out a way of preventing that.
That's unfortunate. I guess we'll just have to do it without installation warning then.
Sadly, we can't append ".deprecated" or anything like that to the version identifier
That's also unfortunate.
So I guess we are limited to the following ways to communicate the deprecation:
- documentation
importwarningimportbreakage
it seems to work well, and would elegantly switch over all existing users of PySoundFile to the proper version without us having to maintain two separate code branches.
I don't see how having two branches is in any way not superior to having two separate repos, but I guess in the end it doesn't make too much of a difference.
I would say these advantages outweigh the lack of visible deprecation warnings. Do you agree?
I don't really know what advantages you are talking about and as far as I understood installation warnings are not feasible anyway, but yes, I agree!
With our current course of action, neither an import warning nor an import breakage is possible. PySoundFile would be an empty project without any code to be imported. Instead, import soundfile would import the real SoundFile (or rather, python-soundfile), which lives entirely independently from PySoundFile.
On the one hand, this is great, as it would tide over all existing users of PySoundFile to the proper version of the library, without any further need for maintenance or care on our part. On the other hand, it does not give them much warning at all that this is what is happening.
I still find it a good solution. If you're OK with it, I'll upload PySoundFile to PyPi, and we'll tackle the actual renaming of SoundFile next.
Does that mean you never ever want to shut down the "PySoundFile" package and it should be available for installation forever?
I think it would be cleaner and less confusing to completely break the package at some point in the future and make it impossible to make a working installation (except when pinning an older version).
Does that mean you never ever want to shut down the "PySoundFile" package and it should be available for installation forever?
Not at all. But it means that I don't know how to communicate to users that PySoundFile is going to go away. Perhaps mentioning it in the documentation, and indeed having a dedicated repo with a clear deprecation warning, must be enough. Than after a few months or so, we could remove PySoundFile from PyPi.
By the way, I find your accusatory tone extremely tiring. Please tone it down if you want my cooperation.
Let's move this forward.
We'll have to decide on a course of action. As far as I can tell, we need to do one of:
- Replace PySoundFile with https://github.com/bastibe/PySoundFile as the final version and leave it at that
- Replace PySoundFile with an empty project that throws an error on import
- Remove PySoundFile from PyPi entirely
- Change our build scripts to provide an up-to-date PySoundFile as an alias to soundfile
- Leave PySoundFile as it is, and only update the README to mark it as deprecated
I would favor 1 or 5, but could live with the other options as well. I specifically prefer 1 or 5 as they probably incur the smallest maintenance burden of these options. What are your thoughts on this?
By the way, I find your accusatory tone extremely tiring. Please tone it down if you want my cooperation.
I'm sorry for the tone, this wasn't at all intentional!
Does that mean you never ever want to shut down the "PySoundFile" package and it should be available for installation forever?
Not at all.
Great, so we are on the same page here.
But it means that I don't know how to communicate to users that PySoundFile is going to go away.
According to the comments above, I think the only three tools left are:
- documentation
- import warning
- breaking the package.
The automatic redirection doesn't seem to be appropriate if we want to break the package in the end (which we apparently do).
Replace PySoundFile with https://github.com/bastibe/PySoundFile as the final version and leave it at that
With "leave it at that" you still mean that we break the package at some point?
I still think a separate branch is simpler and easier than a separate repo, but it's your call.
Replace PySoundFile with an empty project that throws an error on import
I don't think it has to be an empty project, we can just add the error to the existing code.
Deleting the code and/or creating a new empty project seems like more work than necessary.
But again, it's your call.
Remove PySoundFile from PyPi entirely
I don't think that's a good course of action.
It looks a bit shady if we remove everything.
Also, people might legitimately be interested in one of the old versions, and I don't see a reason why we should not allow that.
Change our build scripts to provide an up-to-date PySoundFile as an alias to soundfile
This would be appropriate if we would like to keep PySoundFile forever, but I think we don't.
Leave PySoundFile as it is, and only update the README to mark it as deprecated
That's definitely an option, but I think it's best to do this as a first step but then, at a later point fully disable new installations (except for people who explicitly want an older version).
Thank you for your comments. I think I have made up my mind on this issue:
Pending your approval, I propose to update PySoundFile one final time, with no changes to its (very old) code, but replacing the documentation on PyPi with a clear deprecation message.
After that, we can abandon it. After thinking it over one more time, I don't think we need to break it. Breaking it would only serve to alienate users, and serve no purpose to us.
I think this course of action minimizes our maintenance burden, and confuses the smallest number of users.
Do you approve of this course of action?