Warn that data_files is deprecated in the packaging guide

[cdfarrow]

According to the keywords article data_files has been deprecated. This should be made clear in this section.

[abravalheri]

Hi @cdfarrow, the status of data_files is complicated :tm:.

There are several people that reach for using data_files when they actually should be exploring another approach (e.g. populating $XDG_DATA_HOME/$XDG_CONFIG_HOME/$XDG_STATE_HOME on the first run of the program - see https://github.com/platformdirs/platformdirs), or simply placing the files inside the package directory.

But there is one particular use case that is genuine:

• A library/program that allows plugins to specify non-Python packages (e.g. CSS/JS/HTML) AND the number of plugins is so big that it is impossible to use entry-point mechanisms for advertising these files without causing huge performance impairments.

The only example that I know of is Jupyter.

For this reason, I don't think data_files is going to be removed anytime soon. My opinion is that we have to change setuptools to either:

1. Provide a different (simplified) mechanism with better docs explaining that it is a "last-resort" technique.
2. OR at least update the existing setuptools docs also explaining it is a "last-resort" technique instead of saying it is deprecated.

[cdfarrow]

My opinion is that we have to change setuptools to either:

1. Provide a different (simplified) mechanism with better docs explaining that it is a "last-resort" technique.
2. OR at least update the existing setuptools docs also explaining it is a "last-resort" technique instead of saying it is deprecated.

#1 sounds like a good path forward; but at least updating the docs to explain what you've said and making them consistent would be really helpful.

[abravalheri]

I will work on the setuptools docs to explain 2. for the time being.

[tdpetrou]

Hi @abravalheri, do you think it's possible to update the docs to include the instructions for data_files? The only mention I can find of how to use this feature is here. And that is within the context of setup.py. For pyproject.toml users, there is no guidance, though you can infer from the package data section that the general form is

[tool.setuptools.data-files]
"some/location/on/users/machine" = ["location/in/package/directory"]

I have a couple packages that extend jupyter that require this. So, in my particular case, the section would become:

[tool.setuptools.data-files]
"etc/jupyter/nbconfig/notebook.d" = ["jupyter-config/nbconfig/notebook.d/dataframe_image.json"]

Jupyter documentation also contains a section with how to accomplish this in setup.py. It would be nice if the official setuptools documentation also showcased this feature.