rename ispynull to pyisnull

Author: Christopher Doris

src/Py.jl

@@ -1,10 +1,29 @@
 incref(x::C.PyPtr) = (C.Py_IncRef(x); x)
 decref(x::C.PyPtr) = (C.Py_DecRef(x); x)
 
+"""
+    ispy(x)
+
+True if `x` is a Python object.
+
+This includes `Py` and Python wrapper types such as `PyList`.
+"""
 ispy(x) = false
-ispynull(x) = getptr(x) == C.PyNULL
+export ispy
+
+"""
+    pyisnull(x)
+
+True if the Python object `x` is NULL.
+"""
+pyisnull(x) = getptr(x) == C.PyNULL
+
+"""
+    getptr(x)
+
+Get the underlying pointer from the Python object `x`.
+"""
 getptr(x) = getptr(getpy(x)::Py)
-export ispy, ispynull
 
 """
     Py(x)
@@ -33,6 +52,17 @@ setptr!(x::Py, ptr::C.PyPtr) = (setfield!(x, :ptr, ptr); x)
 
 const PYNULL_CACHE = Py[]
 
+"""
+    pynew([ptr])
+
+A new `Py` representing the Python object at `ptr` (NULL by default).
+
+If `ptr` is given and non-NULL, this function steals a reference to the Python object it
+points at, i.e. the new `Py` object owns a reference.
+
+Note that NULL Python objects are not safe in the sense that most API functions will probably
+crash your Julia session if you pass a NULL argument.
+"""
 pynew() =
     if isempty(PYNULL_CACHE)
         Py(Val(:new), C.PyNULL)
@@ -44,9 +74,37 @@ const PyNULL = pynew()
 
 pynew(ptr::C.PyPtr) = setptr!(pynew(), ptr)
 
-# assumes dst is NULL
+"""
+    pycopy!(dst::Py, src)
+
+Copy the Python object `src` into `dst`, so that they both represent the same object.
+
+This function exists to support module-level constant Python objects. It is illegal to call
+most PythonCall API functions at the top level of a module (i.e. before `__init__()` has run)
+so you cannot do `const x = pything()` at the top level. Instead do `const x = pynew()` at
+the top level then `pycopy!(x, pything())` inside `__init__()`.
+
+Assumes `dst` is NULL, otherwise a memory leak will occur.
+"""
 pycopy!(dst, src) = setptr!(dst, incref(getptr(src)))
 
+"""
+    pydel!(x::Py)
+
+Delete the Python object `x`.
+
+DANGER! Use this function ONLY IF the Julia object `x` could have been garbage-collected
+anyway, i.e. was about to become unreachable. This means you MUST KNOW that no other part of
+the program has the Julia object `x`.
+
+This decrements the reference count, sets the pointer to NULL and appends `x` to a cache
+of unused objects (`PYNULL_CACHE`).
+
+This is an optimization to avoid excessive allocation and deallocation in Julia, which can
+be a significant source of slow-down in code which uses a lot of Python objects. It allows
+`pynew()` to pop an item from `PYNULL_CACHE` instead of allocating one, and avoids calling
+the relatively slow finalizer on `x`.
+"""
 function pydel!(x::Py)
     ptr = getptr(x)
     if ptr != C.PyNULL
@@ -61,8 +119,6 @@ function pystolen!(x::Py)
     nothing
 end
 
-export pynull, pynew, pydel!, pystolen!
-
 macro autopy(args...)
     vs = args[1:end-1]
     ts = [Symbol(v, "_") for v in vs]
@@ -94,7 +150,7 @@ Py(x::Time) = pytime(x)
 Py(x::DateTime) = pydatetime(x)
 Py(x) = ispy(x) ? Py(getpy(x)) : pyjl(x)
 
-Base.string(x::Py) = ispynull(x) ? "<py NULL>" : pystr(String, x)
+Base.string(x::Py) = pyisnull(x) ? "<py NULL>" : pystr(String, x)
 Base.print(io::IO, x::Py) = print(io, string(x))
 
 function Base.repr(x::Py)
@@ -124,7 +180,7 @@ end
 
 function Base.show(io::IO, mime::MIME"text/plain", o::Py)
     hasprefix = get(io, :typeinfo, Any) != Py
-    if ispynull(o)
+    if pyisnull(o)
         if hasprefix
             printstyled(io, "Python NULL", bold=true)
         else
@@ -261,7 +317,7 @@ Base.IteratorSize(::Type{Py}) = Base.SizeUnknown()
 
 function Base.iterate(x::Py, it::Py=pyiter(x))
     v = unsafe_pynext(it)
-    if ispynull(v)
+    if pyisnull(v)
         pydel!(it)
         nothing
     else

src/abstract/collection.jl

@@ -3,7 +3,7 @@
 function _pyconvert_rule_iterable(ans::Vector{T0}, it::Py, ::Type{T1}) where {T0,T1}
     @label again
     x_ = unsafe_pynext(it)
-    if ispynull(x_)
+    if pyisnull(x_)
         pydel!(it)
         return pyconvert_return(ans)
     end
@@ -29,7 +29,7 @@ end
 function _pyconvert_rule_iterable(ans::Set{T0}, it::Py, ::Type{T1}) where {T0,T1}
     @label again
     x_ = unsafe_pynext(it)
-    if ispynull(x_)
+    if pyisnull(x_)
         pydel!(it)
         return pyconvert_return(ans)
     end
@@ -55,7 +55,7 @@ end
 function _pyconvert_rule_mapping(ans::Dict{K0,V0}, x::Py, it::Py, ::Type{K1}, ::Type{V1}) where {K0,V0,K1,V1}
     @label again
     k_ = unsafe_pynext(it)
-    if ispynull(k_)
+    if pyisnull(k_)
         pydel!(it)
         return pyconvert_return(ans)
     end
@@ -128,22 +128,22 @@ end
 function pyconvert_rule_iterable(::Type{R}, x::Py, ::Type{Pair{K0,V0}}=Utils._type_lb(R), ::Type{Pair{K1,V1}}=Utils._type_ub(R)) where {R<:Pair,K0,V0,K1,V1}
     it = pyiter(x)
     k_ = unsafe_pynext(it)
-    if ispynull(k_)
+    if pyisnull(k_)
         pydel!(it)
         pydel!(k_)
         return pyconvert_unconverted()
     end
     k = @pyconvert_and_del(K1, k_)
     v_ = unsafe_pynext(it)
-    if ispynull(v_)
+    if pyisnull(v_)
         pydel!(it)
         pydel!(v_)
         return pyconvert_unconverted()
     end
     v = @pyconvert_and_del(V1, v_)
     z_ = unsafe_pynext(it)
     pydel!(it)
-    if ispynull(z_)
+    if pyisnull(z_)
         pydel!(z_)
     else
         pydel!(z_)

src/compat/serialization.jl

@@ -3,7 +3,7 @@
 # We use pickle to serialise Python objects to bytes.
 
 function serialize_py(s, x::Py)
-    if ispynull(x)
+    if pyisnull(x)
         serialize(s, nothing)
     else
         b = pyimport("pickle").dumps(x)

src/convert.jl

@@ -105,7 +105,7 @@ function pyconvert_get_rules(type::Type, pytype::Py)
                 xbase = base
             end
         end
-        if !ispynull(xbase)
+        if !pyisnull(xbase)
             push!(basetypes, xtype)
             xmro = collect(xtype.__mro__)
             pyisin(xbase, xmro) || pushfirst!(xmro, xbase)

src/err.jl

@@ -80,9 +80,9 @@ end
 function Base.getproperty(exc::PyException, k::Symbol)
     if k in (:t, :v, :b) && !exc._isnormalized
         errnormalize!(exc._t, exc._v, exc._b)
-        ispynull(exc._t) && setptr!(exc._t, incref(getptr(pybuiltins.None)))
-        ispynull(exc._v) && setptr!(exc._v, incref(getptr(pybuiltins.None)))
-        ispynull(exc._b) && setptr!(exc._b, incref(getptr(pybuiltins.None)))
+        pyisnull(exc._t) && setptr!(exc._t, incref(getptr(pybuiltins.None)))
+        pyisnull(exc._v) && setptr!(exc._v, incref(getptr(pybuiltins.None)))
+        pyisnull(exc._b) && setptr!(exc._b, incref(getptr(pybuiltins.None)))
         pyisnone(exc._v) || (exc._v.__traceback__ = exc._b)
         exc._isnormalized = true
     end
@@ -124,7 +124,7 @@ function Base.showerror(io::IO, e::PyException)
     end
 
     # if this is a Julia exception then recursively print it and its stacktrace
-    if !ispynull(pyJuliaError) && pyissubclass(e.t, pyJuliaError)
+    if !pyisnull(pyJuliaError) && pyissubclass(e.t, pyJuliaError)
         try
             # Extract error value
             je, jb = pyconvert(Tuple{Any,Any}, e.v.args)

src/jlwrap/array.jl

@@ -276,7 +276,7 @@ function pyjlarray_array_interface(x::AbstractArray{T,N}) where {T,N}
             d["data"] = data
             d["strides"] = strides(x) .* Base.aligned_sizeof(T)
             d["version"] = 3
-            if !ispynull(descr)
+            if !pyisnull(descr)
                 d["descr"] = descr
             end
             return d

src/jlwrap/base.jl

@@ -110,7 +110,7 @@ end
 function pyjl_handle_error(f, self, exc)
     @nospecialize f self exc
     t = pyjl_handle_error_type(f, self, exc)::Py
-    if ispynull(t)
+    if pyisnull(t)
         # NULL => raise JuliaError
         errset(pyJuliaError, pytuple((pyjlraw(exc), pyjlraw(catch_backtrace()))))
         return C.PyNULL

src/py_macro.jl

@@ -596,7 +596,7 @@ function py_macro_lower(st, body, ans, ex; flavour=:expr)
         py_macro_del(body, y, ty)
         body2 = []
         push!(body2, :($v = $unsafe_pynext($i)))
-        push!(body2, Expr(:if, :($ispynull($v)), Expr(:block, :($pydel!($v)), :(break))))
+        push!(body2, Expr(:if, :($pyisnull($v)), Expr(:block, :($pydel!($v)), :(break))))
         py_macro_lower_assign(st, body2, ax, v)
         py_macro_del(body2, v, true)
         tz = py_macro_lower(st, body2, z, az)

src/pyconst_macro.jl

@@ -19,6 +19,6 @@ macro pyconst(ex)
     else
         val = :($Py($val))
     end
-    :(ispynull($x) ? pycopy!($x, $val) : $x)
+    :(pyisnull($x) ? pycopy!($x, $val) : $x)
 end
 export @pyconst

src/pywrap/PyDict.jl

@@ -34,7 +34,7 @@ Base.length(x::PyDict) = Int(pylen(x))
 
 function Base.iterate(x::PyDict{K,V}, it::Py=pyiter(x)) where {K,V}
     k_ = unsafe_pynext(it)
-    ispynull(k_) && return nothing
+    pyisnull(k_) && return nothing
     v_ = pygetitem(x, k_)
     k = pyconvert_and_del(K, k_)
     v = pyconvert_and_del(V, v_)
@@ -43,7 +43,7 @@ end
 
 function Base.iterate(x::Base.KeySet{K,PyDict{K,V}}, it::Py=pyiter(x.dict)) where {K,V}
     k_ = unsafe_pynext(it)
-    ispynull(k_) && return nothing
+    pyisnull(k_) && return nothing
     k = pyconvert_and_del(K, k_)
     return (k, it)
 end