From bc618da735a02a1cebb85fd979ccdd317b308276 Mon Sep 17 00:00:00 2001 From: Alexey Kotlyarov Date: Thu, 17 Mar 2016 16:06:41 +1100 Subject: [PATCH 1/2] Remove CVS and Subversion references in include_package_data docs --- docs/setuptools.txt | 96 +++++++++++++++++---------------------------- 1 file changed, 35 insertions(+), 61 deletions(-) diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 610a0e613d..d267bf2914 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -258,10 +258,9 @@ unless you need the associated ``setuptools`` feature. ``include_package_data`` If set to ``True``, this tells ``setuptools`` to automatically include any - data files it finds inside your package directories, that are either under - CVS or Subversion control, or which are specified by your ``MANIFEST.in`` - file. For more information, see the section below on `Including Data - Files`_. + data files it finds inside your package directories that are specified by + your ``MANIFEST.in`` file. For more information, see the section below on + `Including Data Files`_. ``exclude_package_data`` A dictionary mapping package names to lists of glob patterns that should @@ -785,17 +784,15 @@ e.g.:: ) This tells setuptools to install any data files it finds in your packages. -The data files must be under CVS or Subversion control, or else they must be -specified via the distutils' ``MANIFEST.in`` file. (They can also be tracked -by another revision control system, using an appropriate plugin. See the -section below on `Adding Support for Other Revision Control Systems`_ for -information on how to write such plugins.) - -If the data files are not under version control, or are not in a supported -version control system, or if you want finer-grained control over what files -are included (for example, if you have documentation files in your package -directories and want to exclude them from installation), then you can also use -the ``package_data`` keyword, e.g.:: +The data files must be specified via the distutils' ``MANIFEST.in`` file. +(They can also be tracked by a revision control system, using an appropriate +plugin. See the section below on `Adding Support for Revision Control +Systems`_ for information on how to write such plugins.) + +If you want finer-grained control over what files are included (for example, +if you have documentation files in your package directories and want to exclude +them from installation), then you can also use the ``package_data`` keyword, +e.g.:: from setuptools import setup, find_packages setup( @@ -853,8 +850,7 @@ converts slashes to appropriate platform-specific separators at build time. Python 2.4; there is `some documentation for the feature`__ available on the python.org website. If using the setuptools-specific ``include_package_data`` argument, files specified by ``package_data`` will *not* be automatically -added to the manifest unless they are tracked by a supported version control -system, or are listed in the MANIFEST.in file.) +added to the manifest unless they are listed in the MANIFEST.in file.) __ http://docs.python.org/dist/node11.html @@ -887,8 +883,7 @@ included as a result of using ``include_package_data``. In summary, the three options allow you to: ``include_package_data`` - Accept all data files and directories matched by ``MANIFEST.in`` or found - in source control. + Accept all data files and directories matched by ``MANIFEST.in``. ``package_data`` Specify additional patterns to match files and directories that may or may @@ -1231,15 +1226,14 @@ Your Project's Dependencies target audience isn't able to compile packages (e.g. most Windows users) and your package or some of its dependencies include C code. -Subversion or CVS Users and Co-Developers +Revision Control System Users and Co-Developers Users and co-developers who are tracking your in-development code using - CVS, Subversion, or some other revision control system should probably read - this manual's sections regarding such development. Alternately, you may - wish to create a quick-reference guide containing the tips from this manual - that apply to your particular situation. For example, if you recommend - that people use ``setup.py develop`` when tracking your in-development - code, you should let them know that this needs to be run after every update - or commit. + a revision control system should probably read this manual's sections + regarding such development. Alternately, you may wish to create a + quick-reference guide containing the tips from this manual that apply to + your particular situation. For example, if you recommend that people use + ``setup.py develop`` when tracking your in-development code, you should let + them know that this needs to be run after every update or commit. Similarly, if you remove modules or data files from your project, you should remind them to run ``setup.py clean --all`` and delete any obsolete @@ -1467,25 +1461,10 @@ use the appropriate defaults.) Generating Source Distributions ------------------------------- -``setuptools`` enhances the distutils' default algorithm for source file -selection, so that all files managed by CVS or Subversion in your project tree -are included in any source distribution you build. This is a big improvement -over having to manually write a ``MANIFEST.in`` file and try to keep it in -sync with your project. So, if you are using CVS or Subversion, and your -source distributions only need to include files that you're tracking in -revision control, don't create a ``MANIFEST.in`` file for your project. -(And, if you already have one, you might consider deleting it the next time -you would otherwise have to change it.) - -(NOTE: other revision control systems besides CVS and Subversion can be -supported using plugins; see the section below on `Adding Support for Other -Revision Control Systems`_ for information on how to write such plugins.) - -If you need to include automatically generated files, or files that are kept in -an unsupported revision control system, you'll need to create a ``MANIFEST.in`` -file to specify any files that the default file location algorithm doesn't -catch. See the distutils documentation for more information on the format of -the ``MANIFEST.in`` file. +If you need to include automatically generated files, you'll need to create a +``MANIFEST.in`` file to specify any files that the default file location +algorithm doesn't catch. See the distutils documentation for more information +on the format of the ``MANIFEST.in`` file. But, be sure to ignore any part of the distutils documentation that deals with ``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you @@ -1501,12 +1480,6 @@ the options that the distutils' more complex ``sdist`` process requires. For all practical purposes, you'll probably use only the ``--formats`` option, if you use any option at all. -(By the way, if you're using some other revision control system, you might -consider creating and publishing a `revision control plugin for setuptools`_.) - - -.. _revision control plugin for setuptools: `Adding Support for Other Revision Control Systems`_ - Making your package available for EasyInstall --------------------------------------------- @@ -1687,9 +1660,10 @@ Of course, for this to work, your source distributions must include the C code generated by Pyrex, as well as your original ``.pyx`` files. This means that you will probably want to include current ``.c`` files in your revision control system, rebuilding them whenever you check changes in for the ``.pyx`` -source files. This will ensure that people tracking your project in CVS or -Subversion will be able to build it even if they don't have Pyrex installed, -and that your source releases will be similarly usable with or without Pyrex. +source files. This will ensure that people tracking your project in a revision +control system will be able to build it even if they don't have Pyrex +installed, and that your source releases will be similarly usable with or +without Pyrex. ----------------- @@ -2569,15 +2543,15 @@ the ``cmd`` object's ``write_file()``, ``delete_file()``, and those methods' docstrings for more details. -Adding Support for Other Revision Control Systems +Adding Support for Revision Control Systems ------------------------------------------------- If you would like to create a plugin for ``setuptools`` to find files in -source control systems, you can do so by adding an -entry point to the ``setuptools.file_finders`` group. The entry point should -be a function accepting a single directory name, and should yield -all the filenames within that directory (and any subdirectories thereof) that -are under revision control. +source control systems, you can do so by adding an entry point to the +``setuptools.file_finders`` group. The entry point should be a function +accepting a single directory name, and should yield all the filenames within +that directory (and any subdirectories thereof) that are under revision +control. For example, if you were going to create a plugin for a revision control system called "foobar", you would write a function something like this: From 741f3bbcbbbd73076a44100a0e112f6dd86864b6 Mon Sep 17 00:00:00 2001 From: Alexey Kotlyarov Date: Sun, 20 Mar 2016 20:27:59 +1100 Subject: [PATCH 2/2] Point towards SCM plugins for including source files --- docs/setuptools.txt | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/setuptools.txt b/docs/setuptools.txt index d267bf2914..886216ea37 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -1461,10 +1461,18 @@ use the appropriate defaults.) Generating Source Distributions ------------------------------- -If you need to include automatically generated files, you'll need to create a -``MANIFEST.in`` file to specify any files that the default file location -algorithm doesn't catch. See the distutils documentation for more information -on the format of the ``MANIFEST.in`` file. +``setuptools`` enhances the distutils' default algorithm for source file +selection with pluggable endpoints for looking up files to include. If you are +using a revision control system, and your source distributions only need to +include files that you're tracking in revision control, use a corresponding +plugin instead of writing a ``MANIFEST.in`` file. See the section below on +`Adding Support for Revision Control Systems`_ for information on plugins. + +If you need to include automatically generated files, or files that are kept in +an unsupported revision control system, you'll need to create a ``MANIFEST.in`` +file to specify any files that the default file location algorithm doesn't +catch. See the distutils documentation for more information on the format of +the ``MANIFEST.in`` file. But, be sure to ignore any part of the distutils documentation that deals with ``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you @@ -2546,9 +2554,15 @@ those methods' docstrings for more details. Adding Support for Revision Control Systems ------------------------------------------------- -If you would like to create a plugin for ``setuptools`` to find files in -source control systems, you can do so by adding an entry point to the -``setuptools.file_finders`` group. The entry point should be a function +If the files you want to include in the source distribution are tracked using +Git, Mercurial or SVN, you can use the following packages to achieve that: + +- Git and Mercurial: `setuptools_scm `_ +- SVN: `setuptools_svn `_ + +If you would like to create a plugin for ``setuptools`` to find files tracked +by another revision control system, you can do so by adding an entry point to +the ``setuptools.file_finders`` group. The entry point should be a function accepting a single directory name, and should yield all the filenames within that directory (and any subdirectories thereof) that are under revision control.