Guide how to images for projects; screenshots; logos; guides; gifs; videos

[illume]

... and such?

People often use images videos and such in their project descriptions. For screenshots, for guides, and various other things.

How should these be included?

[jeanas]

@illume Can you elaborate please?

[sinoroc]

Maybe you mean how to add "package data" (non Python files) to the distributions so that they get installed? If yes, then I agree it would be good to have such a guide and/or tutorial.

[jeanas]

Ah, maybe. But then, this is really dependent on the build backend. I think this should be left to individual backend docs since it will tend to get outdated if it's not maintained by the same people as the backends. See also #1377.

[sinoroc]

I think we should have at least a page explaining the non-tool specific principles of solving this common problem.

Some ideas:

• Give the right vocabulary ("package data" not "data files", because of setuptools).
• Explain things about size upload limit on PyPI.
• Explain how to choose if files belong in sdist or wheel or both.
• Explain general principles of how to generate package data files during build process.
• Explain where package data will end up (in site-packages/top_level_import_package), and that it can not be anywhere else (no man files or icons) unless using some OS native packaging method (apt .deb, yum .rpm, pacman, etc.).
• Explain how to access these files (importlib.resources).
• Explain that there is no install-time script, so we can not write default config files in the user's home directory or anything like this.

Probably it should be a discussion (not a tutorial or a guide).

[jeanas]

Ok, good idea.

Explain how to choose if files belong in sdist or wheel or both.

A tricky question since there is, AFAIK, no consensus on that.

https://discuss.python.org/t/should-sdists-include-docs-and-tests/14578

https://discuss.python.org/t/sdists-for-pure-python-projects/25191/39

[illume]

People often use images videos and such in their project descriptions. For screenshots, for guides, and various other things.

How should these be included?

[jeanas]

You'd put the image in some permanent location, e.g., inside your repository, and link it with standard Markdown or reST syntax in your README.md / README.rst, e.g., ![Alt text](https://github.com/...).

[sinoroc]

You'd put the image in some permanent location, e.g., inside your repository, and link it with standard Markdown or reST syntax in your README.md / README.rst, e.g., ![Alt text](https://github.com/...).

I would rather use paths relative to the location of the README file.

For example my-project/README.md could have ![A great screenshot](my-project/docs/assets/screenshots/great.png). As far as I can tell GitHub and other similar code forges (GitLab, and so on) are able to handle this. And also if I get the source distribution of your project and look at the README locally on my computer without being connected to internet it should still work (my Markdown viewer program can find the screenshot).

But @illume, that is not specific to Python or Python packaging.

[illume]

What works on Pypi?

At some point it was filtering out external links. Not sure about now.

Not sure where or if this is specified anywhere.

[sinoroc]

What works on Pypi?

At some point it was filtering out external links. Not sure about now.

Not sure where or if this is specified anywhere.

Ah right... PyPI... I do not know. I guess there you can not use relative paths for images. The solution is probably to use public URLs.

Personally I believe READMEs should contain only text. If I were to want to show screenshots, then I would put these screenshots on a separate website (something like Sphinx-built GitHub/GitLab pages or ReadTheDocs), and put a link to this website in the README. Then all the sources to build the website would be in the docs directory at the root of the source code repository and probably also in the sdist.

[jeanas]

What works on Pypi?

I just did a test here:

https://test.pypi.org/project/readme-rendering-test-jeanas/

Package source: readme-rendering-test-jeanas.zip

It appears that:

• PyPI supports external image URLs
• PyPI does not support local files included in the distribution — unsurprising
• PyPI does not support base64-encoded data in the image URL — I didn't expect it, but it's not very surprising either.

So, it's like I said: you should use an external URL.

You can also look at the project page of PDM as an example. Source here

[jeanas]

Personally I believe READMEs should contain only text. If I were to want to show screenshots, then I would put these screenshots on a separate website

It can be quite useful though, e.g., to quickly understand what a project does without having to click another link. Some projects like GUIs can be difficult to give an idea of in words only.

[sinoroc]

It appears that:

* PyPI supports external image URLs

* PyPI does not support local files included in the distribution — unsurprising

* PyPI does not support base64-encoded data in the image URL — I didn't expect it, but it's not very surprising either.

That is useful info. It could be added to https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/

[illume]

Good research! I was pretty sure it blocked external images at one point (maybe even when I opened this issue a couple of years ago). But you're right it does appear they are working. I guess this is privacy violation for pypi? https://www.python.org/privacy/ Because anyone can put up a link to any image it seems (and therefore drop any type of cookie). Maybe it's blocking cookies somehow.

I see github markdown does NOT support base64 encoded images in markdown github/markup#270 (and probably never will). So it probably makes sense for pypi to also not support it.

There's an example README.rst here that uses images: https://pypi.org/project/pygame/ source

[illume]

It appears that:

* PyPI supports external image URLs

* PyPI does not support local files included in the distribution — unsurprising

* PyPI does not support base64-encoded data in the image URL — I didn't expect it, but it's not very surprising either.

That is useful info. It could be added to https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/

Yes, that does seem the best place to put this information.

Also some examples of badges and a logo. (in markdown and restructured text).