Deprecation of d2to1: Migrating to the New setuptools Configuration
In the rapidly evolving world of software development, it’s not uncommon for projects to become deprecated as new, improved alternatives emerge. One such project that has recently been deprecated is d2to1. Initially designed to provide distutils2-like functionality on top of setuptools, d2to1 allowed developers to use setup.cfg files for a package’s metadata with a distribute/setuptools setup.py script.
However, with the introduction of new features and enhancements in setuptools, the functionality provided by d2to1 is now available natively and is fairly complete. As a result, the project has been deemed deprecated and will no longer be updated.
Porting Your setup.cfg Files
If you’ve been using d2to1 for your projects, it’s important to migrate your setup.cfg files to the latest version of setuptools. While the overall structure and format of the configuration files remain similar, there are a few slight differences in section names and syntax. Here’s a brief guide to help you with the migration process:
- The [metadata] section: Most options in this section remain the same. However, there are a few changes to be aware of:
- “summary” is now “description”: The short description of the package should be placed in the “description” option. The “summary” option is still available as an alias for “description”.
- “description-file” is now “long_description: file:”: The longer description, typically a README file, goes in the “long_description” option. You can specify multiple files using the “file: , , …” format.
- “home-page” is now “url”: While “home-page” is still allowed as an alias, its use is discouraged.
- “classifier” is now “classifiers”: “classifier” is still allowed as an alias, but its use is discouraged.
- “requires-dist” is now “options.install_requires”: This option should be moved to the “[options]” section of setup.cfg.
- The [files] section: This section no longer exists in the new setuptools format. Most options that were under this section now go under “[options]”. Here are a few notable changes:
- “packages”, “package_dir”, and “scripts” are now under “[options]”: These options, along with “install_requires”, should be placed under the “[options]” section.
- “options.packages.find”: This option supports a special value “find:”, which automatically includes any packages found at the root of the repository or under the specified “package_dir” directory. Additional options can be passed in the “[options.packages.find]” section to control how packages are searched.
- Other sections: Options that take values consisting of one or more ” = ” pairs now have their own sections:
- “[options.package_data]”: Use this section to specify package data files.
- “[options.data_files]”: Use this section to include additional data files.
- “[options.extras_require]”: Use this section to specify dependencies for optional features.
- “[options.entry_points]”: Use this section to define entry points for plugins and extensions.
Example Migration
Let’s take a look at an example setup.cfg file from d2to1 and see how it can be migrated 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
Using the new setuptools format, the setup.cfg file will look like this:
[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 = find:
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
Conclusion
In conclusion, the deprecation of d2to1 marks a shift towards using the native features of setuptools for package configuration. With the knowledge gained from this article, you can confidently migrate your setup.cfg files to the latest version of setuptools, ensuring compatibility with the latest industry standards and best practices.
Remember to carefully review the changes in section names and syntax, update the options accordingly, and use the appropriate sections for specific values. Following these guidelines will ensure a smooth transition and compatibility with future enhancements in setuptools.
If you have any questions or need further assistance with the migration process, don’t hesitate to reach out to the community or consult the official setuptools documentation. Happy migrating!
Leave a Reply