documentation

Author: Christopher Doris

docs/src/compat.md

@@ -12,21 +12,21 @@ Whenever a Python exception is displayed by Julia, `sys.last_traceback` and frie
 
 A `pandas.DataFrame` can be wrapped in Julia as a [`PyPandasDataFrame`](@ref), providing a `Tables.jl`-compatible interface.
 
+Furthermore, any Python object which can be converted to a `PyTable` (e.g. `pandas.DataFrame` can be converted to `PyPandasDataFrame`) satisfies the Tables.jl interface.
+
 In the other direction, the following functions can be used to convert any `Tables.jl`-compatible table to a Python table.
 
 ```@docs
-pycolumntable
-pyrowtable
-pypandasdataframe
+pytable
 ```
 
 ## MatPlotLib / PyPlot
 
 ```@docs
-pyplotshow
+pyplot_show
 ```
 
-If Julia is running an IJulia kernel, `pyplotshow()` is automatically called after executing a cell, so that plots generated in a cell are always shown (similar to IPython). It can be disabled by setting `PythonCall.CONFIG.pyplotautoshow = false`.
+If Julia is running an IJulia kernel, `pyplot_show()` is automatically called after executing a cell, so that plots generated in a cell are always shown (similar to IPython). It can be disabled by setting `PythonCall.CONFIG.auto_pyplot_show = false`.
 
 ## GUIs (including MatPlotLib)
 
@@ -39,14 +39,6 @@ PythonCall.event_loop_on
 PythonCall.event_loop_off
 ```
 
-### Interaction
-
-The following is an alternative to using event loops to enable interactive plotting.
-
-```@docs
-pyinteract
-```
-
 ### Qt path fix
 
 ```@docs
@@ -58,3 +50,5 @@ PythonCall.fix_qt_plugin_path
 If Python is running an IPython kernel, then:
 - Julia's `Base.stdout` is set to Python's `sys.stdout`.
 - An `IPythonDisplay` is pushed onto Julia's display stack, so that `display(x)` goes to IPython if possible.
+
+This is disabled by setting `PythonCall.CONFIG.auto_ipython_display = false`.

docs/src/getting-started.md

@@ -1,15 +1,11 @@
 # Getting Started
 
-## You will need
-
-* Julia 1.0 or higher — download [here](https://julialang.org/downloads).
-* Python 3.5 or higher — download [here](https://www.python.org/downloads) or set `JULIA_PYTHONCALL_EXE=CONDA` (see below).
-
 ## Install the Julia package `PythonCall`
 
 ```julia
-using Pkg
-pkg"add PythonCall"
+julia> using Pkg
+
+pkg> add PythonCall
 ```
 
 ## Install the Python package `juliacall` (optional)
@@ -36,19 +32,8 @@ packages can always `import juliacall`.
 
 ## Environment variables
 
-If Julia and Python are in your PATH, then no further set-up is required.
-Otherwise, the following environment variables control how the package finds these.
-- `JULIA_PYTHONCALL_EXE`: Path to the Python executable. Or one of the following special
-  values:
-  - `CONDA`: Use Python from the default conda environment. In this case, if `conda` is not
-    detected then `Conda.jl` will automatically install
-    [`miniconda`](https://docs.conda.io/en/latest/miniconda.html) in your Julia depot.
-  - `CONDA:{env}`: Use Python from the given conda environment. Also automatically installs
-    miniconda.
-  - `PYCALL`: Import [`PyCall`](https://github.com/JuliaPy/PyCall.jl) and use whichever
-    Python that uses.
-- `JULIA_PYTHONCALL_LIB`: Path to the Python library. Normally this is inferred from the Python
-  executable, but can be over-ridden.
-- `PYTHON_JULIACALL_EXE`: Path to the Julia executable.
-- `PYTHON_JULIACALL_LIB`: Path to the Julia library. Normally this is inferred from the Julia
-  executable, but can be over-ridden.
+- `JULIA_PYTHONCALL_EXE`: By default, `PythonCall` manages its own installation of Python
+  specific to a particular Julia environment, so that the set of installed Python packages
+  is isolated between environments. To instead use a pre-installed version of Python, set
+  this variable to its path. It can simply be set to `python` if it is in your `PATH`.
+- `PYTHON_JULIACALL_EXE`: The path to the Julia executable. By default, it uses `julia`.

docs/src/juliacall.md

@@ -39,8 +39,7 @@ There is also a [`RawValue`](#juliacall.RawValue) object, which gives a stricter
     - [`DictValue`](#juliacall.DictValue)
     - [`SetValue`](#juliacall.SetValue)
     - [`IOValue`](#juliacall.IOValue)
-      - `RawIOValue`
-      - `BufferedIOValue`
+      - `BinaryIOValue`
       - `TextIOValue`
     - [`ModuleValue`](#juliacall.ModuleValue)
     - [`TypeValue`](#juliacall.TypeValue)
@@ -105,12 +104,7 @@ juliacall.IOValue - Class
 
 This wraps any Julia `IO` value. It is a subclass of `io.IOBase` and behaves like Python files.
 
-There are also subtypes `RawIOValue`, `BufferedIOValue` and `TextIOValue`, which are subclasses of `io.RawIOBase` (unbuffered bytes), `io.BufferedIOBase` (buffered bytes) and `io.TextIOBase` (text).
-
-###### Members
-- `torawio()`: Convert to a `RawIOValue`, an un-buffered bytes file-like object. (See also [`pyrawio`](@ref).)
-- `tobufferedio()`: Convert to a `BufferedIOValue`, an buffered bytes file-like object. Julia `IO` objects are converted to this by default. (See also [`pybufferedio`](@ref).)
-- `totextio()`: Convert to a `TextIOValue`, a text file-like object. (See also [`pytextio`](@ref).)
+There are also subtypes `BinaryIOValue` and `TextIOValue`, which are subclasses of `io.BufferedIOBase` (buffered bytes) and `io.TextIOBase` (text).
 `````
 
 `````@customdoc

docs/src/pythoncall.md

@@ -1,48 +1,42 @@
 # The Julia module `PythonCall`
 
-To get started, just do `using PythonCall`. There are two main ways to use this module:
-
-**Way 1:** There is a [collection of macros](#Execute-Python-code) for directly executing Python code, interpolating Julia values in and extracting Julia values out. For example ```@pyv `$x+1`::Int``` adds `x` to `1` in Python and converts the result to an `Int`.
-
-**Way 2:** There is a [collection of functions](#Python-functions) which typically produce and consume Python objects. The previous example can be implemented as `pyadd(Int, x, 1)` or `pyconvert(Int, PyObject(x)+1)`.
-
-In all cases, when a Julia value needs to be passed to Python, it will be converted according to [this table](@ref jl2py).
-
-When a Python value is returned to Julia, by default it will be as a [`PyObject`](@ref). Most functions provide an optional way to specify the return type, in which case it will be converted according to [this table](@ref py2jl).
-
-You can also specify one of the [wrapper types](@ref python-wrappers) as a return type.
-
-## `PyObject`
+## `Py`
 
 ```@docs
-PyObject
+Py
 ```
 
-## Execute Python code
+The object `pybuiltins` has all the standard Python builtin objects as its properties.
+Hence you can access `pybuiltins.None` and `pybuiltins.TypeError`.
 
-These macros are used to execute or evaluate Python code. The main differences between them are in whether/how any values are extracted out again.
-
-**Note to package writers.** These all expect there to be a variable `pyglobals` in scope, which is a Python dictionary giving the global scope. For convenience, this module exports such a variable so that these macros work in the REPL. However other packages should define their own global scope by defining `const pyglobals = PyDict()`.
+## `@py`
 
 ```@docs
 @py
-@pyv
-@pyg
-@pya
-@pyr
 ```
 
 ## Python functions
 
+Most of the functions in this section are essentially Python builtins with a `py` prefix.
+For example `pyint(x)` converts `x` to a Python `int` and is equivalent to `int(x)` in
+Python when `x` is a Python object.
+
+Notable exceptions are:
+- [`pyconvert`](@ref) to convert a Python object to a Julia object.
+- [`pyimport`](@ref) to import a Python module.
+- [`pyjl`](@ref) to directly wrap a Julia object as a Python object.
+- [`pyclass`](@ref) to construct a new class.
+- [`pywith`](@ref) to emulate the Python `with` statement.
+
 ### Construct Python objects
 
 These functions convert Julia values into Python objects of standard types.
 
 ```@docs
-pynone
 pybool
 pyint
 pyfloat
+pycomplex
 pystr
 pybytes
 pytuple
@@ -53,10 +47,10 @@ pyset
 pyfrozenset
 pydict
 pyslice
-pyellipsis
-pynotimplemented
+pyrange
 pymethod
 pytype
+pyclass
 ```
 
 ### Wrap Julia values
@@ -67,23 +61,26 @@ These functions wrap Julia values into Python objects, documented [here](@ref ju
 pyjl
 pyjlraw
 pyisjl
-pyjlgetvalue
+pyjlvalue
 pytextio
-pyrawio
-pybufferedio
+pybinaryio
 ```
 
 ### Python builtins
 
 ```@docs
 pyconvert
+@pyconvert
 pyimport
+pyimport_conda
 pywith
 pyis
 pyrepr
+pyascii
 pyhasattr
 pygetattr
 pysetattr
+pydelattr
 pydir
 pycall
 pylen
@@ -99,46 +96,51 @@ pyhash
 pyiter
 ```
 
-### Numbers
+### Numeric functions
 
 ```@docs
-pyeq
-pyne
-pyle
-pylt
-pyge
-pygt
+pyneg
+pypos
+pyabs
+pyinv
 pyadd
-pyiadd
 pysub
-pyisub
 pymul
-pyimul
 pymatmul
-pyimatmul
+pypow
 pyfloordiv
-pyifloordiv
 pytruediv
-pyitruediv
 pymod
-pyimod
 pydivmod
 pylshift
-pyilshift
 pyrshift
-pyirshift
 pyand
-pyiand
-pyor
-pyior
 pyxor
-pyixor
-pypow
+pyor
+pyiadd
+pyisub
+pyimul
+pyimatmul
 pyipow
-pyneg
-pypos
-pyabs
-pyinv
+pyifloordiv
+pyitruediv
+pyimod
+pyilshift
+pyirshift
+pyiand
+pyixor
+pyior
+```
+
+### Comparisons
+
+```@docs
+pyeq
+pyne
+pyle
+pylt
+pyge
+pygt
 ```
 
 ## [Wrapper types](@id python-wrappers)
@@ -149,13 +151,8 @@ PySet
 PyDict
 PyIterable
 PyArray
-PyBuffer
 PyIO
+PyTable
 PyPandasDataFrame
-PyCode
-@py_cmd
-@pyv_cmd
-PyInternedString
-@pystr_str
-PyException
+PyObjectArray
 ```

src/abstract/iter.jl

@@ -1,3 +1,8 @@
+"""
+    pyiter(x)
+
+Equivalent to `iter(x)` in Python.
+"""
 pyiter(x) = pynew(errcheck(@autopy x C.PyObject_GetIter(getptr(x_))))
 export pyiter