Skip to content

Latest commit

 

History

History
117 lines (94 loc) · 5.69 KB

README.md

File metadata and controls

117 lines (94 loc) · 5.69 KB

Show Markdown from within Code Cells in Jupyter and VS Code's Interactive Python

Description

This package now serves two purposes:

  1. Display markdown from within code cells in IPython output, while ignoring it when run in normal Python (like usual comments). For example, 
    "V = {1 \over 3} \pi r^2 h".md()
  2. Display objects other than strings in IPython output using an extension-like function .md(). For example: 
    dot = Digraph()
# ...
dot.md()

A note on how it can be useful can be found on randompearls.com.

Dependencies

These packages are auto-installed during the installation of this package.

  • forbiddenfruit
  • markdown
  • beautifulsoup4

IPython is not installed automatically.
This is because if you use the overridden print statements (explained below), they are supposed to work without IPython as well.
But, if you do have IPython, those print statements will print formatted text.

Note that forbiddenfruit is installed as a dependency, so that statements of the form "*anymdstring*".md(dtype=DisplayType.Type) can be used conveniently.

You can uninstall forbiddenfruit if you want and then use display_ccmd("*anymdstring*", dtype=DisplayType.MARKDOWN).

Installation

The package can be installed by running:

pip install git+https://github.com/manisar2/ipyccmd.git

Or, copy the code from src/ipyccmd/__init__.py into your project.

Usage

It can be used in two ways depending upon your taste:

  • using function display_ccmd() (or curse function .md()), or
  • by overriding print().

Note that you will not need the import statements shown below if you have copy-pasted the code from src/ipyccmd/__init__.py into your current file.

A. Using display_ccmd() or curse .md():

# With curse .md():
from ipyccmd import DisplayType
"Now we'll *calculate* the **area** as per $A = \pi r^2 + 2 \pi r h$.".md()
"V = {1 \over 3} \pi r^2 h".md(dtype=DisplayType.MATH, python_print=True)
(2).md(DisplayType.MATH) # .md() is not limited to strings
object().md()

# Without using curse (can uninstall forbiddenfruit):
from ipyccmd import display_ccmd, DisplayType
display_ccmd("Now we'll calculate the area as per $A = \pi r^2 + 2 \pi r h$.")
display_ccmd("V = {1 \over 3} \pi r^2 h", dtype=DisplayType.MATH, python_print=True)
display_ccmd(2, DisplayType.MATH)

# In both the cases, if you pass python_print=True or set global PYTHON_PRINT=True (default),
# the string will also be printed when the code is run as normal Python - with markdown symbols
# and HTML tags removed (except MATH symbols).

# Thus, you can have your string displayed in both IPython and Python - with formatting, and
# without markdown symbols and HTML tags respectively.

B. By Overriding print():

from ipyccmd import md_print, DisplayType
print = md_print
print("Now we'll *calculate* the **area** as per $A = \pi r^2 + 2 \pi r h$.")
print("V = {1 \over 3} \pi r^2 h", is_md=True, dtype=DisplayType.MATH)
print(2, is_md=True, dtype=DisplayType.MATH) # the new print can handle other objects as well
print(object(), is_md=True) # any object can be displayed/printed
# This overriden print will ensure that the string is displayed in both IPython (formatted) and
# Python (with markdown symbols and HTML tags removed).

# The value of the argument is_md or global IS_MD will work as follows:
#   True (default) => formatted text in IPython, plain_text (without markdown symbols and HTML tags) in Python
#   False => unmodified text in both IPython and Python (like normal print)

The advantage with B. is that if print() is used without any arguments (is_md and type), all the print statements will continue to work in both IPython and Python even without this package, thus giving you the option of not using this package in production.

Examples

See a .py or notebook example.

The notebook shows some of the outputs generated by using different DisplayTypes.

Configuration

  1. The display can be modified in these ways (using dtype argument):

    • MARKDOWN
    • LATEX
    • MATH
    • HTML
    • PRETTY - use this for displaying / printing the default representation of the object
    • NONE - this will let display() handle the object (and not any of its representations)

  2. If dtype is not provided, it is automatically determined as follows:

    • If global DEFAULT_DTYPE is set, its value will be used; otherwise
    • dtype will be set to .MARKDOWN if obj is str, else .PRETTY

  3. In IPython, object name can also be printed (default behavior).

    This is governed by the argument print_objname or the global PRINT_OBJNAME.

  4. Restricting displaying to IPython only

    Pass python_print as False or set the global PYTHON_PRINT to False.
    Note that this is applicable only to display_ccmd() or md().
    If you are using overriden print() or md_print(), it will always print in both IPython and Python.

  5. Suppressing the package temporarily

    The functions display_ccmd(), md(), print() and md_print() provide the following two features:

    • displaying formatted text in IPython; and
    • printing markdown-html-stripped text in Python

    If you want to suppress this functionality temporarily, either pass is_md=False, or set the global IS_MD=False. This will enable normal printing.