Diff for "ApiChanges"

Why you shouldn't use Mercurial's internal API

Mercurial's internals are continually evolving to be simpler, more consistent, and more powerful, a process we hope will continue for the foreseeable future. Unfortunately, this process means we will regularly be changing interfaces in ways that break third-party code in various (mostly minor) ways.

For the vast majority of third party code, the best approach is to use Mercurial's published, documented, and stable API: the command line interface.

There are NO guarantees that third-party code calling into Mercurial's internals won't break from release to release.

Use of Mercurial's internal API very likely makes your code subject to Mercurial's license. Before going any further, read the License page.

If you do use Mercurial's API for published third-party code, we expect you to test your code before each major Mercurial release (see TimeBasedReleasePlan). This will prevent various bug reports from your users when they upgrade their copy of Mercurial.

Changes after 1.6

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

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() 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)

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.

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.

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

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

Changes from 1.0 to 1.1

• repo.count(), changelog.count(), and revlog.count() replaced with len() method
• 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.

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.