Entrypoints: extending/changing zest.releaser ============================================= A zest.releaser entrypoint gets passed a data dictionary and that's about it. You can do tasks like generating documentation. Or downloading external files you don't want to store in your repository but that you do want to have included in your egg. Every release step (prerelease, release and postrelease) has three points where you can hook in an entry point: before Only the ``workingdir`` and ``name`` are available in the data dictionary, nothing has happened yet. middle All data dictionary items are available and some questions (like new version number) have been asked. No filesystem changes have been made yet. after The action has happened, everything has been written to disk or uploaded to pypi or whatever. For the release step it made sense to create one extra entry point: after_checkout The middle entry point has been handled, the tag has been made, a checkout of that tag has been made and we are now in that checkout directory. Of course, when the user chooses not to do a checkout, this entry point never triggers. Note that an entry point can be specific for one package (usually the package that you are now releasing) or generic for all packages. An example of a generic one is `gocept.zestreleaser.customupload`_, which offers to upload the generated distribution to a chosen destination (like a server for internal company use). If your entry point is specific for the current package only, you should add an extra check to make sure it is not run while releasing other packages; something like this should do the trick:: def my_entry_point(data): if data['name'] != 'my.package': return ... .. _`gocept.zestreleaser.customupload`: http://pypi.python.org/pypi/gocept.zestreleaser.customupload Entry point specification ------------------------- An entry point is configured like this in your setup.py:: entry_points={ #'console_scripts': [ # 'myscript = my.package.scripts:main'], 'zest.releaser.prereleaser.middle': [ 'dosomething = my.package.some:some_entrypoint', ]}, Replace ``prereleaser`` and ``middle`` in ``zest.releaser.prereleaser.middle`` with prerelease/release/postrelease and before/middle/after where needed. See the ``setup.py`` of ``zest.releaser`` itself for some real world examples. You'll have to make sure that the zest.releaser scripts know about your entry points, for instance by placing your egg (with entry point) in the same zc.recipe.egg section in your buildout as where you placed zest.releaser. Or, if you installed zest.releaser globally, your egg-with-entrypoint has to be globally installed, too. Comments about data dict items ------------------------------ Your entry point gets a data dictionary: the items you get in that dictionary are documented below. Some comments about them: - Not all items are available. If no history/changelog file is found, there won't be any ``data['history_lines']`` either. - Items that are templates are normal python string templates. They use dictionary replacement: they're actually passed the same data dict. For instance, prerelease's ``data['commit_message']`` is by default ``Preparing release %(new_version)s``. A "middle" entry point could modify this template to get a different commit message. .. ### AUTOGENERATED FROM HERE ### Prerelease data dict items -------------------------- commit_msg Message template used when committing history_file Filename of history/changelog file (when found) history_header Header template used for 1st history header history_lines List with all history file lines (when found) name Name of the project being released new_version New version (so 1.0 instead of 1.0dev) original_version Version before prereleasing (e.g. 1.0dev) today Date string used in history header workingdir Original working directory Release data dict items ----------------------- name Name of the project being released tag_already_exists Internal detail, don't touch this :-) tagdir Directory where the tag checkout is placed (*if* a tag checkout has been made) version Version we're releasing workingdir Original working directory Postrelease data dict items --------------------------- commit_msg Message template used when committing dev_version New development version with dev marker (so 1.1.dev0) dev_version_template Template for dev version number history_header Header template used for 1st history header name Name of the project being released new_version New development version (so 1.1) nothing_changed_yet First line in new changelog section workingdir Original working directory