DEPRECATED -- Rewritten and moved to 🌊 Shore is a distribution and release management tool for pure Python packages.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

45 lines
1.7 KiB

4 months ago
  1. # Package Data
  2. There are two methods in which additional files can be shipped alongside a
  3. Python package: "data files" and "package data". While files from the former
  4. will be copied into a folder relative to `sys.prefix`, files from the latter
  5. will be installed alongside the package and should be accessed with the
  6. `pkg_resources` module.
  7. Using "data files" usually requires some more effort to make it work with an
  8. editable installation of your package during development (detecting that your
  9. package is currently installed in editable mode and looking for the files in
  10. a different location), thus using "package data" is usually the preferred
  11. method. However if your additional files contain binaries that need to be
  12. present on the file system, "data files" is the better bet.
  13. "Data files" are configured with a special option called `datafiles` which
  14. consists of alist of strings that define which files are to be copied to
  15. what location inside `sys.prefix` as well as patterns for the files to copy.
  16. The syntax is `<src>[:<dst>],<pattern>,<pattern>...`.
  17. ```yaml
  18. datafiles:
  19. - src/datafiles,file.txt
  20. - src/datafiles:data,!file.txt
  21. ```
  22. > Data files are always prefixed with `data/<packagename>`, thus to access the
  23. > file at runtime you must add that to the path like this:
  24. >
  25. > ```py
  26. > os.path.join(sys.prefix, 'data', 'mypackage', 'file.txt')
  27. > ```
  28. "Package files" on the other hand can be included by simply specifying them
  29. in the `` file.
  30. ```yaml
  31. manifest:
  32. - include src/mypackage/data/file.txt
  33. - recursive-include src/mypackage/data/models *.bin
  34. ```
  35. > Tip: You can use the `shore build` command to produce a distribution archive
  36. > of your package, which you can inspect to ensure the (package) data files
  37. > are included as expected.