a bit more on including files in packages

Author: PythonCHB

source/exercises/mailroom/mailroom-pkg.rst

@@ -50,8 +50,6 @@ Put all these in a python package structure, something like this::
               __init__.py
               test_model.py
               test_cli.py
-      bin
-          mailman.py
 
 You will need to import the logic code from model.py in the cli code in order to use it. You can wait until you learn about mocking to write the code in test_cli.py (so you can leave that out)
 
@@ -61,11 +59,13 @@ Now write your ``setup.py`` to support your package.
 Making the top-level script runnable
 ------------------------------------
 
-To get the script installed you have two options. I prefer the more straightforward one, `the scripts keyword argument <http://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-scripts-keyword-argument>`_
+To get the script installed you have two options. I used to prefer the more straightforward one, `the scripts keyword argument <http://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-scripts-keyword-argument>`_
 
-But if you want to get fancy, you can use ``setuptools``'s `entry points <http://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-console-scripts-entry-point>`_
+But it turns out that while the simple ``scripts`` keyword argument method works well and is simple, it may not work as well on Windows -- it relies in your script being named ``something.py`` and that Windows is configured to run all files with ``.py`` extensions. Not all windows systems are set up this way. But the "entry points" method builds a little exe file to call your script, so it's more reliable.
 
-.. note:: On Unix systems, including the Mac, the simple ``scripts`` keyword argument method works well and is simple. But it may not work as well on Windows -- it relies in your script being named ``something.py`` and that Windows is configured to run all files with ``.py`` extensions. Not all windows systems are set up this way. But the "entry points" method builds a little exe file to call your script, so it's more reliable.
+And the Python community has moved very much towards using setuptools entry points, so That's really the way to go now:
+
+http://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-console-scripts-entry-point
 
 
 Including data files

source/modules/Packaging.rst

@@ -1086,10 +1086,16 @@ I personally like the simplest one with the least magic:
       ...
         )
 
+This is a dict with the keys being the package(s) you want to add data files to. This is required, as a single setup command can install more than one package. The value(s) is a list of filenames, *relative to the package* - note that in the above example, the "pkg_name" is not part of the path to the file.
+
+WARNING: For some reason, setuptools does not give you an error or warning if it can't find the files you specify -- which is a real shame - makes it harder to debug.
+
 https://packaging.python.org/tutorials/distributing-packages/#package-data
 
 Then you'll get the data file included in the package in the same place relative to your code regardless of how (or whether) it is installed.
 
+.. note:: Debugging package building can be kind of tricky: if you install the package, and it doesn't work, what went wrong?!? One approach that can help is to "build" the package, separately from installing it. setuptools provides a build command: ``python setup.py build`` that does just that. It will create a ``build`` directory, and in there, a ``lib`` dir. In there is what will actually get installed -- your "built" package. So you can look there and see if your data files are getting included, and everything else about the package.
+
 Now you'll need to write your code to find that data file. You can do that by using the ``__file__`` module attribute -- then the location of the data file will be relative to the ``__file__`` that your code is in. A little massaging with a ``pathlib.Path`` should do it. Putting the path to the data directory in the package's ``__init__.py`` provides a way for the rest of your code to find it.
 
 In ``pkg_name/__init__.py``: