registrar.py
491 lines
| 17.1 KiB
| text/x-python
|
PythonLexer
/ mercurial / registrar.py
|
r27583 | # registrar.py - utilities to register function for specific purpose | ||
# | ||||
# Copyright FUJIWARA Katsunori <foozy@lares.dti.ne.jp> and others | ||||
# | ||||
# This software may be used and distributed according to the terms of the | ||||
# GNU General Public License version 2 or any later version. | ||||
from __future__ import absolute_import | ||||
from . import ( | ||||
r33127 | configitems, | |||
|
r30608 | error, | ||
|
r30059 | pycompat, | ||
|
r27583 | util, | ||
) | ||||
r33127 | # unlike the other registered items, config options are neither functions or | |||
# classes. Registering the option is just small function call. | ||||
# | ||||
# We still add the official API to the registrar module for consistency with | ||||
# the other items extensions want might to register. | ||||
configitem = configitems.getitemregister | ||||
|
r28392 | class _funcregistrarbase(object): | ||
|
r30332 | """Base of decorator to register a function for specific purpose | ||
|
r28392 | |||
This decorator stores decorated functions into own dict 'table'. | ||||
The least derived class can be defined by overriding 'formatdoc', | ||||
for example:: | ||||
class keyword(_funcregistrarbase): | ||||
_docformat = ":%s: %s" | ||||
This should be used as below: | ||||
keyword = registrar.keyword() | ||||
@keyword('bar') | ||||
def barfunc(*args, **kwargs): | ||||
'''Explanation of bar keyword .... | ||||
''' | ||||
pass | ||||
In this case: | ||||
- 'barfunc' is stored as 'bar' in '_table' of an instance 'keyword' above | ||||
- 'barfunc.__doc__' becomes ":bar: Explanation of bar keyword" | ||||
""" | ||||
def __init__(self, table=None): | ||||
if table is None: | ||||
self._table = {} | ||||
else: | ||||
self._table = table | ||||
def __call__(self, decl, *args, **kwargs): | ||||
return lambda func: self._doregister(func, decl, *args, **kwargs) | ||||
def _doregister(self, func, decl, *args, **kwargs): | ||||
name = self._getname(decl) | ||||
|
r30608 | if name in self._table: | ||
msg = 'duplicate registration for name: "%s"' % name | ||||
raise error.ProgrammingError(msg) | ||||
|
r28392 | if func.__doc__ and not util.safehasattr(func, '_origdoc'): | ||
|
r31820 | doc = pycompat.sysbytes(func.__doc__).strip() | ||
|
r28392 | func._origdoc = doc | ||
|
r31820 | func.__doc__ = pycompat.sysstr(self._formatdoc(decl, doc)) | ||
|
r28392 | |||
self._table[name] = func | ||||
self._extrasetup(name, func, *args, **kwargs) | ||||
return func | ||||
def _parsefuncdecl(self, decl): | ||||
"""Parse function declaration and return the name of function in it | ||||
""" | ||||
i = decl.find('(') | ||||
if i >= 0: | ||||
return decl[:i] | ||||
else: | ||||
return decl | ||||
def _getname(self, decl): | ||||
"""Return the name of the registered function from decl | ||||
Derived class should override this, if it allows more | ||||
descriptive 'decl' string than just a name. | ||||
""" | ||||
return decl | ||||
_docformat = None | ||||
def _formatdoc(self, decl, doc): | ||||
"""Return formatted document of the registered function for help | ||||
'doc' is '__doc__.strip()' of the registered function. | ||||
""" | ||||
return self._docformat % (decl, doc) | ||||
def _extrasetup(self, name, func): | ||||
"""Execute exra setup for registered function, if needed | ||||
""" | ||||
|
r28393 | |||
|
r32338 | class command(_funcregistrarbase): | ||
"""Decorator to register a command function to table | ||||
|
r32337 | |||
|
r32338 | This class receives a command table as its argument. The table should | ||
|
r32337 | be a dict. | ||
|
r32338 | The created object can be used as a decorator for adding commands to | ||
that command table. This accepts multiple arguments to define a command. | ||||
|
r32337 | |||
|
r35106 | The first argument is the command name (as bytes). | ||
|
r32337 | |||
|
r35106 | The `options` keyword argument is an iterable of tuples defining command | ||
arguments. See ``mercurial.fancyopts.fancyopts()`` for the format of each | ||||
tuple. | ||||
|
r32337 | |||
|
r35106 | The `synopsis` argument defines a short, one line summary of how to use the | ||
|
r32337 | command. This shows up in the help output. | ||
|
r35106 | There are three arguments that control what repository (if any) is found | ||
and passed to the decorated function: `norepo`, `optionalrepo`, and | ||||
`inferrepo`. | ||||
The `norepo` argument defines whether the command does not require a | ||||
|
r32337 | local repository. Most commands operate against a repository, thus the | ||
|
r35106 | default is False. When True, no repository will be passed. | ||
|
r32337 | |||
|
r35106 | The `optionalrepo` argument defines whether the command optionally requires | ||
a local repository. If no repository can be found, None will be passed | ||||
to the decorated function. | ||||
|
r32337 | |||
|
r35106 | The `inferrepo` argument defines whether to try to find a repository from | ||
the command line arguments. If True, arguments will be examined for | ||||
potential repository locations. See ``findrepo()``. If a repository is | ||||
found, it will be used and passed to the decorated function. | ||||
|
r34782 | |||
|
r37734 | The `intents` argument defines a set of intended actions or capabilities | ||
the command is taking. These intents can be used to affect the construction | ||||
of the repository object passed to the command. For example, commands | ||||
declaring that they are read-only could receive a repository that doesn't | ||||
have any methods allowing repository mutation. Other intents could be used | ||||
to prevent the command from running if the requested intent could not be | ||||
fulfilled. | ||||
|
r34782 | |||
|
r40327 | If `helpcategory` is set (usually to one of the constants in the help | ||
module), the command will be displayed under that category in the help's | ||||
list of commands. | ||||
|
r37734 | The following intents are defined: | ||
readonly | ||||
The command is read-only | ||||
|
r35106 | |||
The signature of the decorated function looks like this: | ||||
def cmd(ui[, repo] [, <args>] [, <options>]) | ||||
`repo` is required if `norepo` is False. | ||||
`<args>` are positional args (or `*args`) arguments, of non-option | ||||
arguments from the command line. | ||||
`<options>` are keyword arguments (or `**options`) of option arguments | ||||
from the command line. | ||||
See the WritingExtensions and MercurialApi documentation for more exhaustive | ||||
descriptions and examples. | ||||
|
r32337 | """ | ||
|
r32338 | |||
|
r40327 | # Command categories for grouping them in help output. | ||
|
r40450 | # These can also be specified for aliases, like: | ||
# [alias] | ||||
# myalias = something | ||||
# myalias:category = repo | ||||
|
r40329 | CATEGORY_REPO_CREATION = 'repo' | ||
CATEGORY_REMOTE_REPO_MANAGEMENT = 'remote' | ||||
CATEGORY_COMMITTING = 'commit' | ||||
CATEGORY_CHANGE_MANAGEMENT = 'management' | ||||
CATEGORY_CHANGE_ORGANIZATION = 'organization' | ||||
CATEGORY_FILE_CONTENTS = 'files' | ||||
CATEGORY_CHANGE_NAVIGATION = 'navigation' | ||||
CATEGORY_WORKING_DIRECTORY = 'wdir' | ||||
CATEGORY_IMPORT_EXPORT = 'import' | ||||
CATEGORY_MAINTENANCE = 'maintenance' | ||||
CATEGORY_HELP = 'help' | ||||
CATEGORY_MISC = 'misc' | ||||
|
r40327 | CATEGORY_NONE = 'none' | ||
|
r32338 | def _doregister(self, func, name, options=(), synopsis=None, | ||
|
r34782 | norepo=False, optionalrepo=False, inferrepo=False, | ||
|
r40331 | intents=None, helpcategory=None, helpbasic=False): | ||
|
r32339 | func.norepo = norepo | ||
func.optionalrepo = optionalrepo | ||||
func.inferrepo = inferrepo | ||||
|
r37734 | func.intents = intents or set() | ||
|
r40327 | func.helpcategory = helpcategory | ||
|
r40331 | func.helpbasic = helpbasic | ||
|
r32339 | if synopsis: | ||
self._table[name] = func, list(options), synopsis | ||||
else: | ||||
self._table[name] = func, list(options) | ||||
return func | ||||
|
r32337 | |||
|
r37734 | INTENT_READONLY = b'readonly' | ||
|
r28393 | class revsetpredicate(_funcregistrarbase): | ||
"""Decorator to register revset predicate | ||||
Usage:: | ||||
revsetpredicate = registrar.revsetpredicate() | ||||
@revsetpredicate('mypredicate(arg1, arg2[, arg3])') | ||||
def mypredicatefunc(repo, subset, x): | ||||
'''Explanation of this revset predicate .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
Optional argument 'safe' indicates whether a predicate is safe for | ||||
DoS attack (False by default). | ||||
|
r29933 | Optional argument 'takeorder' indicates whether a predicate function | ||
takes ordering policy as the last argument. | ||||
|
r34274 | Optional argument 'weight' indicates the estimated run-time cost, useful | ||
for static optimization, default is 1. Higher weight means more expensive. | ||||
Usually, revsets that are fast and return only one revision has a weight of | ||||
0.5 (ex. a symbol); revsets with O(changelog) complexity and read only the | ||||
changelog have weight 10 (ex. author); revsets reading manifest deltas have | ||||
weight 30 (ex. adds); revset reading manifest contents have weight 100 | ||||
(ex. contains). Note: those values are flexible. If the revset has a | ||||
same big-O time complexity as 'contains', but with a smaller constant, it | ||||
might have a weight of 90. | ||||
|
r28393 | 'revsetpredicate' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'revsetpredicate' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'revset.loadpredicate()' is needed. | ||||
""" | ||||
_getname = _funcregistrarbase._parsefuncdecl | ||||
|
r31820 | _docformat = "``%s``\n %s" | ||
|
r28393 | |||
|
r34274 | def _extrasetup(self, name, func, safe=False, takeorder=False, weight=1): | ||
|
r28393 | func._safe = safe | ||
|
r29933 | func._takeorder = takeorder | ||
|
r34274 | func._weight = weight | ||
|
r28447 | |||
class filesetpredicate(_funcregistrarbase): | ||||
"""Decorator to register fileset predicate | ||||
Usage:: | ||||
filesetpredicate = registrar.filesetpredicate() | ||||
@filesetpredicate('mypredicate()') | ||||
def mypredicatefunc(mctx, x): | ||||
'''Explanation of this fileset predicate .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
Optional argument 'callstatus' indicates whether a predicate | ||||
implies 'matchctx.status()' at runtime or not (False, by | ||||
default). | ||||
|
r38865 | Optional argument 'weight' indicates the estimated run-time cost, useful | ||
for static optimization, default is 1. Higher weight means more expensive. | ||||
|
r38899 | There are predefined weights in the 'filesetlang' module. | ||
|
r38865 | |||
|
r38866 | ====== ============================================================= | ||
Weight Description and examples | ||||
====== ============================================================= | ||||
0.5 basic match patterns (e.g. a symbol) | ||||
10 computing status (e.g. added()) or accessing a few files | ||||
30 reading file content for each (e.g. grep()) | ||||
50 scanning working directory (ignored()) | ||||
====== ============================================================= | ||||
|
r28447 | 'filesetpredicate' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'filesetpredicate' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'fileset.loadpredicate()' is needed. | ||||
""" | ||||
_getname = _funcregistrarbase._parsefuncdecl | ||||
|
r31820 | _docformat = "``%s``\n %s" | ||
|
r28447 | |||
|
r38865 | def _extrasetup(self, name, func, callstatus=False, weight=1): | ||
|
r28447 | func._callstatus = callstatus | ||
|
r38865 | func._weight = weight | ||
|
r28538 | |||
class _templateregistrarbase(_funcregistrarbase): | ||||
"""Base of decorator to register functions as template specific one | ||||
""" | ||||
|
r31820 | _docformat = ":%s: %s" | ||
|
r28538 | |||
class templatekeyword(_templateregistrarbase): | ||||
"""Decorator to register template keyword | ||||
Usage:: | ||||
|
r30332 | templatekeyword = registrar.templatekeyword() | ||
|
r28538 | |||
|
r36463 | # new API (since Mercurial 4.6) | ||
@templatekeyword('mykeyword', requires={'repo', 'ctx'}) | ||||
def mykeywordfunc(context, mapping): | ||||
'''Explanation of this template keyword .... | ||||
''' | ||||
pass | ||||
|
r38966 | # old API (DEPRECATED) | ||
|
r28538 | @templatekeyword('mykeyword') | ||
def mykeywordfunc(repo, ctx, templ, cache, revcache, **args): | ||||
'''Explanation of this template keyword .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
|
r36463 | Optional argument 'requires' should be a collection of resource names | ||
which the template keyword depends on. This also serves as a flag to | ||||
switch to the new API. If 'requires' is unspecified, all template | ||||
keywords and resources are expanded to the function arguments. | ||||
|
r28538 | 'templatekeyword' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'templatekeyword' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'templatekw.loadkeyword()' is needed. | ||||
""" | ||||
|
r28692 | |||
|
r36463 | def _extrasetup(self, name, func, requires=None): | ||
func._requires = requires | ||||
|
r28692 | class templatefilter(_templateregistrarbase): | ||
"""Decorator to register template filer | ||||
Usage:: | ||||
templatefilter = registrar.templatefilter() | ||||
|
r37239 | @templatefilter('myfilter', intype=bytes) | ||
|
r28692 | def myfilterfunc(text): | ||
'''Explanation of this template filter .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
|
r37239 | Optional argument 'intype' defines the type of the input argument, | ||
|
r37244 | which should be (bytes, int, templateutil.date, or None for any.) | ||
|
r37239 | |||
|
r28692 | 'templatefilter' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'templatefilter' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'templatefilters.loadkeyword()' is needed. | ||||
""" | ||||
|
r28695 | |||
|
r37239 | def _extrasetup(self, name, func, intype=None): | ||
func._intype = intype | ||||
|
r28695 | class templatefunc(_templateregistrarbase): | ||
"""Decorator to register template function | ||||
Usage:: | ||||
templatefunc = registrar.templatefunc() | ||||
|
r38447 | @templatefunc('myfunc(arg1, arg2[, arg3])', argspec='arg1 arg2 arg3', | ||
requires={'ctx'}) | ||||
|
r28695 | def myfuncfunc(context, mapping, args): | ||
'''Explanation of this template function .... | ||||
''' | ||||
pass | ||||
The first string argument is used also in online help. | ||||
|
r31886 | If optional 'argspec' is defined, the function will receive 'args' as | ||
a dict of named arguments. Otherwise 'args' is a list of positional | ||||
arguments. | ||||
|
r38447 | Optional argument 'requires' should be a collection of resource names | ||
which the template function depends on. | ||||
|
r28695 | 'templatefunc' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'templatefunc' is used for | ||||
decorating in extension. | ||||
|
r36940 | Otherwise, explicit 'templatefuncs.loadfunction()' is needed. | ||
|
r28695 | """ | ||
_getname = _funcregistrarbase._parsefuncdecl | ||||
|
r31886 | |||
|
r38447 | def _extrasetup(self, name, func, argspec=None, requires=()): | ||
|
r31886 | func._argspec = argspec | ||
|
r38447 | func._requires = requires | ||
|
r33663 | |||
class internalmerge(_funcregistrarbase): | ||||
"""Decorator to register in-process merge tool | ||||
Usage:: | ||||
internalmerge = registrar.internalmerge() | ||||
@internalmerge('mymerge', internalmerge.mergeonly, | ||||
|
r39158 | onfailure=None, precheck=None, | ||
binary=False, symlink=False): | ||||
|
r33663 | def mymergefunc(repo, mynode, orig, fcd, fco, fca, | ||
toolconf, files, labels=None): | ||||
'''Explanation of this internal merge tool .... | ||||
''' | ||||
return 1, False # means "conflicted", "no deletion needed" | ||||
The first string argument is used to compose actual merge tool name, | ||||
":name" and "internal:name" (the latter is historical one). | ||||
The second argument is one of merge types below: | ||||
========== ======== ======== ========= | ||||
merge type precheck premerge fullmerge | ||||
========== ======== ======== ========= | ||||
nomerge x x x | ||||
mergeonly o x o | ||||
fullmerge o o o | ||||
========== ======== ======== ========= | ||||
|
r34437 | Optional argument 'onfailure' is the format of warning message | ||
|
r33663 | to be used at failure of merging (target filename is specified | ||
at formatting). Or, None or so, if warning message should be | ||||
suppressed. | ||||
Optional argument 'precheck' is the function to be used | ||||
before actual invocation of internal merge tool itself. | ||||
It takes as same arguments as internal merge tool does, other than | ||||
'files' and 'labels'. If it returns false value, merging is aborted | ||||
immediately (and file is marked as "unresolved"). | ||||
|
r39158 | Optional argument 'binary' is a binary files capability of internal | ||
merge tool. 'nomerge' merge type implies binary=True. | ||||
Optional argument 'symlink' is a symlinks capability of inetrnal | ||||
merge function. 'nomerge' merge type implies symlink=True. | ||||
|
r33663 | 'internalmerge' instance in example above can be used to | ||
decorate multiple functions. | ||||
Decorated functions are registered automatically at loading | ||||
extension, if an instance named as 'internalmerge' is used for | ||||
decorating in extension. | ||||
Otherwise, explicit 'filemerge.loadinternalmerge()' is needed. | ||||
""" | ||||
_docformat = "``:%s``\n %s" | ||||
# merge type definitions: | ||||
nomerge = None | ||||
mergeonly = 'mergeonly' # just the full merge, no premerge | ||||
fullmerge = 'fullmerge' # both premerge and merge | ||||
def _extrasetup(self, name, func, mergetype, | ||||
|
r39158 | onfailure=None, precheck=None, | ||
binary=False, symlink=False): | ||||
|
r33663 | func.mergetype = mergetype | ||
func.onfailure = onfailure | ||||
func.precheck = precheck | ||||
|
r39158 | |||
binarycap = binary or mergetype == self.nomerge | ||||
symlinkcap = symlink or mergetype == self.nomerge | ||||
# actual capabilities, which this internal merge tool has | ||||
func.capabilities = {"binary": binarycap, "symlink": symlinkcap} | ||||