How to update the "Description" in pypi.org ?

[guolinke]

In the old pypi.python.org, we can update the description by using edit or upload a pkg-info file.
But now it is not support:

Gone (This API has been deprecated and removed from legacy PyPI in favor of using the APIs available in the new PyPI.org implementation of PyPI (located at https://pypi.org/). For more information about migrating your use of this API to PyPI.org, please see https://packaging.python.org/guides/migrating-to-pypi-org/#uploading. For more information about the sunsetting of this API, please see https://mail.python.org/pipermail/distutils-sig/2017-June/030766.html)

But in pypi.org, I cannot find any function to add or change the description of the package : https://pypi.org/project/lightgbm/

I also tried to update it by using python setup.py register , but it failed: Server response (410): This API is no longer supported, instead simply upload the file.

So I tried to upload the pkg-file, but sill met the error: ValueError: Unknown distribution format: 'PKG-INFO'

[computron]

I was able to get the description on PyPI to update for my package by:

1. Editing the "description" and "long_description" fields in the setup() function of setup.py
2. Releasing a new version of the code to PyPI (which still seems to work)

Without releasing a new version of the code, I also couldn't figure out a way to edit the description.

See also: https://docs.python.org/2/distutils/packageindex.html for more on the long_description field

[jeremyarr]

I would say it happens pretty frequently that you forgot to update a Trove Classifier or there was a typo in the long description field. It would be nice to be able to edit these fields for an existing release.

[hroest]

I would say it happens pretty frequently that you forgot to update a Trove Classifier or there was a typo in the long description field. It would be nice to be able to edit these fields for an existing release.

I agree, it would already be helpful if one could update the description by re-uploading a new version of the same file

[hroest]

another idea that came up in the chat log that would still let authors have some power over this:

• if the long_description differs from the one provided in the package there could be a big red box with a link to the original description, so that users can compare the original and modified install instructions

[J08nY]

Duplicate of #424. Still, no idea why the old API was shutdown, with the new one lacking any editing capability.

[swistakm]

I have stumbled upon it today. I use markdown or other markup in multiple a projects as a markup language of my READMEs (for a various reasons). It is a very common convention to use this README as a basis of long_description metadata field. Usually I use pypandoc or similar tool to convert my README to rst during sdist or wheel creation and this mostly works without any problems. Sometimes I have even to modify dynamically the README during creation of package distribution just before uploading it to PyPI.

In such cases no matter how much of automation you employ it is still easy to miss something or make mistake due to broken local dependency or incomplete environment. Till this time I have used to use setup.py register or twine register to just upload new updated/fixed metadata for given version of the package.

@computron's approach (using new release) is an approach that works well for simple packages that can be distributed as universal wheels or sdists. But it is very problematic for projects that require packages to be actually compiled.

I have some projects (like pyimgui or pyrilla) that depend on C extensions and their distributions needs to be created on multiple independent CI systems for various systems (3 different OS in 2 architecture flavours, 4 versions o Python). Full distribution consists of 25 built wheels and one sdist. It takes a lot of time to prepare whole set of distributions just for the purpose of fixing some README typo. It also takes a lot of space. Wheels for pyimgui project are about 32 MB. But think about projects like numpy. It has also more that 20 wheels and their size ranges from 6 to 15 MB each.

I understand that not requiring package pre-registration is a good step towards simplifying repository usage. Still it would be useful to have ability to modify/upload metadata independently from the actual package distributions. Note that metadata (mainly long description) describe one version of application that may consist of multiple distributions and not every distribution may be built in the same homogenic environment. It means that in more complex scenarios there may be some issues and metadata may not be consistent between different distributions (e.g. due to lack of pandoc on certain environment in my case). Selecting metadata of the first uploaded distribution as a representative of given package version is a reasonable approach that works in most of the situations but also create problems for some projects.

Also, I believe that having ability to easily modify metadata errors for packages (e.g. like using register endpoint) will have beneficial effect on the package repository content in the long term:

• It allows to limit infrastructure impact of users willing to correct their silly metadata mistakes. Think of re-uploading big numpy-like projects on every long description typo.
• Lowers the barrier for package owners. Allows to fix silly mistakes with minimal amount od additional work. On the other hand, users who browse and download packages will be more likely to get metadata of better quality.
• Reduces the package version inflation and this is beneficial for whole community.

[techtonik]

It could store edits separately, like GitHub shows that message is edited.

[jobec]

Bumped into the same issue.

While generating a wheel the DESCRIPTION.rst file got corrupted due to some strange bug (it added a > in front of a section header). I only noticed after uploading and now the description of my package is messed up, without any way to change the description but releasing a new version and manually modifying the DESCRIPTION.rst file in the weel...

The current situation is insane. Or you fully migrate, or leave the old features enabled untill you reach feature parity...

[jobec]

FYI:
Issue pypa/wheel#189 is what corrupted my package description.

[dstufft]

I realized I had not yet commented on this issue so here goes:

I'm not sure yet how we're going to treat this. On one hand it is fairly convenient to be able to do a quick bit of edit without making a new release of the project-- I've personally used that and I'm sure others have as well (As reflected by this issue!). On the other hand, allowing that means that the contents of the PyPI database differ from the contents of the packages themselves which is less than ideal given that many different downstream consumers of these projects want to consume the description of the projects too.

I don't believe either situation is more or less "right" or "sane", but rather represents a trade off. PyPI tends to have to make these kinds of trade offs between restricting what authors are allowed to do to provide downstream users with some sort of consistency in what they can expect and giving authors the power to manage their projects in the best way they personally see fit. I think that it is more common in other language packaging systems to not allow updates to this field than it is to allow updates (and the fact that PyPI ever supported it appears to me to be an accident) so I think it's certainly not unreasonable to not have this functionality (if that is the ultimate decision here).

Right now I'm leaning towards being fairly rigid in the guarantees of immutability and leaving this as it is (in addition likely fixing the data model to divide between truly file specific data and general data and guaranteeing the general data is the same for every file uploaded for a specific version).

I'm leaving this issue open so others can weigh in, and because I'm not fully settled on that being the right idea yet or not. One possible idea that I've been considering is the suggestions from above about allowing edits, but retaining a sort of history or adding an indicator that it has been edited from the "true" description inside of the package. My main concern with that is that if it's just history, then I'm not sure that people will generally find it useful-- but if it's some sort of a red warning box, then that is making editing the description painful for little benefit over just allowing it without warning and likely will introduce "warning fatigue".

So basically, I'm not entirely sure yet how the future looks for this feature.

[jobec]

Why not allow package versions to be "staged"?

You can then see if everything is correct without others seeing the package. In that status you can then make changes and even update the files.

The next step is then to "publish" the packages, after which it becomes immutable and visible for everyone.

[xavfernandez]

Why not allow package versions to be "staged"?

cf #726 :)

[dstufft]

Yea, I am entirely on board with staged releases-- and it hadn't occurred to me util you mentioned it that they could act as a mechanism for this as well. I think that is likely going to be the long term answer here, that if you want to preview things before they go live, use the staging functionality (yet to be implemented) but once things are published they are immutable.

[ryukinix]

This is really annoying. :/
But ok, at least a wont-fix tag was not marked as some development teams do about crucial UX problems.

[bskinn]

I think immutability is an important feature of the final, published packages and should be kept.

But a major point of stress in uploading releases is not knowing how my README.rst is going to render on PyPI. Yes, there's testpypi, but I have to keep changing my version in setup.py, which is annoying (v1.2.1.post112....) AND I have to remember to change it back to the actual version number before uploading to "regular" PyPI.

I agree, the staged upload/release approach seems very appealing.

[dstufft]

You can also use readme_renderer to render your readme.

[bskinn]

@dstufft Where does the python setup.py check -r -s invocation put the rendered readme?

Nothing shows up with a dir /s *.htm*.

[di]

@bskinn That command doesn't output any HTML, it will show warnings if there are issues with the long_description, otherwise it will say nothing and return with an exit code of 0.

[bskinn]

<nod>, gotcha.

So -- if I read the readme_renderer source right, there's no script entry point to actually carry out the translation locally? To get HTML I need to do something like this?

>>> from readme_renderer import rst

>>> with open('README.rst', 'r') as f:
...     text = f.read()

>>> with open('README.html', 'w') as f:
...     f.write(rst.render(text))

[pjeby]

And yet, somehow the previous version of PyPI was able to do such changes, because it was originally a package index for humans, and didn't even support uploading files when it was first created.

But somehow, the utility of being a place where humans can find out about Python projects has now been re-labeled as "vanity". And important functionality was dropped without notice to PyPI users. When other PyPI functionality was dropped, PEPs were needed with notices periods being sent to maintainers, but removing a feature from the UI? Nah, who actually edits their package. Who cares. And we'll just break setup.py register while we're at it. Oh, people are complaining? Too bad, we already changed it.

Running manual updates for "installability" is just the icing on the cake. It demonstrates that the capability to edit release metadata is in fact needed, and all the platitudes about not needing to do it are just that: platitudes defending the purity of the system, when practicality beats purity.

In the pure land, nobody needs to edit metadata and should output new binaries. In the real world, stuff happens. (And a package listing isn't solely for automated consumption.)

[ewdurbin]

First I want to clarify that the word vanity was used not in a derogatory sense, but to try to indicate information which was not functional for installation purposes. Clearly my use of scare quotes around the word didn't help. I apologize for this word choice, it obviously struck a chord.

Second, it was obviously a mistake to provide this support to pytest and Django without a larger discussion. This issue in particular started as a place to track the concern of updating descriptions for projects and has continued well past that specific concern and into a wider one around arbitrary edits of package metadata.

I'm not sure where to go from here, but I am frustrated and feeling down about the whole thing now.

[bskinn]

The model of 'write-once per-release metadata' implicitly assumes that the metadata, and the knowledge underlying its composition, are both perfectly complete and perfectly accurate for each release at the time the release is made.

It's a stretch to think these assumptions hold for any one release of any distribution, much less all releases of all distributions.

I understand the impulse toward immutability, in terms of avoiding 'noncritical post-release updates' to metadata. But, as the pytest and Django examples show, strict immutability means that critical post-release updates are also locked out.

I see two (non-exclusive-exhaustive) general paths forward, personally:

1. Unmanaged post-release updates. 'Noncritical' updates are accepted as an unavoidable cost of allowing 'critical' updates, with the benefit of reduced ongoing burden on PyPA staff due to not having to intermediate the updates

2. Managed post-release updates. Post-release updates are effected by petition to PyPA staff, with case-by-case approval. Disadvantage here is the ongoing burden on PyPA staff both as re the time involved, and as re being the arbiters of criticality. A further risk is that denied petitions may engender ill will.

In both cases, perhaps some of the metadata can be declared as universally disallowed for post-release updates. This would probably still be fraught with edge cases, though.

[pjeby]

Conversely, perhaps some of the metadata could be universally allowed to change independently, such as changes in maintainers, support contact, home page, etc.

After all, none of these attributes are really about the release in the first place. They're about the project, and can change independently of the project's releases or lack thereof. (For example, if a project's issue tracker or home page moves, visiting the old page is not useful even if you are working with an older version. Likewise, a URL such as this changing is not really a reason to issue a new release of a project.)

[EmilStenstrom]

Another use-case: I have a README.md in the project (on github), but I forgot to add it to long_description. So my use-case is not a typo, but making sure PyPI is in sync with GitHub.

[bskinn]

@EmilStenstrom Especially given the intentional behavior change from legacy PyPI to Warehouse disabling automatic introspection for README.rst, I suspect there are a lot of projects (some of mine included) that could benefit from being able to make this kind of change post facto.

[jobec]

Well, according to https://mail.python.org/pipermail/distutils-sig/2017-December/031826.html and despite the numerous reactions here this decision seems final 😞

(Unless your package is like Django, then all of a sudden direct database changes are possible...)

[ewdurbin]

Howdy! I still feel shitty about how the entire Django metadata/python_requires situation went down. Dragging it up does more harm to my morale/person than it does to driving the conversation forward, @jobec.

Clearly this was a departure from the stated policy and a mistake.

I don't take actions on the index lightly. In the case of Django's botched python_requires setting, it was causing uninstallable versions of Django to be delivered to clients who were doing everything else right. Ultimately having the inaugural version of Django dropping Python 2 support involved caught the better of me in being eager to help.

Moving forward I'll expressly avoid such intervention. The policy for PyPI is immutable metadata.

This is no longer a feature discussion. Future comments on this discussion that fly snark in passing won't be tolerated. Please be mindful of the impact that words have on the folks who are eager to help the community.

[jaraco]

I'd like to add another use-case to the discussion above. Today, I'm making the first update to https://pypi.org/project/backports, a project with nothing but metadata. That is, it has no code and no downloads. I'd like to update the project without uploading any new artifacts or creating any new versions. It would be nice if there were a way to perform the equivalent operation, something like twine refresh-metadata dist/backports*.tar.gz (or twine register dist/*).

[pradyunsg]

@jaraco Please file a new issue to discuss this, rather than commenting on a closed and locked issue from almost three years ago.

[pradyunsg]

Unlocked and relocked to surface any x-refs made over the last three years.

#4816 is probably where you want to comment.