update changelog and docs

Author: Christopher Rowley

CHANGELOG.md

@@ -3,7 +3,9 @@
 ## Unreleased (v1)
 * The vast majority of these changes are breaking, see the [v1 Migration Guide](@ref) for how to upgrade.
 * Changes to core functionality:
-  * Comparisons like `==(::Py, ::Py)`, `<(::Py, ::Number)`, `isless(::Number, ::Py)` now return `Bool` instead of `Py`.
+  * Comparisons like `==`, `<` and `isless` between `Py`s now return `Bool` instead of `Py`.
+  * Removed comparisons between `Py` and `Number` (like `Py(3) < 5`).
+  * Removed arithmetic between `Py` and `Number` (like `Py(2) * 10`).
 * Changes to `PythonCall.GC` (now more like `Base.GC`):
   * `enable(true)` replaces `enable()`.
   * `enable(false)` replaces `disable()`.

docs/src/v1-migration-guide.md

@@ -4,18 +4,26 @@ Use this guide to help with migrating code from v0.9 to v1.
 
 ## Core functionality
 
-Comparisons (`==`, `<`, etc.) between Python objects `Py`, or between `Py` and `Number`,
+Comparisons (`==`, `<`, etc.) between Python objects `Py`,
 used to return `Py` but now return `Bool`. The old behaviour was a pun but broke the
 Base API behaviour of these functions. These comparisons will now raise an error if the
 underlying Python operation does not return `bool`.
 
 * Instead of `pytruth(Py(3) < Py(5))` use `Py(3) < Py(5)`.
 * Instead of `Py(3) < Py(5)` use `Py(Py(3) < Py(5))`.
-* Instead of `np.array([1,2,3]) < Py(3)` use `pylt(np.array([1,2,3]), Py(3))`. This is
+* Instead of `np.array([1,2,3]) < Py(3)` use `pylt(np.array([1,2,3]), 3)`. This is
   because comparisons on numpy arrays return arrays of `bool` rather than a single
   `bool`.
 * Instead of `pylt(Bool, Py(3), Py(5))` you can use `Py(3) < Py(5)`.
 
+Comparisons and arithmetic (`==`, `<`, `+`, `*`, etc.) between `Py` and `Number` have
+been removed. The old behaviour broke the PythonCall convention that the boundary
+between Python and Julia is explicit.
+
+* Instead of `Py(3) < 10` use `Py(3) < Py(10)` or `pylt(Py(3), 10)`.
+* Instead of `Py(5) * 6` use `Py(5) * Py(6)` or `pymul(Py(5), 6)`.
+* Instead of `np.array([1,2,3]) < 3` use `pylt(np.array([1,2,3]), 3)`.
+
 ## `PythonCall.GC`
 
 This submodule has been changed to closer mimic the `Base.GC` API.