Coverage for pyquickhelper/ipythonhelper/magic_class_example.py: 96%
26 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-03 02:21 +0200
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-03 02:21 +0200
1# -*- coding: utf-8 -*-
2"""
3@file
4@brief Example of a class which defines magic commands.
5"""
6from __future__ import print_function
7from IPython.core.magic import magics_class, line_magic
8from .magic_class import MagicClassWithHelpers
9from .magic_parser import MagicCommandParser
10from ..helpgen import docstring2html
13@magics_class
14class MagicClassExample(MagicClassWithHelpers):
16 """
17 .. faqref::
18 :title: Define a magic command
20 This class is an example of how a magic commands can be defined
21 with parameters as if it was a regular command in a terminal.
22 The class @see cl MagicClassExample defines magic
23 command ``htmlhelp`` and the associated parser.
24 Function @see fn load_ipython_extension
25 register the magic command through ``%load_ext pyquickhelper``.
26 The magic command can be unit tested with::
28 mg = MagicClassExample()
29 mg.add_context(context={"MagicClassExample": MagicClassExample})
30 cmd = "MagicClassExample -f text"
31 res = mg.htmlhelp(cmd)
32 assert "NB(example of a magic command)"
33 """
35 @staticmethod
36 def htmlhelp_parser():
37 """
38 Defines the way to parse the magic command ``%htmlhelp``.
39 """
40 parser = MagicCommandParser(prog="htmlhelp",
41 description='display help for an object in HTML format')
42 parser.add_argument(
43 'obj',
44 type=str,
45 help='a python object')
46 parser.add_argument(
47 '-f',
48 '--format',
49 type=str,
50 default="html",
51 help='format',
52 choices=['text', 'html', 'rst', 'rawhtml'])
53 parser.add_argument(
54 '-np',
55 '--no-print',
56 action='store_true',
57 help='by default, the magic command outputs everything on the standard output, '
58 'if specified, it returns a string')
59 return parser
61 @line_magic
62 def htmlhelp(self, line):
63 """
64 Defines ``%htmlhelp``, it displays the help for an object in :epkg:`HTML`.
66 .. nbref::
67 :title: %htmlhelp
69 Magic command ``htmlhelp`` convert docstring (RST)
70 into HTML format for a better display in a notebook.
71 It is equivalent to the code:
73 ::
75 from pyquickhelper.helpgen import docstring2html
76 obj = <function or object>
77 docstring2html(obj, format="html")
79 See function @see fn docstring2html.
80 """
81 parser = self.get_parser(MagicClassExample.htmlhelp_parser, "htmlhelp")
82 args = self.get_args(line, parser)
84 if args is not None:
85 obj = args.obj
86 format = args.format
87 nop = args.no_print
88 if nop or format == "html":
89 return docstring2html(obj, format=format)
90 print(docstring2html(obj, format=format))
91 return None # pragma: no cover
94def register_file_magics(ip=None): # pragma: no cover
95 """
96 Registers magics functions, can be called from a notebook.
98 @param ip from ``get_ipython()``
99 """
100 if ip is None:
101 from IPython import get_ipython
102 ip = get_ipython()
103 ip.register_magics(MagicClassExample)