This is an archive of the discontinued Mercurial Phabricator instance.

Differential D9367

helptext: byteify extensions examples
ClosedPublic

Authored by mharbison72 on Nov 22 2020, 3:08 PM.

Details

Reviewers
Alphare
pulkit
Group Reviewers
hg-reviewers
Commits
rHGf177fcd9cb96: helptext: byteify extensions examples
Summary

Make it easier on the copy/paste crowd. I haven't looked at the other help text
to see if there are other instances; I was just looking to confirm buglink is
meant to be bytes and this popped up along with the code.

Diff Detail

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

Event Timeline

mharbison72 created this revision.Nov 22 2020, 3:08 PM
Alphare accepted this revision.Nov 23 2020, 10:58 AM
Alphare added a subscriber: Alphare.

This is nice for extensions writers indeed. Although I hope one day we might roll back to using strings for command names and help texts, this is fine for the near future.

pulkit accepted this revision.Nov 26 2020, 7:44 AM
This revision is now accepted and ready to land.Nov 26 2020, 7:44 AM
mharbison72 added a commit: rHGf177fcd9cb96: helptext: byteify extensions examples.Nov 26 2020, 8:15 AM
Closed by commit rHGf177fcd9cb96: helptext: byteify extensions examples (authored by mharbison72). · Explain Why
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

Diff 23624

mercurial/helptext/internals/extensions.txt

extension). The package root module gives its name to the extension and extension). The package root module gives its name to the extension and
implements the ``cmdtable`` and optional callbacks described below. implements the ``cmdtable`` and optional callbacks described below.
Command table Command table
============= =============
To write your own extension, your python module can provide an optional dict To write your own extension, your python module can provide an optional dict
named ``cmdtable`` with entries describing each command. A command should be named ``cmdtable`` with entries describing each command. A command should be
registered to the ``cmdtable`` by ``@command`` decorator. registered to the ``cmdtable`` by ``@command`` decorator. All string-like
values must be the ``bytes`` type, and are thus prefixed with ``b``.
Example using ``@command`` decorator (requires Mercurial 1.9):: Example using ``@command`` decorator (requires Mercurial 1.9)::
from mercurial.i18n import _ from mercurial.i18n import _
cmdtable = {} cmdtable = {}
try: try:
from mercurial import registrar from mercurial import registrar
command = registrar.command(cmdtable) command = registrar.command(cmdtable)
except (AttributeError, ImportError): except (AttributeError, ImportError):
# Fallback to hg < 4.3 support # Fallback to hg < 4.3 support
from mercurial import cmdutil from mercurial import cmdutil
command = cmdutil.command(cmdtable) command = cmdutil.command(cmdtable)
@command('print-parents', @command(b'print-parents',
[('s', 'short', None, _('print short form')), [(b's', b'short', None, _(b'print short form')),
('l', 'long', None, _('print long form'))], (b'l', b'long', None, _(b'print long form'))],
_('[options] node')) _(b'[options] node'))
def printparents(ui, repo, node, **opts): def printparents(ui, repo, node, **opts):
... ...
The cmdtable dictionary The cmdtable dictionary
----------------------- -----------------------
The ``cmdtable`` dictionary uses as key the new command names, and, as value, The ``cmdtable`` dictionary uses as key the new command names, and, as value,
a tuple containing: a tuple containing:
a ``repo`` parameter. The rest of parameters are taken from the command line a ``repo`` parameter. The rest of parameters are taken from the command line
items that don't start with a dash and are passed in the same order they were items that don't start with a dash and are passed in the same order they were
written. If no default value is given in the parameter list they are required. written. If no default value is given in the parameter list they are required.
If there is no repo to be associated with the command and consequently no If there is no repo to be associated with the command and consequently no
``repo`` passed, then ``norepo=True`` should be passed to the ``@command`` ``repo`` passed, then ``norepo=True`` should be passed to the ``@command``
decorator:: decorator::
@command('mycommand', [], norepo=True) @command(b'mycommand', [], norepo=True)
def mycommand(ui, **opts): def mycommand(ui, **opts):
... ...
For examples of ``norepo``, see the convert extension. For examples of ``norepo``, see the convert extension.
Command function docstrings Command function docstrings
=========================== ===========================
Mark Mercurial commands with ``:hg:`` to make a nice link to the corresponding Mark Mercurial commands with ``:hg:`` to make a nice link to the corresponding
documentation. We'll expand the support if new constructs can be parsed documentation. We'll expand the support if new constructs can be parsed
without too much trouble. without too much trouble.
Communicating with the user Communicating with the user
=========================== ===========================
Besides the ``ui`` methods, like ``ui.write(*msg)`` or Besides the ``ui`` methods, like ``ui.write(*msg)`` or
``ui.prompt(msg, default="y")``, an extension can add help text for each ``ui.prompt(msg, default=b"y")``, an extension can add help text for each
of its commands and the extension itself. of its commands and the extension itself.
The module docstring will be used as help string when ``hg help extensionname`` The module docstring will be used as help string when ``hg help extensionname``
is used and, similarly, the help string for a command and the docstring is used and, similarly, the help string for a command and the docstring
belonging to the function that's wrapped by the command will be shown when belonging to the function that's wrapped by the command will be shown when
``hg help command`` is invoked. ``hg help command`` is invoked.
Setup Callbacks Setup Callbacks
extension is enabled (or copies thereof, reusing your new class). extension is enabled (or copies thereof, reusing your new class).
For example:: For example::
def uisetup(ui): def uisetup(ui):
class echologui(ui.__class__): class echologui(ui.__class__):
def log(self, service, *msg, **opts): def log(self, service, *msg, **opts):
if msg: if msg:
self.write('%s: %s\n' % (service, msg[0] % msg[1:])) self.write(b'%s: %s\n' % (service, msg[0] % msg[1:]))
super(echologui, self).log(service, *msg, **opts) super(echologui, self).log(service, *msg, **opts)
ui.__class__ = echologui ui.__class__ = echologui
Configuring Hooks Configuring Hooks
================= =================
Some extensions must use hooks to do their work. These required hooks can Some extensions must use hooks to do their work. These required hooks can
be configured manually by the user by modifying the ``[hook]`` section of be configured manually by the user by modifying the ``[hook]`` section of
their hgrc, but they can also be configured automatically by calling the their hgrc, but they can also be configured automatically by calling the
``ui.setconfig('hooks', ...)`` function in one of the setup functions ``ui.setconfig(b'hooks', ...)`` function in one of the setup functions
described above. described above.
The main difference between manually modifying the hooks section in the hgrc The main difference between manually modifying the hooks section in the hgrc
and using ``ui.setconfig()`` is that when using ``ui.setconfig()`` you have and using ``ui.setconfig()`` is that when using ``ui.setconfig()`` you have
access to the actual hook function object, which you can pass directly to access to the actual hook function object, which you can pass directly to
``ui.setconfig()``, while when you use the hooks section of the hgrc file ``ui.setconfig()``, while when you use the hooks section of the hgrc file
you must refer to the hook function by using the you must refer to the hook function by using the
``python:modulename.functioname`` idiom (e.g. ``python:hgext.notify.hook``). ``python:modulename.functioname`` idiom (e.g. ``python:hgext.notify.hook``).
For example:: For example::
# Define hooks -- note that the actual function name it irrelevant. # Define hooks -- note that the actual function name it irrelevant.
def preupdatehook(ui, repo, **kwargs): def preupdatehook(ui, repo, **kwargs):
ui.write("Pre-update hook triggered\n") ui.write(b"Pre-update hook triggered\n")
def updatehook(ui, repo, **kwargs): def updatehook(ui, repo, **kwargs):
ui.write("Update hook triggered\n") ui.write(b"Update hook triggered\n")
def uisetup(ui): def uisetup(ui):
# When pre-<cmd> and post-<cmd> hooks are configured by means of # When pre-<cmd> and post-<cmd> hooks are configured by means of
# the ui.setconfig() function, you must use the ui object passed # the ui.setconfig() function, you must use the ui object passed
# to uisetup or extsetup. # to uisetup or extsetup.
ui.setconfig("hooks", "pre-update.myextension", preupdatehook) ui.setconfig(b"hooks", b"pre-update.myextension", preupdatehook)
def reposetup(ui, repo): def reposetup(ui, repo):
# Repository-specific hooks can be configured here. These include # Repository-specific hooks can be configured here. These include
# the update hook. # the update hook.
ui.setconfig("hooks", "update.myextension", updatehook) ui.setconfig(b"hooks", b"update.myextension", updatehook)
Note how different hooks may need to be configured in different setup Note how different hooks may need to be configured in different setup
functions. In the example you can see that the ``update`` hook must be functions. In the example you can see that the ``update`` hook must be
configured in the ``reposetup`` function, while the ``pre-update`` hook configured in the ``reposetup`` function, while the ``pre-update`` hook
must be configured on the ``uisetup`` or the ``extsetup`` functions. must be configured on the ``uisetup`` or the ``extsetup`` functions.
Marking compatible versions Marking compatible versions
=========================== ===========================
Every extension should use the ``testedwith`` variable to specify Mercurial Every extension should use the ``testedwith`` variable to specify Mercurial
releases it's known to be compatible with. This helps us and users diagnose releases it's known to be compatible with. This helps us and users diagnose
where problems are coming from:: where problems are coming from::
testedwith = '2.0 2.0.1 2.1 2.1.1 2.1.2' testedwith = b'2.0 2.0.1 2.1 2.1.1 2.1.2'
Do not use the ``internal`` marker in third-party extensions; we will Do not use the ``internal`` marker in third-party extensions; we will
immediately drop all bug reports mentioning your extension if we catch you immediately drop all bug reports mentioning your extension if we catch you
doing this. doing this.
Similarly, an extension can use the ``buglink`` variable to specify how users Similarly, an extension can use the ``buglink`` variable to specify how users
should report issues with the extension. This link will be included in the should report issues with the extension. This link will be included in the
error message if the extension produces errors:: error message if the extension produces errors::
buglink = 'https://bitbucket.org/USER/REPO/issues' buglink = b'https://bitbucket.org/USER/REPO/issues'
If an extension requires a minimum version of Mercurial, it can be declared If an extension requires a minimum version of Mercurial, it can be declared
with the ``minimumhgversion`` variable:: with the ``minimumhgversion`` variable::
minimumhgversion = '4.6' minimumhgversion = b'4.6'
Older clients will print a warning that the extension requires a new version, Older clients will print a warning that the extension requires a new version,
instead of attempting to load it. instead of attempting to load it.
Wrap up: what belongs where? Wrap up: what belongs where?
============================ ============================
You will find here a list of most common tasks, based on setups from the You will find here a list of most common tasks, based on setups from the
module members module members
* Set up ``pre-*`` and ``post-*`` hooks. (DEPRECATED. ``uipopulate`` is * Set up ``pre-*`` and ``post-*`` hooks. (DEPRECATED. ``uipopulate`` is
preferred on Mercurial 4.9 and later.) preferred on Mercurial 4.9 and later.)
* ``pushkey`` setup * ``pushkey`` setup
extsetup extsetup
-------- --------
* Changes depending on the status of other extensions. (``if extensions.find('mq')``) * Changes depending on the status of other extensions. (``if extensions.find(b'mq')``)
* Add a global option to all commands * Add a global option to all commands
* Extend revsets * Extend revsets
uipopulate uipopulate
---------- ----------
* Modify ``ui`` instance attributes and configuration variables. * Modify ``ui`` instance attributes and configuration variables.
* Changes to ``ui.__class__`` per instance. * Changes to ``ui.__class__`` per instance.