Transitioning to setuptools

Deprecation of d2to1: Transitioning to setuptools

In the world of software development, technology is constantly evolving and improving. As a result, some tools and frameworks become outdated and are eventually deprecated. One such tool is d2to1, a project that aimed to provide functionality from the long-defunct distutils2/packaging project on top of classic distutils/setuptools. However, I regret to inform you that the d2to1 project has been deprecated and will no longer receive updates.

But fear not! The functionality that d2to1 offered is now available in plain setuptools. In fact, setuptools has supported package configuration declaratively through the setup.cfg file for quite some time now, making it a powerful and complete alternative.

Porting from d2to1 to setuptools

If you were using d2to1 and would like to transition to setuptools, here’s a brief guide on how to port your existing setup.cfg files:

• The options in the [metadata] section of setup.cfg remain largely the same, with a few exceptions:

  • summary -> description: The short description of your package should now be placed in the description option. Although summary still works as an alias, it is recommended to use description.
  • description-file -> long_description: file:: If you had a longer description (typically a README) for your package, it can now be specified in the long_description option. You can use the file: <file1>, <file2>, ... format to read the long description from one or more files listed as relative paths in your repository. This format is also available in other options. Check out the documentation for more details.
  • home-page -> url: Although home-page is still allowed as an alias for url, it is discouraged to use it.
  • classifier -> classifiers: Similarly, classifier is still accepted as an alias, but its use is discouraged.
  • requires-dist -> options.install_requires: The requires-dist option should be moved to the [options] section of your setup.cfg. It is now equivalent to the install_requires keyword in the setup() function of setuptools.

• The [files] section in setup.cfg no longer exists. Instead, most options that were under [files] are now placed in a section called [options]. This includes packages, package_dir, scripts, and install_requires, among others.

• For options that accept values consisting of <key> = <value> pairs, there are dedicated sections in the new setuptools format, such as [options.package_data], [options.data_files], [options.extras_require], and [options.entry_points].

To help you understand the transition better, here’s an example of how the old setup.cfg file from d2to1 can be ported to the new format:

“`
[metadata]
name = d2to1
version = 0.2.12
author = Erik M. Bray
author_email = embray@stsci.edu
description = Allows using distutils2-like setup.cfg files for a package’s metadata with a distribute/setuptools setup.py
long_description = file: README.rst, CHANGES.rst
url = http://pypi.python.org/pypi/d2to1
classifiers =
Development Status :: 5 – Production/Stable
Environment :: Plugins
Framework :: Setuptools Plugin
Intended Audience :: Developers
License :: OSI Approved :: BSD License
Operating System :: OS Independent
Programming Language :: Python
Programming Language :: Python :: 3
Topic :: Software Development :: Build Tools
Topic :: Software Development :: Libraries :: Python Modules
Topic :: System :: Archiving :: Packaging

[options]
packages = d2to1, d2to1.extern
install_requires = setuptools
tests_require = nose

[options.entry_points]
distutils.setup_keywords =
d2to1 = d2to1.core:d2to1
zest.releaser.prereleaser.middle =
d2_version = d2to1.zestreleaser:prereleaser_middle
zest.releaser.postreleaser.middle =
d2_version = d2to1.zestreleaser:postreleaser_middle
“`

In the above example, you can see how the options have been rearranged to fit the new setuptools format.

Embracing the Future of Package Configuration

Setuptools offers a robust and feature-rich solution for configuring your Python packages. While d2to1 served as a valuable tool during its time, it is now time to transition to setuptools and take advantage of its extensive capabilities.

By adopting setuptools, you ensure that your package remains compatible with the latest standards and practices in the Python community. It also opens up opportunities to leverage new features and enhancements as they are introduced.

Conclusion and Next Steps

Although it may require some effort to port your existing setup.cfg files from d2to1 to setuptools, it is a worthwhile investment to ensure the longevity and compatibility of your projects. The transition will enable you to continue using declarative package configuration and take advantage of the full capabilities of setuptools.

For a detailed guide on using setuptools and its various features, refer to the official documentation. Don’t forget to update your project’s README and other relevant files to reflect these changes. With the deprecation of d2to1, now is the perfect time to embrace the future of package configuration and make the switch to setuptools.

Remember, progress is inevitable, and adapting to change is a crucial aspect of success in the ever-evolving world of technology.