API Changes

Notable changes in Mercurial's API.

1. How to keep your extension compatible

• Subscribe to this page to keep up-to-date on changes

• Mark your calendar to test your extension before our scheduled releases (Feb 1, May 1, Aug 1, Nov 1)

• Use introspection in helper functions to choose which interface to call, for example:

def updatedir(*args, **kwargs):
    if hasattr(patch, 'updatedir'):
        patch.updatedir(*args, **kwargs)
    else:
        cmdutil.updatedir(*args, **kwargs)

• Use inspect.getargspec() to deal with changing argument lists

2. Changes in 4.8rc0

• externalize() and externalizeall() removed from dagutil
  • Use .node() on a storage primitive to perform revision to node conversions.
• removed internalize() and internalizeall() from dagutil
  • Use .rev(node) on storage objects to convert nodes to revisions.
• descendantset() and ancestorset() removed from dagutil
  • Use a revset instead when operating on the changelog. Or use various functionality in the ancestor or dagop modules.
• remove inverse() methods from classes in dagutil
• parents() removed from dagutil classes
  • Use parentrevs() on the storage object instead.
• dagutil module has been removed
  • Some functionality has been moved to the dagop module. Other functionality can be accomplished via revsets.
• storedeltachains has been dropped from ifilestorage interface
• storedeltachains on revlog classes is now _storedeltachains

• renamed manifest.manifestrevlog.__init__ dir argument to tree

• manifestlog now has a getstorage(tree) method
  • It should be used for obtaining an object representing the manifest's storage implementation. Accessing manifestlog._revlog should be avoided.
• cmdutil.openrevlog() now returns a revlog instance or aborts
  • Previously, it would return a storage object, which may not be a revlog instance.
  • Use the new cmdutil.openstorage() API to return an object conforming to the storage interface of the thing you are accessing if you don't need a revlog instance.
• manifest.manifestrevlog no longer inherits from revlog
  • The manifestrevlog class now wraps a revlog instance instead of inheriting from revlog. Various attributes and methods on instances are no longer available.
• local repo creation moved out of constructor

  • localrepo.localrepository.__init__ no longer accepts a "create" argument to create a new repository. New repository creation is now performed as part of "localrepo.instance()" and the bulk of the work is performed by "localrepo.createrepository()".

• options can now be passed to influence repository creation
  • The various instance() functions to spawn new peers or repository instances now receive a "createopts" argument that can be a dict defining additional options to influence repository creation.
  • localrepo.newreporequirements() also receives this argument.

3. Changes in 3.9

• annotate: context.annotate will no longer return (ctx, line) for linenumber=None - it will always return ((ctx, linenumber), line)

• error: make HintException a mix-in class not derived from BaseException (API)

• error: make hintable exceptions reject unknown keyword arguments (API)
• localrepo: jettison parents() method per deprecation policy (API)
• sslutil: convert socket validation from a class to a function (API)
• sslutil: move sslkwargs logic into internal function (API)
• sslutil: remove sslkwargs() (API)
• sslutil: remove ui from sslkwargs (API)
• sslutil: require serverhostname argument (API)
• transaction: turn lack of locking into a hard failure (API)

4. Changes in 3.8

• bundle: move writebundle() from changegroup.py to bundle2.py (API)
• changelog: lazy decode description (API)
• changelog: lazy decode user (API)
• commands: add postincoming explicit brev argument (API)
• dispatch: store norepo/optionalrepo/inferrepo attributes in function (API)
• fileset: replace predicate by filesetpredicate of registrar (API)
• localrepo: move new repo requirements into standalone function (API)
• match: rename "narrowmatcher" to "subdirmatcher" (API)
• registrar: add templatefilter to mark a function as template filter (API)
• registrar: add templatefunc to mark a function as template function (API)
• registrar: add templatekeyword to mark a function as template keyword (API)
• registrar: remove useless base classes (API)

• remove: queue warnings until after status messages (issue5140) (API)

• revset: remove useless extpredicate class (API)
• sslutil: require a server hostname when wrapping sockets (API)

• templater: load and expand aliases by template engine (API) (issue4842)

• templater: separate function to create templater from map file (API)

• ui: add prompt argument to write (issue5154) (API)

5. Changes in 3.7

• commands: inline definition of localrepo.parents() and drop the method (API)
• fileset: use set instead of list to mark predicates for efficiency (API)
• merge: move almost all change/delete conflicts to resolve phase (BC) (API)
• status: change + back out == clean (API)

6. Changes in 3.6

• help: pass around ui to doc loader (API)
• help: pass around ui to rewriter hooks (API)
• revrange: drop old-style parser in favor of revset (API)

7. Changes in 3.2

• localrepo.push method have been removed in favor of the exchange.push function. It returns a pushoperation object. the former returned value is stored in the pushop.cgresult attribute.

• localrepo.pull method have been removed in favor of the exchange.pull function. It returns a pulloperation object. the former returned value is stored in the pullop.cgresult attribute.

•  memfilectx.__init__() takes an extra repo as first parameter (after self) (503bb3af70fe)

• dirstate: add exception when calling setparent without begin/end (API)

8. Changes in 3.1

•  memfilectx.__init__() takes an extra repo as first parameter (after self) (503bb3af70fe)

9. Changes after 2.8

• repo._branchtags() is no more, maybe use repo.branchmap() (4274eda143cb)

• ui.promptchoice no longer takes a separate choices argument; choices are now parsed out of the string (c58b6ab4c26f)

10. Changes after 2.4

• Writing bookmarks should now use repo._bookmarks.write() instead of bookmarks.write(repo) (7f5dab94e48c)

11. Changes after 2.3

• The 'opener' classes and class members have been renamed 'vfs' and acquired new methods in preparation for improving Unicode handling on Windows

• The 'filectx.ancestor' method now requires the ancestor changeset context to be passed in (4b73f4ba27ca)

12. Changes after 2.2

• peer: introduce real peer classes (API) (1ac628cd7113); as a result, the mercurial.repo module is gone, as well as the repository base class

• revlog: ancestors(*revs) becomes ancestors(revs) (API)
• revlog: descendants(*revs) becomes descendants(revs) (API)

• phases.visibleheads and phases.visiblebranchmap were moved to discovery (97eff00046de)

13. Changes between 1.9 and 2.2

?

14. Changes after 1.9

• util.atomictempfile.close semantics were changed, util.atomictempfile.rename was removed (774da7121fc9)

15. Changes after 1.8

• dispatch.dispatch now requires a request argument (08bfec2ef031)

• cmdutil.logmessage now requires a ui argument (217b7d83afc3)

• scmutil.match (formerly cmdutil.match) now requires a context argument (35c2cc322ba8), typically "repo[None]"

• Various functions have been moved from cmdutil.py to scmutil.py, including revrange/revsingle/revpair and match/matchall/matchfiles

• revset.match now requires two arguments (9f5a0acb0056)

• util.opener, canonpath, path_auditor, walkrepos, rcpath, os_rcpath, system_rcpath and user_rcpath were moved to scmutil (d1f4e7fd970a, 938fbeacac84, 9c374cf76b7d).

• patch.iterhunks now takes a single fp argument, ui is no longer passed (28762bb767dc).

• patch.iterhunks emits a gitpatch object when available in file event (d0c2cc11e611).

• cmdutil.updatedir has been removed, patch.patch and patch.internalpatch now perform a similar functionality through backend objects (17cea10c343e)

• patch.patch no longer takes a cwd argument, it always operates on the repository root directory (2d16f15da7bd)

• patch.patch and patch.internalpatch files argument is now a set, not a dict (65f4512e40e4)

• hg.clone takes an additional positional dictionary argument for peer options (d976542986d2)

16. Changes after 1.7

• Previous util.unlink was renamed to unlinkpath (6bf39d88c857) and was reimplemented to only delete the file, not removing directories any more (6052bbc7aabd).

17. Changes after 1.6

• patch.updatedir was moved to cmdutil.updatedir to break an import cycle (00658492e2aa)

• store.auxencode and store.hybridencode were renamed to _auxencode and _hybridencode and got an additional parameter (34d8247a4595)

18. Changes after 1.5

• patch.export moved to cmdutil.export (e764f24a45ee)

• cmdutil.findrenames moved to similar.findrenames (ef4aa90b1e58)

• transactions now need to be released at the end of the function that acquired them via tr.release (5116a077c3da)

• changeset discovery functions (findincoming, findcommonincoming, findoutgoing, prepush) moved from localrepo to new discovery module (3d0591a66118)

• working dir manipulation methods (add, forget, remove, undelete, copy) moved from localrepo to workingctx (a1aad8333864)

• move cmdutil.remoteui to hg.remoteui (d1908cb95a82)

• ui.write and friends now take **opts and accept the label keyword argument (32b213b9b22c)

• color makes use of ui labels to provide colorization. extensions can provide a colortable dict mapping labels to colors (717c35d55fb3)

• ui.plain function is added, which returns True if the HGPLAIN environment var is set. HGPLAIN disables output-changing settings for script stability (40dfd46d098f)

• ui.formatted is added as an output-related analogue to ui.interactive (cdf6d861b207)

• localrepo.rollback now accepts an optional dryrun argument. Users subclassing repo should add *args to their rollback method. (f0bfe42c7b1f)

• bookmarks.parse is now part of the repo._bookmarks property definition (be041d6714ed)

19. Changes after 1.4

• hg.parseurl no longer returns a tuple of 3 items (see d757bc0c7865 for complete details)

• localrepo.commitctx now checks the errno of raised IOError instances if they are present, and will re-raise if the errno is not ENOENT. See e553a425751d for details.

20. Changes after 1.3

• ui.prompt is now a simple prompt and does not accept a list of choices. Use ui.promptchoice instead.

• The change argument passed to cmdutil.walkchangerevs() should now return a changectx instead of the underlying data.

• As mentioned for 1.3, the #var# templater syntax has been removed in favor of the {var} syntax.

21. Changes from 1.2 to 1.3

• we've dropped Python 2.3 compatibility

• the #var# templater syntax is now deprecated in favor of the {var} syntax. The old syntax will be removed in the 1.4 release. A tmplrewrite.py script is provided in contrib to help you convert your templates.

• util.set is now just set

• util.sort is replaced by the sorted built-in

• util.Popen3 is gone, use subprocess instead

• util.md5 is gone, use util.sha1 to get a secure hash function or keepalive.md5 if you really must use MD5

• util._encoding is now encoding.encoding

• util.isowner now takes a mandatory stat object instead of a file path (use util.fstat to stat a path first)

• platform specific parts of util have been split out into posix and windows modules, which are imported as necessary by util

• the ui object constructor has been simplified:

    # before
    ui = ui.ui(parentui=parentui, interactive=False)

    # after
    ui = baseui.copy() # there's no longer a parent/child concept
    ui.setconfig('ui', 'interactive', 'off')

• Some methods relating to configuration have been removed from the ui object.

• util.configparser replaced by config.config

• __getattr__ caching tricks replaced by @util.propertycache tricks

• cmdutil.setremoteopts(ui, opts) is now cmdutil.remoteui([repo|ui], opts)

• ui.interactive is now a method

• ui.readsections() is now ui.readconfig(sections=[])

• ui.print_exc is renamed ui.traceback

• must explicitly call lock.release

• encoding functions moved to new encoding module

• the rawcommit code paths have been removed; this includes localrepo.rawcommit and the debugrawcommit command

• localrepo.filecommit is no longer part of the (public) API

• the commit API around invoking the editor has changed (also, you can no longer pass a list of files; pass a matcher instead)
• the templater API now takes a context object instead of a node
• a branchmap command has been added to the wire protocol

22. Changes from 1.1 to 1.2

• Most exceptions are now defined in error.py and some exception names have changed
• Version info is now retrieved with util.version(), version.py is removed

23. Changes from 1.0 to 1.1

• repo.count, changelog.count, and revlog.count replaced with len built-in

• introduction of repo[identifier] and revlog[identifier]

• replace all users of util.matcher with match objects

• changed cmdutil.walk to repo.walk:

    # before
    for src, abs, rel, exact in cmdutil.walk(repo, pats, opts,
                                             node=ctx.node()):

    # after

    m = cmdutil.match(repo, pats, opts)
    for abs in ctx.walk(m):
        rel = m.rel()

• changed defaults for localrepo.status:

    # before
    def status(self, node1=None, node2=None, files=[], match=util.always,
               list_ignored=False, list_clean=False, list_unknown=True):

    # after
    def status(self, node1='.', node2=None, match=None,
               ignored=False, clean=False, unknown=False):

• patch.diff no longer accepts an fp argument, it yields data instead

• len(changectx.parents()) may now be of length 1 (but never length 0)

• revlog.linkrev now takes a numerical rev argument rather than a node:

    # before
    a = manifest.linkrev(node)
    b = manifest.linkrev(manifest.node(rev))

    # after
    a = manifest.linkrev(manifest.rev(node))
    b = manifest.linkrev(rev)

• cset_printer and cset_templater now take a changectx instead of rev or node:

    # before
    displayer = cmdutil.show_changeset(ui, repo, opts)
    displayer.show(rev, node)

    # after
    displayer = cmdutil.show_changeset(ui, repo, opts)
    displayer.show(repo[rev])

• patch.patchfile now expects a fifth argument, opener

• patch.applydiff's argument changes constructs a new dict:

    # before
    keep = { }
    patch.applydiff(..., keep, ...)

    print keep
    { 'fname': ( action, other ) }

    # after
    keep = { }
    patch.applydiff(..., keep, ...)

    print keep
    { 'fname': action }

as before, action will only be set to anything not-None if the patch is in git-format.

• hgweb and hgwebdir now return an iterator over bytes rather than writing to the write callable provided by the WSGI server.

23.1. Template changes in 1.0

If you use your own template set (particularly for hgweb), here are some relevant changes.

• Before 1.0, Content-Type was set as a line in header.tmpl. It was changed in 1.0 to use a "mimetype" value from the map. In 1.1, the old behavior has been removed.
• Annotate templates now get a full user instead of the short version. Use "author|user" to revert to the previous behavior.
• Annotate lines now also have the "desc" variable, in order to show the commit message for that line's changeset.
• Parent and child links (in changeset and diff pages, for example) can now show much more information about those changesets.
• Branch name and branch head information is available in many more places.

24. See also

• WhatsNew

• UpgradeNotes

• Our time-based release plan

CategoryInternals