### Custom wrappers example

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

A minimal example of defining a custom wrapper type.

```APIDOC
### [Custom wrappers](@id python-wrappers-custom)

Here is a minimal example of defining a wrapper type. You may add methods, fields and a
supertype to the type to specialise its behaviour. See any of the above wrapper types for
examples.

```julia
# The new type with a field for the Python object being wrapped.
struct MyType
    py::Py
end

# Says that the object is a wrapper.
ispy(x::MyType) = true

# Says how to access the underlying Python object.
Py(x::MyType) = x.py
```
```

--------------------------------

### Install PythonCall.jl

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Install the PythonCall package using the Julia package manager.

```julia-repl
pkg> add PythonCall
```

--------------------------------

### Configure PythonCall with Preferences for Existing Python

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Use preferences to set the CondaPkg backend to Null and optionally specify the Python executable path for an existing Python installation.

```julia
pkg> preference add CondaPkg backend=Null
pkg> preference add PythonCall exe=/path/to/python  # optional
```

--------------------------------

### Install JuliaCall with pip

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Install the JuliaCall package using pip. This is the standard method for installing Python packages.

```bash
pip install juliacall
```

--------------------------------

### Example juliapkg.json for Julia Dependencies

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Define Julia version and package requirements in a juliapkg.json file to manage Julia dependencies for your project.

```json
{
    "julia": "1.5",
    "packages": {
        "Example": {
            "uuid": "7876af07-990d-54b4-ab0e-23690620f79a",
            "version": "0.5, 0.6"
        }
    }
}
```

--------------------------------

### Install JuliaCall with Conda

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Install the JuliaCall package using Conda from the conda-forge channel. This is an alternative installation method.

```bash
conda install conda-forge::pyjuliacall
```

--------------------------------

### Configure PythonCall to Use Existing Python Installation

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Set CondaPkg backend to Null and optionally specify the Python executable path to use an existing Python installation. This prevents CondaPkg from installing any packages.

```julia
ENV["JULIA_CONDAPKG_BACKEND"] = "Null"
ENV["JULIA_PYTHONCALL_EXE"] = "/path/to/python"  # optional
```

--------------------------------

### Get Help for Julia Object

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

The `_jl_help(mime=None)` method displays help information for a Julia object, similar to Julia's built-in help system.

```python
_jl_help(mime=None)
```

--------------------------------

### Configure PythonCall to Use Current Conda Environment

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Set CondaPkg backend to Current and optionally specify the Conda executable path to use the currently activated Conda environment. This will still install required Conda packages into the environment.

```julia
ENV["JULIA_CONDAPKG_BACKEND"] = "Current"
ENV["JULIA_CONDAPKG_EXE"] = "/path/to/conda"  # optional
```

--------------------------------

### Define a custom Python wrapper type

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Example of defining a custom Julia type that wraps a Python object, implementing `ispy` and `Py` methods for integration with PythonCall.

```julia
# The new type with a field for the Python object being wrapped.
struct MyType
    py::Py
end

# Says that the object is a wrapper.
ispy(x::MyType) = true

# Says how to access the underlying Python object.
Py(x::MyType) = x.py
```

--------------------------------

### Configure PythonCall to Use System Conda/Mamba/Pixi

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Set CondaPkg backend to System or SystemPixi and optionally specify the Conda executable path to use a preinstalled Conda, Mamba, MicroMamba, or Pixi implementation. This will create a new Conda environment.

```julia
ENV["JULIA_CONDAPKG_BACKEND"] = "System"  # or "SystemPixi" for Pixi
ENV["JULIA_CONDAPKG_EXE"] = "/path/to/conda"  # optional
```

--------------------------------

### Run Julia Tests

Source: https://github.com/juliapy/pythoncall.jl/blob/main/AGENTS.md

Execute Julia tests from the project root. Expect a warning about the General registry in locked-down environments, but the suite should still complete.

```bash
julia --project -e 'using Pkg; Pkg.test()'
```

--------------------------------

### Configure PythonCall with Preferences for System Conda/Mamba/Pixi

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Use preferences to set the CondaPkg backend to System or SystemPixi and optionally specify the Conda executable path for using a preinstalled Conda, Mamba, MicroMamba, or Pixi implementation.

```julia
pkg> preference add CondaPkg backend=System
pkg> preference add CondaPkg exe=/path/to/conda  # optional
```

--------------------------------

### Define and Initialize Flux Model

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/flux.ipynb

Sets up a neural network model using Flux.jl. This includes defining the layers, activation functions, and the loss function.

```python
jl.seval("using Flux")
model = jl.Chain(
    jl.Dense(1, 10, jl.relu),
    jl.Dense(10, 10, jl.relu),
    jl.Dense(10, 10, jl.relu),
    jl.Dense(10, 1),
)
loss = jl.seval("m -> (x, y) -> Flux.Losses.mse(m(x), y)")(model)
```

--------------------------------

### Import Python Module and Use Functions

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Import the 're' Python module and use its findall function. Strings are automatically converted to Python strings.

```julia-repl
julia> using PythonCall
julia> re = pyimport("re")
Python: <module 're' from '[...]/lib/re.py'>
julia> words = re.findall("[a-zA-Z]+", "PythonCall.jl is very useful!")
Python: ['PythonCall', 'jl', 'is', 'very', 'useful']
```

--------------------------------

### Reshape Julia Array

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Use the `reshape(shape)` method on an `ArrayValue` to get a reshaped view of the underlying Julia array without copying data.

```python
reshape(shape)
```

--------------------------------

### Configuring Julia Call Process via Environment Variables

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Set JuliaCall process configurations using environment variables. These variables offer an alternative to -X arguments for controlling the Julia runtime.

```text
PYTHON_JULIACALL_OPTLEVEL=3
```

```text
PYTHON_JULIACALL_CHECK_BOUNDS=yes
```

```text
PYTHON_JULIACALL_COMPILE=yes
```

```text
PYTHON_JULIACALL_COMPILED_MODULES=yes
```

```text
PYTHON_JULIACALL_DEPWARN=yes
```

```text
PYTHON_JULIACALL_HANDLE_SIGNALS=yes
```

```text
PYTHON_JULIACALL_INLINE=yes
```

```text
PYTHON_JULIACALL_MIN_OPTLEVEL=3
```

```text
PYTHON_JULIACALL_OPTIMIZE=3
```

```text
PYTHON_JULIACALL_PROCS=auto
```

```text
PYTHON_JULIACALL_STARTUP_FILE=yes
```

```text
PYTHON_JULIACALL_SYSIMAGE=<file>
```

```text
PYTHON_JULIACALL_THREADS=auto
```

```text
PYTHON_JULIACALL_WARN_OVERWRITE=yes
```

```text
PYTHON_JULIACALL_AUTOLOAD_IPYTHON_EXTENSION=yes
```

```text
PYTHON_JULIACALL_HEAP_SIZE_HINT=<N>
```

```text
PYTHON_JULIACALL_EXE=<file>
```

```text
PYTHON_JULIACALL_PROJECT=<dir>
```

```text
PYTHON_JULIACALL_LIB=<file>
```

```text
PYTHON_JULIACALL_TRACE_COMPILE=stderr
```

```text
PYTHON_JULIACALL_TRACE_COMPILE_TIMING=yes
```

--------------------------------

### Execute Julia code in IPython with Cell Magic

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/compat.md

Demonstrates using the `%%julia` cell magic in IPython to execute Julia code and synchronize variables between Julia and Python.

```python
x = 2

y = 8

%%julia x y z
 z = "$x^$y = $(x^y)";
   
```

--------------------------------

### Import Seaborn and Set Theme

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/seaborn.ipynb

Import the Seaborn library from Python and set its default theme for plots.

```python
sns = pyimport("seaborn")
sns.set_theme()
```

--------------------------------

### Py Objects

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Documentation for the core `Py` object and `pybuiltins`.

```APIDOC
## `Py` objects

```@docs
Py
pybuiltins
```
```

--------------------------------

### Call Julia Functions from Python

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Demonstrates calling Julia functions like println and rand from Python using the imported 'jl' object. Includes displaying Julia objects and using NumPy for calculations.

```python
jl.println("Hello from Julia!")
# Hello from Julia!
x = jl.rand(range(10), 3, 5)
x._jl_display()
# 3×5 Matrix{Int64}:
#  8  1  7  0  6
#  9  2  1  4  0
#  1  8  5  4  0
import numpy
numpy.sum(x, axis=0)
# array([18, 11, 13,  8,  6], dtype=int64)
```

--------------------------------

### Configuring Julia Call Process via -X Arguments

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Set JuliaCall process configurations using -X arguments passed to the Python interpreter. These options control various aspects of the Julia runtime.

```text
-X juliacall-optlevel=3
```

```text
-X juliacall-check-bounds=yes
```

```text
-X juliacall-compile=yes
```

```text
-X juliacall-compiled-modules=yes
```

```text
-X juliacall-depwarn=yes
```

```text
-X juliacall-handle-signals=yes
```

```text
-X juliacall-inline=yes
```

```text
-X juliacall-min-optlevel=3
```

```text
-X juliacall-optimize=3
```

```text
-X juliacall-procs=auto
```

```text
-X juliacall-startup-file=yes
```

```text
-X juliacall-sysimage=<file>
```

```text
-X juliacall-threads=auto
```

```text
-X juliacall-warn-overwrite=yes
```

```text
-X juliacall-autoload-ipython-extension=yes
```

```text
-X juliacall-heap-size-hint=<N>
```

```text
-X juliacall-exe=<file>
```

```text
-X juliacall-project=<dir>
```

```text
-X juliacall-lib=<file>
```

```text
-X juliacall-trace-compile=stderr
```

```text
-X juliacall-trace-compile-timing=yes
```

--------------------------------

### Python Object Interaction and Conversion

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Demonstrates creating Python lists, accessing elements by index, slicing, and performing arithmetic operations on Python objects.

```julia-repl
julia> x = pylist([3, 4, 5])
Python: [3, 4, 5]
julia> x[2] == 5
Python: True
julia> x[pyslice(0,2)] + pylist([1,2])
Python: [3, 4, 1, 2]
```

--------------------------------

### Configure PythonCall with Preferences for Current Conda Environment

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Use preferences to set the CondaPkg backend to Current and optionally specify the Conda executable path for using the current Conda environment.

```julia
pkg> preference add CondaPkg backend=Current
pkg> preference add CondaPkg exe=/path/to/conda  # optional
```

--------------------------------

### Create classes

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions to create new Python classes with Julia-implemented functions.

```APIDOC
## Create classes

These functions can be used to create new Python classes where the functions are implemented
in Julia. You can instead use [`@pyeval`](@ref) etc. to create pure-Python classes.

```@docs
pytype(::Any, ::Any, ::Any)
pyfunc
pyclassmethod
pystaticmethod
pyproperty
```
```

--------------------------------

### Benchmark Python dict creation

Source: https://github.com/juliapy/pythoncall.jl/blob/main/BENCHMARKS.md

This Python code defines a function to create a dictionary with 1000 string keys and float values, then times its execution.

```python-repl
>>> from timeit import timeit
>>> def test():
...     from random import random
...     x = {}
...     for i in range(1000):
...         x[str(i)] = i + random()
...     return x
...
>>> timeit("test()", N=1000, globals=globals())
```

--------------------------------

### juliacall.Main

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

The Julia `Main` module, accessible as a `ModuleValue`. This is the primary entry-point for interactive scripts.

```APIDOC
## Constant

juliacall.Main - Constant

The Julia `Main` module, as a [`ModuleValue`](#juliacall.ModuleValue).

In interactive scripts, you can use this as the main entry-point to JuliaCall:
```python
from juliacall import Main as jl
jl.println("Hello, world!")
```

In packages, use [`newmodule`](#juliacall.newmodule) instead.

The modules `Base`, `Core` and `PythonCall` are also available.
```

--------------------------------

### Import Python Libraries for JuliaCall

Source: https://github.com/juliapy/pythoncall.jl/blob/main/pytest/test_nb.ipynb

Import necessary libraries like numpy from Python and initialize Julia from Python. This sets up the environment for inter-language communication.

```python
# NBVAL_IGNORE_OUTPUT
import numpy as np
from juliacall import Main as jl
```

--------------------------------

### Benchmark PyCall dict creation (readable but wrong)

Source: https://github.com/juliapy/pythoncall.jl/blob/main/BENCHMARKS.md

This Julia code uses PyCall for dictionary creation, demonstrating a more readable but potentially incorrect approach that might lead to unexpected behavior.

```julia-repl
julia> using PyCall, BenchmarkTools

julia> function test()
           random = pyimport("random").random
           x = pybuiltin("dict")()
           str = pybuiltin("str")
           for i in pybuiltin("range")(1000)
               x[str(i)] = i + random()
           end
           return x
       end
test (generic function with 1 method)

julia> @benchmark test()
```

--------------------------------

### Enable Interactive Julia Async Code in Python REPL

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/compat.md

Allows Julia async code to run while the Python REPL prompt is showing, useful for interactive plots.

```python
juliacall.interactive()
```

--------------------------------

### Run Python Tests

Source: https://github.com/juliapy/pythoncall.jl/blob/main/AGENTS.md

Execute Python tests using pytest. Ensure the juliapkg.json file is copied before running. Coverage can be enabled by adding the --cov flag.

```bash
uv run pytest -s --nbval ./pytest
```

```bash
uv run pytest -s --nbval ./pytest --cov=pysrc
```

--------------------------------

### Execute Julia Code with %julia Magic

Source: https://github.com/juliapy/pythoncall.jl/blob/main/pytest/test_nb.ipynb

Use the `%julia` line magic command for single-line Julia execution within a Python cell. This provides a concise way to run simple Julia commands.

```julia
%julia println(x + 3)
```

--------------------------------

### Load juliacall IPython Extension

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/compat.md

Loads the juliacall IPython extension to enable enhanced integration between Julia and IPython.

```python
%load_ext juliacall
```

--------------------------------

### `@py` and `@pyconst`

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Macros for Python code evaluation and constant definition.

```APIDOC
## `@py` and `@pyconst`

```@docs
@py
@pyconst
```
```

--------------------------------

### Benchmark PythonCall dict creation with pydel!

Source: https://github.com/juliapy/pythoncall.jl/blob/main/BENCHMARKS.md

This Julia code demonstrates using PythonCall with `pydel!` to explicitly deallocate Python objects within the loop, aiming to reduce memory allocations.

```julia-repl
julia> using PythonCall, BenchmarkTools

julia> function test()
           random = pyimport("random").random
           x = pydict()
           for i in pyrange(1000)
               k = pystr(i)
               r = random()
               v = i + r
               x[k] = v
               pydel!(k)
               pydel!(r)
               pydel!(v)
               pydel!(i)
           end
           return x
       end
test (generic function with 1 method)

julia> @benchmark test()
```

--------------------------------

### Import Julia Main Module

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Import the Julia Main module as 'jl' for interactive or scripting use. This provides access to all of Julia's functionality.

```python
from juliacall import Main as jl
```

--------------------------------

### Import PythonCall and RDatasets

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/seaborn.ipynb

Import necessary Julia packages for Python integration and data handling.

```julia
using PythonCall, RDatasets
```

--------------------------------

### Load and Display Iris Dataset

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/seaborn.ipynb

Load the Iris dataset using RDatasets and display the first 5 rows.

```julia
df = dataset("datasets", "iris")
df[1:5, :]
```

--------------------------------

### Access Julia Main Module in Python

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Use the `Main` module as the primary entry point to JuliaCall in interactive scripts. For packages, use `newmodule` instead.

```python
from juliacall import Main as jl
jl.println("Hello, world!")
```

--------------------------------

### Benchmark PythonCall dict creation

Source: https://github.com/juliapy/pythoncall.jl/blob/main/BENCHMARKS.md

This Julia code uses PythonCall to replicate the Python dictionary creation benchmark, timing the execution of the `test` function.

```julia-repl
julia> using PythonCall, BenchmarkTools

julia> function test()
           random = pyimport("random").random
           x = pydict()
           for i in pyrange(1000)
               x[pystr(i)] = i + random()
           end
           return x
       end
test (generic function with 1 method)

julia> @benchmark test()
```

--------------------------------

### Benchmark PyCall dict creation

Source: https://github.com/juliapy/pythoncall.jl/blob/main/BENCHMARKS.md

This Julia code uses PyCall to benchmark dictionary creation, employing `pycall` for function calls and object instantiation.

```julia-repl
julia> using PyCall, BenchmarkTools

julia> function test()
           random = pyimport("random")."random"
           x = pycall(pybuiltin("dict"), PyObject)
           str = pybuiltin("str")
           for i in pycall(pybuiltin("range"), PyObject, 1000)
               set!(x, pycall(str, PyObject, i), i + pycall(random, PyObject))
           end
           return x
       end
test (generic function with 1 method)

julia> @benchmark test()
```

--------------------------------

### Visualize Model Predictions

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/flux.ipynb

Generates a plot comparing the ground truth data with the model's predictions. It also prints the final loss value.

```python
x, y = batch(400)
plt.scatter(x[0], y[0], label="truth")
yhat = model(x)
plt.plot(x[0], yhat[0,:], c="k", label="model")
plt.legend()
print("loss =", loss(x,y))
```

--------------------------------

### Pass Data and Return Named Outputs with @pyexec

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Demonstrates passing a named Julia variable (`num`) to Python and returning multiple named outputs, with type casting using `::`. This allows for complex data exchange between Julia and Python.

```julia-repl
julia> @pyexec (num=10) => """
           def add(a, b):
             return a + b

           def subtract(a, b):
               return a - b

           plusone = num + 1
           """ => (add, subtract, plusone::Float64)
(add = <py function add at 0x721b001a7cc0>, subtract = <py function subtract at 0x721b001a7d70>, plusone = 11.0)

julia> add(4, 3)
Python: 7

julia> subtract(4, 3)
Python: 1

julia> plusone
11.0
```

--------------------------------

### Julia Type with Parametric Specification

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Demonstrates how to specify Julia parametric types using Python's square bracket notation, mirroring Julia's curly syntax. This is useful for creating generic Julia types like vectors of specific element types.

```python
from juliacall import Main as jl
# equivalent to Vector{Int}() in Julia
jl.Vector[jl.Int]()
```

--------------------------------

### Add PythonCall Preference

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Use PreferenceTools to add a PythonCall preference for the Python executable path.

```julia
using PreferenceTools
# now press ] to enter the Pkg REPL
pkg> preference add PythonCall exe=/path/to/python
```

--------------------------------

### Using PyList to wrap Python lists

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

PyList wraps Python sequences as Julia vectors. Mutations to the PyList affect the original Python object.

```julia
julia> x = pylist([3,4,5])
Python: [3, 4, 5]

julia> y = PyList{Union{Int,Nothing}}(x)
3-element PyList{Union{Nothing, Int64}}:
 3
 4
 5

julia> push!(y, nothing)
4-element PyList{Union{Nothing, Int64}}:
 3
 4
 5
  nothing

julia> append!(y, 1:2)
6-element PyList{Union{Nothing, Int64}}:
 3
 4
 5
  nothing
 1
 2

julia> x
Python: [3, 4, 5, None, 1, 2]
```

--------------------------------

### Benchmark PythonCall dict creation with @py macro

Source: https://github.com/juliapy/pythoncall.jl/blob/main/BENCHMARKS.md

This Julia code utilizes the `@py` macro from PythonCall for a more concise way to write Python code within Julia, timing the execution.

```julia-repl
julia> using PythonCall, BenchmarkTools

julia> test() = @py begin
           import random: random
           x = {}
           for i in range(1000)
               x[str(i)] = i + random()
               # Uncomment for pydel! version:
               # @jl PythonCall.pydel!(i)
           end
           x
       end
test (generic function with 1 method)

julia> @benchmark test()
```

--------------------------------

### Low-level API

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Unsafe functions for low-level interaction with the Python interpreter.

```APIDOC
## Low-level API

The functions here are not exported. They are mostly unsafe in the sense that you can
crash Julia by using them incorrectly.

```@docs
PythonCall.pynew
PythonCall.pyisnull
PythonCall.pycopy!
PythonCall.getptr
PythonCall.pydel!
PythonCall.unsafe_pynext
```
```

--------------------------------

### Yield to Julia Scheduler from Python

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/compat.md

Allows asynchronous Julia code to run while Python is executing by periodically calling `jl.yield()` from Python.

```python
jl.yield()
```

--------------------------------

### Using PyIO to wrap Python file objects

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

PyIO views a Python file object as a Julia IO object, enabling standard Julia IO operations on Python files.

```julia
julia> x = pyimport("io").StringIO()
Python: <_io.StringIO object at 0x000000006579BC70>

julia> y = PyIO(x)
PyIO(<py _io.StringIO object at 0x000000006579BC70>, false, true, false, 4096, UInt8[], 4096, UInt8[])

julia> println(y, "Hello, world!")

julia> flush(y)

julia> x.seek(0)
Python: 0

julia> x.read()
Python: 'Hello, world!\n'
```

--------------------------------

### Create a New Julia Module

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Use `newmodule` to create a new Julia module with a specified name, typically used within Python packages.

```python
newmodule(name)
```

--------------------------------

### Parallel Python Sleep with GIL Locking

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Demonstrates calling Python's time.sleep in parallel across Julia threads. Requires unlocking the GIL before the loop and re-locking it within each thread's execution of Python code to prevent deadlocks and crashes.

```julia
PythonCall.GIL.@unlock Threads.@threads for i in 1:4
  PythonCall.GIL.@lock pyimport("time").sleep(5)
end
```

--------------------------------

### Logical Operations

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions equivalent to Python logical operators.

```APIDOC
## Logic

These functions are equivalent to the corresponding Python logical operators.

Note that the equivalent Julia operators are overloaded to call these when all arguments
are `Py` (or `Number`). Hence the following are equivalent: `Py(1) < Py(2)`, `Py(1) < 2`,
`pylt(1, 2)`, `pylt(Py(1), Py(2))`, etc.

Note that the binary operators by default return `Py` (not `Bool`) since comparisons in
Python do not necessarily return `bool`.

```@docs
pytruth
pynot
pyeq
pyne
pyle
pylt
pyge
pygt
```
```

--------------------------------

### Create a New Julia Module

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Create a new, isolated Julia module named 'SomeName' to avoid polluting the global Main namespace when using Julia in a package.

```python
import juliacall
jl = juliacall.newmodule("SomeName")
```

--------------------------------

### Multi-threading

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions supporting multi-threading of Python and/or Julia.

```APIDOC
## Multi-threading

These functions are not exported. They support multi-threading of Python and/or Julia.
See also [`juliacall.AnyValue._jl_call_nogil`](@ref julia-wrappers).

```@docs
PythonCall.GIL.lock
PythonCall.GIL.@lock
PythonCall.GIL.unlock
PythonCall.GIL.@unlock
PythonCall.GC.gc
```
```

--------------------------------

### Conversion to Julia

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions to convert Python values to Julia values.

```APIDOC
## Conversion to Julia

These functions convert Python values to Julia values, using the rules documented [here](@ref jl2py).

```@docs
pyconvert
@pyconvert
```
```

--------------------------------

### Add Python Packages with CondaPkg.jl

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Use CondaPkg.jl to add Python packages to your project. This creates a CondaPkg.toml file to manage dependencies.

```julia-repl
julia> using CondaPkg

julia> # press ] to enter the Pkg REPL

pkg> conda add some_package
```

--------------------------------

### juliacall.IOValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps any Julia IO value, behaving like Python files and subclassing io.IOBase. Subtypes BinaryIOValue and TextIOValue handle buffered bytes and text respectively.

```APIDOC
## Class: juliacall.IOValue

### Description
This wraps any Julia `IO` value. It is a subclass of `io.IOBase` and behaves like Python files.

There are also subtypes `BinaryIOValue` and `TextIOValue`, which are subclasses of `io.BufferedIOBase` (buffered bytes) and `io.TextIOBase` (text).

```

--------------------------------

### Display Julia Object Representation

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Use `_jl_display(mime=None)` to render a Julia object using Julia's display system, optionally specifying a MIME type.

```python
_jl_display(mime=None)
```

--------------------------------

### Builtins

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions that mimic Python builtin functions or keywords.

```APIDOC
## Builtins

These functions mimic the Python builtin functions or keywords of the same name.

```@docs
pyall
pyany
pyascii
pycall
pycallable
pycompile
pycontains
pydelattr
pydelitem
pydir
pyeval
@pyeval
pyexec
@pyexec
pygetattr
pygetitem
pyhasattr
pyhasitem
pyhash
pyhelp
pyimport
pyin
pyis
pyisinstance
pyissubclass
pyiter
pylen
pynext
pyprint
pyrepr
pysetattr
pysetitem
pytype(::Any)
pywith
```
```

--------------------------------

### Convert Julia String to Python String and Join

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Explicitly convert a Julia string to a Python string using Py() and call its join method.

```julia-repl
julia> sentence = Py(" ").join(words)
Python: 'PythonCall jl is very useful'
```

--------------------------------

### Convert Julia Table to Python Table

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/compat.md

Converts any Tables.jl-compatible table to a Python table using the `pytable` function.

```julia
pytable
```

--------------------------------

### Convert Python List to Julia Vector

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Demonstrates converting a Python list to different Julia Vector types using `pyconvert`. Shows conversion to a default `Vector{Float64}`, a specific `Vector{Float32}`, and a no-copy wrapper `PyList{Py}`.

```julia-repl
julia> x = pylist([3.4, 5.6])
Python: [3.4, 5.6]

julia> pyconvert(Vector, x)
2-element Vector{Float64}:
 3.4
 5.6

julia> pyconvert(Vector{Float32}, x)
2-element Vector{Float32}:
 3.4
 5.6

julia> pyconvert(Any, x)
2-element PyList{Any}:
 3.4
 5.6
```

--------------------------------

### Constructors

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions to construct Python objects of builtin types from Julia values.

```APIDOC
## Constructors

These functions construct Python objects of builtin types from Julia values.

```@docs
pybool
pycollist
pybytes
pycomplex
pydict
pyfloat
pyfrozenset
pyint
pylist
pyrange
pyrowlist
pyset
pyslice
pystr
pytuple
```
```

--------------------------------

### Import Libraries for Python and Julia

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/flux.ipynb

Imports necessary libraries from NumPy, Matplotlib, and JuliaCall for seamless integration.

```python
import numpy as np, matplotlib.pyplot as plt
from juliacall import Main as jl, convert as jlconvert
```

--------------------------------

### Train Flux Model

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/flux.ipynb

Trains the initialized Flux model using the ADAM optimizer. It uses synthetic data generated by the `batch` function and iterates through the training process.

```python
jl.Flux.train_b(
    loss,
    jl.Flux.params(model),
    jlconvert(jl.Vector[jl.Tuple], [batch(100) for _ in range(2000)]),
    jl.ADAM(0.01),
)
```

--------------------------------

### Fix Qt Plugin Path

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/compat.md

Applies a fix for the Qt plugin path, which can resolve issues with Qt-based Python applications when used with PythonCall.jl.

```julia
PythonCall.fix_qt_plugin_path
```

--------------------------------

### Execute Julia Code in Python Cell

Source: https://github.com/juliapy/pythoncall.jl/blob/main/pytest/test_nb.ipynb

Use the `%%julia` magic command to execute Julia code directly within a Python cell. This is useful for running Julia-specific logic.

```julia
%%julia

# Automatically activates Julia magic

x = 1
println(x + 2)
```

--------------------------------

### juliacall.AnyValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps any Julia object, providing basic Python semantics. Subclasses offer enhanced functionality for specific Julia types.

```APIDOC
## Class

juliacall.AnyValue - Class

Wraps any Julia object, giving it some basic Python semantics. Subtypes provide extra
semantics.

Supports `repr(x)`, `str(x)`, attributes (`x.attr`), calling (`x(a,b)`), iteration,
comparisons, `len(x)`, `a in x`, `dir(x)`.

Calling, indexing, attribute access, etc. will convert the result to a Python object
according to [this table](@ref jl2py). This is typically a builtin Python type (for
immutables) or a subtype of `AnyValue`.

Attribute access can be used to access Julia properties as well as normal class members. In
the case of a name clash, the class member will take precedence. For convenience with Julia
naming conventions, `_b` at the end of an attribute is replaced with `!` and `_bb` is
replaced with `!!`.

###### Members
- `_jl_raw()`: Convert to a [`RawValue`](#juliacall.RawValue). (See also [`pyjlraw`](@ref).)
- `_jl_display(mime=None)`: Display the object using Julia's display mechanism.
- `_jl_help(mime=None)`: Display help for the object.
- `_jl_call_nogil(*args, **kwargs)`: Call this with the GIL disabled.
```

--------------------------------

### Avoid Python Interaction During Module Precompilation

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Do not interact with Python during module precompilation. Instead, import Python modules when the module is loaded or perform imports dynamically.

```julia
module MyModule
  using PythonCall
  const foo = pyimport("foo")
  bar() = foo.bar() # will crash when called
end
```

```julia
module MyModule
  using PythonCall
  const foo = Ref{Py}()
  function __init__()
    foo[] = pyimport("foo")
  end
  bar() = foo[].bar()
end
```

```julia
module MyModule
  using PythonCall
  bar() = pyimport("foo").bar()
end
```

```julia
module MyModule
  using PythonCall
  bar() = @pyconst(pyimport("foo")).bar()
end
```

```julia
module MyModule
  using PythonCall
  bar() = @pyconst(pyimport("foo").bar)()
end
```

--------------------------------

### Define and Use a Python Function with @pyexec

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Use the @pyexec macro to define a Python function and make it accessible in Julia. The `global` keyword is necessary for packages like `re` to be accessible in the global scope. The `=>` syntax creates a Julia function that calls the Python function.

```julia-repl
julia> @pyexec """
           global re
           import re

           def my_sentence(s):
               words = re.findall("[a-zA-Z]+", s)
               sentence = " ".join(words)
               return sentence
           """ => my_sentence
Python: <function my_sentence at 0x7d83bb1b01a0>

julia> sentence = my_sentence("PythonCall.jl is very useful!")
Python: 'PythonCall jl is very useful'
```

--------------------------------

### Arithmetic Operations

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions equivalent to Python arithmetic operators.

```APIDOC
## Arithmetic

These functions are equivalent to the corresponding Python arithmetic operators.

Note that the equivalent Julia operators are overloaded to call these when all arguments
are `Py` (or `Number`). Hence the following are equivalent: `Py(1)+Py(2)`, `Py(1)+2`,
`pyadd(1, 2)`, `pyadd(Py(1), Py(2))`, etc.

```@docs
pyneg
pypos
pyabs
pyinv
pyindex
pyadd
pysub
pymul
pymatmul
pypow
pyfloordiv
pytruediv
pymod
pydivmod
pylshift
pyrshift
pyand
pyxor
pyor
pyiadd
pyisub
pyimul
pyimatmul
pyipow
pyifloordiv
pyitruediv
pyimod
pyilshift
pyirshift
pyiand
pyixor
pyior
```
```

--------------------------------

### Accessing Python Builtins

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Access Python built-in constants and functions like None, True, and ValueError through the pybuiltins object.

```julia-repl
julia> pybuiltins.None
Python: None
julia> pybuiltins.True
Python: True
julia> pybuiltins.ValueError("some error")
Python: ValueError('some error')
```

--------------------------------

### juliacall.newmodule

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Creates a new Julia module with the specified name. Recommended for use within Python packages.

```APIDOC
## Function

juliacall.newmodule - Function

```python
newmodule(name)
```

A new module with the given name.
```

--------------------------------

### Evaluate Julia Code with seval

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Use the 'seval' method to evaluate a Julia code string within a specific module, commonly used for importing Julia modules like Statistics.

```python
from array import array
jl.seval("using Statistics")
x = array('i', [1, 2, 3])
jl.mean(x)
# 2.0
y = array('i', [2,4,8])
jl.cor(x, y)
# 0.9819805060619657
```

--------------------------------

### Using PyArray for Python array views

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

PyArray provides a Julia array view for Python objects supporting the buffer protocol or NumPy array interface. Indexing and operations are efficient.

```julia
julia> x = pyimport("array").array("i", [3, 4, 5])
Python: array('i', [3, 4, 5])

julia> y = PyArray(x)
3-element PyArray{Int32, 1, true, true, Int32}:
 3
 4
 5

julia> sum(y)
12

julia> y[1] = 0
0

julia> x
Python: array('i', [0, 4, 5])
```

--------------------------------

### Generate Synthetic Data

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/flux.ipynb

Creates synthetic data for training and testing a model. This function generates sorted random x values and corresponding y values with added noise.

```python
def batch(n):
    x = np.sort(np.random.uniform(-1, 1, (1,n)))
    y = np.sin(x*10) + np.random.normal(0, 0.1, (1,n))
    return x, y
```

--------------------------------

### The Python interpreter

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions providing information about the Python interpreter being used.

```APIDOC
## The Python interpreter

These functions are not exported. They give information about which Python interpreter is
being used.
```@docs
PythonCall.python_version
PythonCall.python_executable_path
PythonCall.python_library_path
PythonCall.python_library_handle
```
```

--------------------------------

### Wrapper types

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Types that wrap a Python object, giving it Julia object semantics.

```APIDOC
## [Wrapper types](@id python-wrappers)

The following types wrap a Python object, giving it the semantics of a Julia object. For example `PyList(x)` interprets the Python sequence `x` as a Julia abstract vector.

Apart from a few fundamental immutable types, conversion from Python to Julia `Any` will return a wrapper type such as one of these, or simply `Py` if no wrapper type is suitable.

```@docs
PyList
PySet
PyDict
PyIterable
PyArray
PyIO
PyTable
PyPandasDataFrame
PyObjectArray
PyException
```
```

--------------------------------

### Enable Event Loop for Python GUIs

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/compat.md

Enables the Julia event loop to allow Python GUIs, such as Matplotlib in interactive mode, to function correctly.

```julia
PythonCall.event_loop_on
```

--------------------------------

### Handling Julia's Task Scheduler with Yielding Functions

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

When calling Julia functions that yield to the task scheduler (like `sleep`), periodically yield back to Julia's scheduler to prevent hangs. This pattern ensures that Julia can manage its tasks while waiting for Python threads to complete.

```python
jl_yield = getattr(jl, "yield")
while True:
  # yield to Julia's task scheduler
  jl_yield()
  # wait for up to 0.1 seconds for the threads to finish
  state = wait(fs, timeout=0.1)
  # if they finished then stop otherwise try again
  if not state.not_done:
    break
```

--------------------------------

### Copy Julia Array

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

The `copy()` method on an `ArrayValue` creates a distinct copy of the Julia array in Python.

```python
copy()
```

--------------------------------

### Add Python Package with CondaPkg.jl

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/faq.md

Use CondaPkg.jl to add Python packages before importing PythonCall.jl to ensure they are available in your Julia environment.

```julia
using CondaPkg

CondaPkg.add("numpy")

using PythonCall

np = pyimport("numpy")
```

--------------------------------

### juliacall.DictValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps any Julia AbstractDict value, behaving like a Python dict and subclassing collections.abc.MutableMapping.

```APIDOC
## Class: juliacall.DictValue

### Description
This wraps any Julia `AbstractDict` value. It is a subclass of `collections.abc.MutableMapping` and behaves similar to a Python `dict`.

```

--------------------------------

### juliacall.RawValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps any Julia value with a rigid interface, similar to AnyValue but always returning RawValue for operations like indexing and calling.

```APIDOC
## Class: juliacall.RawValue

### Description
Wraps any Julia value with a rigid interface suitable for generic programming.

Supports `repr(x)`, `str(x)`, attributes (`x.attr`), calling (`x(a,b)`), `len(x)`, `dir(x)`.

This is very similar to [`AnyValue`](#juliacall.AnyValue) except that indexing, calling, etc. will always return a `RawValue`.

Indexing with a tuple corresponds to indexing in Julia with multiple values. To index with a single tuple, it will need to be wrapped in another tuple.

###### Members
- `_jl_any()`: Convert to a [`AnyValue`](#juliacall.AnyValue) (or subclass). (See also [`pyjl`](@ref).)
- `_jl_call_nogil(*args, **kwargs)`: Call this with the GIL disabled.

```

--------------------------------

### Parallel Python Execution with Unlocked GIL

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall.md

Execute Julia functions in parallel threads from Python, unlocking the GIL for true concurrency. This is useful for CPU-bound tasks that do not interact with Python.

```python
from concurrent.futures import ThreadPoolExecutor, wait
from juliacall import Main as jl
pool = ThreadPoolExecutor(4)
fs = [pool.submit(jl.Libc.systemsleep._jl_call_nogil, 5) for _ in range(4)]
wait(fs)
```

--------------------------------

### Wrap Julia values

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall-reference.md

Functions to explicitly wrap Julia values into Python objects.

```APIDOC
## Wrap Julia values

These functions explicitly wrap Julia values into Python objects, documented [here](@ref julia-wrappers).

As documented [here](@ref py2jl), Julia values are wrapped like this automatically on
conversion to Python, unless the value is immutable and has a corresponding Python type.

```@docs
pyjl
pyjlraw
pyisjl
pyjlvalue
pybinaryio
pytextio
```
```

--------------------------------

### Create Seaborn Pairplot

Source: https://github.com/juliapy/pythoncall.jl/blob/main/examples/seaborn.ipynb

Generate a Seaborn pairplot from a Julia DataFrame converted to a Python Pandas DataFrame. The plot is colored by the 'Species' column.

```python
sns.pairplot(data=pypandasdataframe(df), hue="Species")
```

--------------------------------

### juliacall.ModuleValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps any Julia Module value, providing an additional method `seval` for evaluating code within a specified module.

```APIDOC
## Class: juliacall.ModuleValue

### Description
This wraps any Julia `Module` value.

It is the same as [`AnyValue`](#juliacall.AnyValue) except for one additional convenience method:
- `seval([module=self], code)`: Evaluates the given code (a string) in the given module.

```

--------------------------------

### Convert Python String to Julia String

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/pythoncall.md

Convert a Python string object back to a Julia string using pyconvert.

```julia-repl
julia> pyconvert(String, sentence)
"PythonCall jl is very useful"
```

--------------------------------

### Access Raw Julia Value

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

The `_jl_raw()` method on an `AnyValue` object converts it to a `RawValue`, providing a stricter Julia-only interface.

```python
_jl_raw()
```

--------------------------------

### juliacall.NumberValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps Julia `Number` values, behaving like Python numbers. Includes specialized subclasses for complex, real, rational, and integer types.

```APIDOC
## Class

juliacall.NumberValue - Class

This wraps any Julia `Number` value. It is a subclass of `numbers.Number` and behaves
similar to other Python numbers.

There are also subtypes `ComplexValue`, `RealValue`, `RationalValue`, `IntegerValue` which
wrap values of the corresponding Julia types, and are subclasses of the corresponding
`numbers` ABC.
```

--------------------------------

### Call Julia Function from Python

Source: https://github.com/juliapy/pythoncall.jl/blob/main/pytest/test_nb.ipynb

Call a Julia function (e.g., `cos`) directly from Python using the `jl` object. This allows seamless integration of Julia's mathematical capabilities.

```python
jl.cos(0)
```

--------------------------------

### juliacall.TypeValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps any Julia Type value, enabling parametric type specification using Python's square bracket syntax and supporting conversion to numpy dtypes.

```APIDOC
## Class: juliacall.TypeValue

### Description
This wraps any Julia `Type` value.

It is the same as [`AnyValue`](#juliacall.AnyValue) except that indexing is used to access Julia's "curly" syntax for specifying parametric types:

```python
from juliacall import Main as jl
# equivalent to Vector{Int}() in Julia
jl.Vector[jl.Int]()
```

Some Julia types can be converted to corresponding numpy dtypes like `numpy.dtype(jl.Int)`. Supports `Bool`, `IntXX`, `UIntXX`, `FloatXX`, `ComplexFXX`,
`NumpyDates.InlineDateTime64{unit}` and `NumpyDates.InlineTimeDelta64{unit}`, plus `Tuple`s and `NamedTuple`s of these.

```

--------------------------------

### Register Custom Conversion Rule

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/conversion-to-julia.md

Use `pyconvert_add_rule` to register a custom function for converting Python objects to Julia. This should be called within your module's `__init__` function.

```julia
PythonCall.pyconvert_add_rule
```

--------------------------------

### juliacall.SetValue

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Wraps any Julia AbstractSet value, behaving like a Python set and subclassing collections.abc.MutableSet.

```APIDOC
## Class: juliacall.SetValue

### Description
This wraps any Julia `AbstractSet` value. It is a subclass of `collections.abc.MutableSet` and behaves similar to a Python `set`.

```

--------------------------------

### Call Julia Function with GIL Disabled

Source: https://github.com/juliapy/pythoncall.jl/blob/main/docs/src/juliacall-reference.md

Use `_jl_call_nogil(*args, **kwargs)` to execute a Julia function call without holding the Python Global Interpreter Lock (GIL).

```python
_jl_call_nogil(*args, **kwargs)
```