~bzr-pqm/bzr/bzr.dev : revision 4133

17

18

"""Support for plugin hooking logic."""

19

from bzrlib.lazy_import import lazy_import

20

from bzrlib import registry

20

21

from bzrlib.symbol_versioning import deprecated_method, one_five

21

22

lazy_import(globals(), """

22

23

import textwrap

25

26

_format_version_tuple,

26

27

errors,

27

28

)

29

from bzrlib.help_topics import help_as_plain_text

28

30

""")

29

31

30

32

33

known_hooks = registry.Registry()

34

known_hooks.register_lazy(('bzrlib.branch', 'Branch.hooks'), 'bzrlib.branch',

35

'BranchHooks')

36

known_hooks.register_lazy(('bzrlib.commands', 'Command.hooks'),

37

'bzrlib.commands', 'CommandHooks')

38

known_hooks.register_lazy(('bzrlib.lock', 'Lock.hooks'), 'bzrlib.lock',

39

'LockHooks')

40

known_hooks.register_lazy(('bzrlib.mutabletree', 'MutableTree.hooks'),

41

'bzrlib.mutabletree', 'MutableTreeHooks')

42

known_hooks.register_lazy(('bzrlib.smart.client', '_SmartClient.hooks'),

43

'bzrlib.smart.client', 'SmartClientHooks')

44

known_hooks.register_lazy(('bzrlib.smart.server', 'SmartTCPServer.hooks'),

45

'bzrlib.smart.server', 'SmartServerHooks')

46

47

48

def known_hooks_key_to_object((module_name, member_name)):

49

"""Convert a known_hooks key to a object.

50

51

:param key: A tuple (module_name, member_name) as found in the keys of

52

the known_hooks registry.

53

:return: The object this specifies.

54

"""

55

return registry._LazyObjectGetter(module_name, member_name).get_obj()

56

57

58

def known_hooks_key_to_parent_and_attribute((module_name, member_name)):

59

"""Convert a known_hooks key to a object.

60

61

:param key: A tuple (module_name, member_name) as found in the keys of

62

the known_hooks registry.

63

:return: The object this specifies.

64

"""

65

member_list = member_name.rsplit('.', 1)

66

if len(member_list) == 2:

67

parent_name, attribute = member_list

68

else:

69

parent_name = None

70

attribute = member_name

71

parent = known_hooks_key_to_object((module_name, parent_name))

72

return parent, attribute

73

74

31

75

class Hooks(dict):

32

76

"""A dictionary mapping hook name to a list of callables.

33

77

59

103

hook_docs = []

60

104

name = self.__class__.__name__

61

105

hook_docs.append(name)

62

hook_docs.append("="*len(name))

106

hook_docs.append("-"*len(name))

63

107

hook_docs.append("")

64

108

for hook_name in hook_names:

65

109

hook = self[hook_name]

69

113

# legacy hook

70

114

strings = []

71

115

strings.append(hook_name)

72

strings.append("-" * len(hook_name))

116

strings.append("~" * len(hook_name))

73

117

strings.append("")

74

118

strings.append("An old-style hook. For documentation see the __init__ "

75

119

"method of '%s'\n" % (name,))

162

206

"""

163

207

strings = []

164

208

strings.append(self.name)

165

strings.append('-'*len(self.name))

209

strings.append('~'*len(self.name))

166

210

strings.append('')

167

211

if self.introduced:

168

212

introduced_string = _format_version_tuple(self.introduced)

179

223

strings.append('')

180

224

return '\n'.join(strings)

181

225

226

def __eq__(self, other):

227

return (type(other) == type(self) and

228

other.__dict__ == self.__dict__)

229

182

230

def hook(self, callback, callback_label):

183

231

"""Register a callback to be called when this HookPoint fires.

184

232

187

235

processing.

188

236

"""

189

237

self._callbacks.append(callback)

190

self._callback_names[callback] = callback_label

238

if callback_label is not None:

239

self._callback_names[callback] = callback_label

191

240

192

241

def __iter__(self):

193

242

return iter(self._callbacks)

194

243

244

def __len__(self):

245

return len(self._callbacks)

246

195

247

def __repr__(self):

196

248

strings = []

197

249

strings.append("<%s(" % type(self).__name__)

206

258

strings[-1] = ")"

207

259

strings.append("]>")

208

260

return ''.join(strings)

261

262

263

_help_prefix = \

264

"""

265

Hooks

266

=====

267

268

Introduction

269

------------

270

271

A hook of type *xxx* of class *yyy* needs to be registered using::

272

273

yyy.hooks.install_named_hook("xxx", ...)

274

275

See `Using hooks`_ in the User Guide for examples.

276

277

.. _Using hooks: ../user-guide/index.html#using-hooks

278

279

The class that contains each hook is given before the hooks it supplies. For

280

instance, BranchHooks as the class is the hooks class for

281

`bzrlib.branch.Branch.hooks`.

282

283

Each description also indicates whether the hook runs on the client (the

284

machine where bzr was invoked) or the server (the machine addressed by

285

the branch URL). These may be, but are not necessarily, the same machine.

286

287

Plugins (including hooks) are run on the server if all of these is true:

288

289

* The connection is via a smart server (accessed with a URL starting with

290

"bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"

291

URL when a smart server is available via HTTP).

292

293

* The hook is either server specific or part of general infrastructure rather

294

than client specific code (such as commit).

295

296

"""

297

298

def hooks_help_text(topic):

299

segments = [_help_prefix]

300

for hook_key in sorted(known_hooks.keys()):

301

hooks = known_hooks_key_to_object(hook_key)

302

segments.append(hooks.docs())

303

return '\n'.join(segments)