adds juliacall.using

Author: Christopher Doris

docs/src/juliacall.md

@@ -98,6 +98,30 @@ and will ensure the given packages are installed.
 
 ## Utilities
 
+`````@customdoc
+juliacall.using - Function
+
+```python
+using(globals, module, attrs=None, prefix='jl', rename=None)
+```
+
+Import the Julia `module` into `globals`.
+
+If `attrs` is given, the given attributes are imported from the module instead of the
+module itself. It may be a list of strings or a space-separated string.
+
+Each item imported is renamed before being added to `globals`. By default a `prefix` is
+added. You more generally supply a `rename` function which maps a string to a string.
+
+In the following example we import some items from `Base` to do some vector operations:
+```python
+juliacall.using(locals(), 'Base', 'Vector Int push! pop!', rename=lambda x:'jl'+x.replace('!',''))
+x = jlVector[jlInt]()
+jlpush(x, 1, 2, 3)
+jlpop(x)  # 3
+```
+`````
+
 `````@customdoc
 juliacall.newmodule - Function
 

python/juliacall/__init__.py

@@ -7,6 +7,42 @@ def newmodule(name):
     "A new module with the given name."
     return Base.Module(Base.Symbol(name))
 
+def using(globals, module, attrs=None, prefix='jl', rename=None):
+    """Import a module into globals.
+
+    Args:
+        globals: A dict to import into (usually 'locals()').
+        module: The name of the module to import.
+        attrs: If given, import these attributes from the module instead of
+            the module itself. A list of strings or a space-separated string.
+        prefix: A prefix added to the name of each imported item.
+        rename: If given, a function mapping names to the name assigned in globals.
+    """
+    # rename
+    if rename is None:
+        rename = lambda name: prefix + name
+    # import the module
+    path = module.split('.')
+    mname = path[0]
+    if mname == 'Base':
+        module = Base
+    elif mname == 'Core':
+        module = Core
+    elif mname == 'Main':
+        module = Main
+    else:
+        module = Base.require(Base.Main, Base.Symbol(mname))
+    for attr in path[1:]:
+        module = Base.getproperty(module, Base.Symbol(attr))
+    # export
+    if attrs is None:
+        globals[rename(path[-1])] = module
+    else:
+        if isinstance(attrs, str):
+            attrs = attrs.split()
+        for attr in attrs:
+            globals[rename(attr)] = getattr(module, attr)
+
 class As:
     "Interpret 'value' as type 'type' when converting to Julia."
     __slots__ = ("value", "type")