documentation

Author: Christopher Doris

docs/src/compat.md

@@ -2,7 +2,8 @@
 
 Some packages require a little extra help to work nicely with PythonCall.
 
-Some of these are "fixes" that are silently applied for you, and some are just extra functions to bridge a gap. We aim to keep these as minimal as possible.
+Some of these are "fixes" that are silently applied for you, and some are just extra
+functions to bridge a gap. We aim to keep these as minimal as possible.
 
 ## Stdlib
 
@@ -58,6 +59,11 @@ PythonCall.fix_qt_plugin_path
 
 ## IPython
 
-If Python is running an IPython kernel, then:
-- Currently disabled: Julia's `Base.stdout` is set to Python's `sys.stdout`.
-- A `PythonDisplay` and `IPythonDisplay` are pushed onto Julia's display stack, so that `display(x)` goes to IPython if possible.
+The `juliacall.ipython` IPython extension adds these features to your IPython session:
+- The line magic `%jl code` executes the given Julia code in-line.
+- The cell magic `%%jl` executes a cell of Julia code.
+- Julia's `stdout` and `stderr` are redirected to IPython.
+- Calling `display(x)` from Julia will display `x` in IPython.
+
+Enable the extension with `%load_ext juliacall.ipython`.
+See https://ipython.readthedocs.io/en/stable/config/extensions/.

pysrc/juliacall/importer.py

@@ -1,4 +1,23 @@
-import base64
+"""Experimental module for loading Julia files as Python modules.
+
+Being experimental, it does not form part of the JuliaCall API. It may be changed or removed
+in any release.
+
+Basic usage is:
+    import juliacall.importer
+    juliacall.importer.install()
+
+And now you can import any Julia file as Python module. That is, if 'foo.jl' is in your
+Python path, then 'import foo' will work.
+
+By default, all objects at the top level of the file whose name does not start with '_' are
+exposed. Alternatively, you may explicitly 'export' objects.
+
+The importer is intended for development use. To release a package, use 'gen_file' on each
+Julia module file to generate a corresponding Python file and only include the Python files
+in the release.
+"""
+
 import io
 import os
 import sys
@@ -28,11 +47,19 @@ def find_spec(self, fullname, path, target=None):
                 return ModuleSpec(fullname, SourceFileLoader(fullname, pyfile), origin=jlfile)
 
 def install(**kw):
+    """Install the Julia importer.
+
+    After calling this, files ending '.jl' in your Python path may be imported as Python
+    modules.
+
+    The return value may be passed to 'uninstall'.
+    """
     finder = Finder(**kw)
     sys.meta_path.insert(0, finder)
     return finder
 
 def uninstall(finder):
+    """Uninstall the Julia importer."""
     sys.meta_path.remove(finder)
 
 def gen_code(jl):
@@ -46,6 +73,7 @@ def gen_code(jl):
     return buf.getvalue()
 
 def gen_file(jl, py):
+    """Convert a Julia module file to a Python module file."""
     with open(jl, encoding='utf-8') as fp:
         jlcode = fp.read()
     pycode = gen_code(jlcode)

pysrc/juliacall/ipython.py

@@ -1,3 +1,17 @@
+"""Experimental IPython extension for Julia.
+
+Being experimental, it does not form part of the JuliaCall API. It may be changed or removed
+in any release.
+
+Enable the extension by calling the magic '%load_ext juliacall.ipython'.
+
+Features:
+- Magic `%jl code` to evaluate a piece of Julia code in-line.
+- Cell magic `%%jl` to evaluate a cell of Julia code.
+- Julia's stdin and stdout are redirected to Python's stdin and stdout.
+- Calling Julia's 'display(x)' function will display 'x' in IPython.
+"""
+
 from IPython.core.magic import Magics, magics_class, line_cell_magic
 from . import Main, Base, PythonCall
 
@@ -17,11 +31,14 @@ def load_ipython_extension(ip):
     # register magics
     ip.register_magics(JuliaMagics(ip))
     # redirect stdout/stderr
+    # push displays
     PythonCall.seval("""begin
         const _redirected_stdout = redirect_stdout()
         const _redirected_stderr = redirect_stderr()
         const _py_stdout = PyIO(pyimport("sys" => "stdout"), buflen=1)
         const _py_stderr = PyIO(pyimport("sys" => "stderr"), buflen=1)
         const _redirect_stdout_task = @async write($_py_stdout, $_redirected_stdout)
         const _redirect_stderr_task = @async write($_py_stderr, $_redirected_stderr)
+        pushdisplay(PythonDisplay())
+        pushdisplay(IPythonDisplay())
     end""")

src/PythonCall.jl

@@ -106,7 +106,6 @@ function __init__()
         init_stdlib()
         init_pyshow()
         init_gui()
-        init_ipython()
         init_tables()
         init_ctypes()
         init_numpy()

src/compat/ipython.jl

@@ -68,14 +68,3 @@ function Base.display(d::IPythonDisplay, @nospecialize(x))
     ipy.display.display(dict, raw=true)
     return
 end
-
-function init_ipython()
-    # EXPERIMENTAL: IPython integration
-    if C.CTX.is_embedded && CONFIG.auto_ipython_display
-        is_ipython = ("IPython" in pysysmodule.modules) && !pyisnone(pysysmodule.modules["IPython"].get_ipython())
-        if is_ipython
-            pushdisplay(PythonDisplay())
-            pushdisplay(IPythonDisplay())
-        end
-    end
-end

src/config.jl

@@ -2,7 +2,6 @@ Base.@kwdef mutable struct Config
     meta :: String = ""
     auto_sys_last_traceback :: Bool = true
     auto_fix_qt_plugin_path :: Bool = true
-    auto_ipython_display :: Bool = true
 end
 
 const CONFIG = Config()