( )⚙ D10295 exthelper: improve docs to indicate what module vars are needed

This is an archive of the discontinued Mercurial Phabricator instance.

Differential D10295

exthelper: improve docs to indicate what module vars are needed
ClosedPublic

Authored by spectral on Apr 1 2021, 3:24 PM.

Details

Reviewers
Alphare
pulkit
Group Reviewers
hg-reviewers
Commits
rHG887f89b100ac: exthelper: improve docs to indicate what module vars are needed
Summary

I recently tried creating an extension "from scratch" using exthelper, and it
wasn't obvious that you needed these. I believe that a careful reading of one of
the comments would tell you that they were required, but it's easy to miss and
having the examples be "complete" is helpful.

Diff Detail

Repository
rHG Mercurial
Branch
default
Lint
No Linters Available
Unit
No Unit Test Coverage

Event Timeline

spectral created this revision.Apr 1 2021, 3:24 PM
Alphare accepted this revision.Apr 8 2021, 6:21 AM
Alphare added a subscriber: Alphare.

Thanks! This had bit me in the past, and I probably forgot about it.

pulkit accepted this revision.Apr 8 2021, 12:51 PM
This revision is now accepted and ready to land.Apr 8 2021, 12:51 PM

Revision Contents
Changeset List

PathPackages
Mmercurial/exthelper.py (37 lines)

Diff 26641

mercurial/exthelper.py

variable to a module level variable of the extension. The variable to a module level variable of the extension. The
extension loading mechanism will handle the rest. extension loading mechanism will handle the rest.
example:: example::
# ext.py # ext.py
eh = exthelper.exthelper() eh = exthelper.exthelper()
# As needed: # As needed (failure to do this will mean your registration will not
# happen):
cmdtable = eh.cmdtable cmdtable = eh.cmdtable
configtable = eh.configtable configtable = eh.configtable
filesetpredicate = eh.filesetpredicate filesetpredicate = eh.filesetpredicate
revsetpredicate = eh.revsetpredicate revsetpredicate = eh.revsetpredicate
templatekeyword = eh.templatekeyword templatekeyword = eh.templatekeyword
# As needed (failure to do this will mean your eh.wrap*-decorated
# functions will not wrap, and/or your eh.*setup-decorated functions
# will not execute):
uisetup = eh.finaluisetup
extsetup = eh.finalextsetup
reposetup = eh.finalreposetup
uipopulate = eh.finaluipopulate
@eh.command(b'mynewcommand', @eh.command(b'mynewcommand',
[(b'r', b'rev', [], _(b'operate on these revisions'))], [(b'r', b'rev', [], _(b'operate on these revisions'))],
_(b'-r REV...'), _(b'-r REV...'),
helpcategory=command.CATEGORY_XXX) helpcategory=command.CATEGORY_XXX)
def newcommand(ui, repo, *revs, **opts): def newcommand(ui, repo, *revs, **opts):
# implementation goes here # implementation goes here
eh.configitem(b'experimental', b'foo', eh.configitem(b'experimental', b'foo',
- Set up additional ui members - Set up additional ui members
- Update configuration by ``ui.setconfig()`` - Update configuration by ``ui.setconfig()``
- Extend the class dynamically - Extend the class dynamically
""" """
for c in self._uipopulatecallables: for c in self._uipopulatecallables:
c(ui) c(ui)
def finalextsetup(self, ui): def finalextsetup(self, ui):
"""Method to be used as a the extension extsetup """Method to be used as the extension extsetup
The following operations belong here: The following operations belong here:
- Changes depending on the status of other extensions. (if - Changes depending on the status of other extensions. (if
extensions.find(b'mq')) extensions.find(b'mq'))
- Add a global option to all commands - Add a global option to all commands
""" """
knownexts = {} knownexts = {}
with tracing.log('finalreposetup: %s', repr(c)): with tracing.log('finalreposetup: %s', repr(c)):
c(ui, repo) c(ui, repo)
def uisetup(self, call): def uisetup(self, call):
"""Decorated function will be executed during uisetup """Decorated function will be executed during uisetup
example:: example::
# Required, otherwise your uisetup function(s) will not execute.
uisetup = eh.finaluisetup
@eh.uisetup @eh.uisetup
def setupbabar(ui): def setupbabar(ui):
print('this is uisetup!') print('this is uisetup!')
""" """
self._uicallables.append(call) self._uicallables.append(call)
return call return call
def uipopulate(self, call): def uipopulate(self, call):
"""Decorated function will be executed during uipopulate """Decorated function will be executed during uipopulate
example:: example::
# Required, otherwise your uipopulate function(s) will not execute.
uipopulate = eh.finaluipopulate
@eh.uipopulate @eh.uipopulate
def setupfoo(ui): def setupfoo(ui):
print('this is uipopulate!') print('this is uipopulate!')
""" """
self._uipopulatecallables.append(call) self._uipopulatecallables.append(call)
return call return call
def extsetup(self, call): def extsetup(self, call):
"""Decorated function will be executed during extsetup """Decorated function will be executed during extsetup
example:: example::
# Required, otherwise your extsetup function(s) will not execute.
extsetup = eh.finalextsetup
@eh.extsetup @eh.extsetup
def setupcelestine(ui): def setupcelestine(ui):
print('this is extsetup!') print('this is extsetup!')
""" """
self._extcallables.append(call) self._extcallables.append(call)
return call return call
def reposetup(self, call): def reposetup(self, call):
"""Decorated function will be executed during reposetup """Decorated function will be executed during reposetup
example:: example::
# Required, otherwise your reposetup function(s) will not execute.
reposetup = eh.finalreposetup
@eh.reposetup @eh.reposetup
def setupzephir(ui, repo): def setupzephir(ui, repo):
print('this is reposetup!') print('this is reposetup!')
""" """
self._repocallables.append(call) self._repocallables.append(call)
return call return call
def wrapcommand(self, command, extension=None, opts=None): def wrapcommand(self, command, extension=None, opts=None):
"""Decorated function is a command wrapper """Decorated function is a command wrapper
The name of the command must be given as the decorator argument. The name of the command must be given as the decorator argument.
The wrapping is installed during `uisetup`. The wrapping is installed during `uisetup`.
If the second option `extension` argument is provided, the wrapping If the second option `extension` argument is provided, the wrapping
will be applied in the extension commandtable. This argument must be a will be applied in the extension commandtable. This argument must be a
string that will be searched using `extension.find` if not found and string that will be searched using `extension.find` if not found and
Abort error is raised. If the wrapping applies to an extension, it is Abort error is raised. If the wrapping applies to an extension, it is
installed during `extsetup`. installed during `extsetup`.
example:: example::
# Required if `extension` is not provided
uisetup = eh.finaluisetup
# Required if `extension` is provided
extsetup = eh.finalextsetup
@eh.wrapcommand(b'summary') @eh.wrapcommand(b'summary')
def wrapsummary(orig, ui, repo, *args, **kwargs): def wrapsummary(orig, ui, repo, *args, **kwargs):
ui.note(b'Barry!') ui.note(b'Barry!')
return orig(ui, repo, *args, **kwargs) return orig(ui, repo, *args, **kwargs)
The `opts` argument allows specifying a list of tuples for additional The `opts` argument allows specifying a list of tuples for additional
arguments for the command. See ``mercurial.fancyopts.fancyopts()`` for arguments for the command. See ``mercurial.fancyopts.fancyopts()`` for
the format of the tuple. the format of the tuple.
"""Decorated function is a function wrapper """Decorated function is a function wrapper
This function takes two arguments, the container and the name of the This function takes two arguments, the container and the name of the
function to wrap. The wrapping is performed during `uisetup`. function to wrap. The wrapping is performed during `uisetup`.
(there is no extension support) (there is no extension support)
example:: example::
@eh.function(discovery, b'checkheads') # Required, otherwise the function will not be wrapped
def wrapfunction(orig, *args, **kwargs): uisetup = eh.finaluisetup
@eh.wrapfunction(discovery, b'checkheads')
def wrapcheckheads(orig, *args, **kwargs):
ui.note(b'His head smashed in and his heart cut out') ui.note(b'His head smashed in and his heart cut out')
return orig(*args, **kwargs) return orig(*args, **kwargs)
""" """
def dec(wrapper): def dec(wrapper):
self._functionwrappers.append((container, funcname, wrapper)) self._functionwrappers.append((container, funcname, wrapper))
return wrapper return wrapper
return dec return dec