You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/conversion.md
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ This page documents the rules used to convert values between Julia and Python.
4
4
5
5
In both directions, the default behaviour is to allow conversion between immutable values. Mutable values will be "wrapped" so that mutations on the wrapper affect the original object.
6
6
7
-
## Julia to Python
7
+
## [Julia to Python](@id jl2py)
8
8
9
9
When a Julia object is converted to a Python one (e.g. by calling `PyObject`, by interpolating it into a `@py` command, or passing it as an argument to a Python function) the following rules are used by default.
10
10
@@ -33,11 +33,11 @@ The user can always explicitly choose a different conversion (e.g. by calling `p
33
33
|`Type`|`juliaaa.TypeValue`|
34
34
| Anything else |`juliaaa.AnyValue`|
35
35
36
-
The `juliaaa.*Value` types are all subtypes of `juliaaa.AnyValue`. They wrap a Julia value, providing access to Julia semantics: it can be called, indexed, and so on. Subtypes add additional Pythonic semantics. Read more [here](../juliapy/#Wrapper-types).
36
+
The `juliaaa.*Value` types are all subtypes of `juliaaa.AnyValue`. They wrap a Julia value, providing access to Julia semantics: it can be called, indexed, and so on. Subtypes add additional Pythonic semantics. Read more [here](@ref julia-wrappers).
37
37
38
38
This conversion policy is defined/implemented by `Python.C.PyObject_From` and `Python.C.PyJuliaValue_From`. Package authors can (carefully) overload these with additional rules for custom types.
39
39
40
-
## Python to Julia
40
+
## [Python to Julia](@id py2jl)
41
41
42
42
From Julia, one can convert Python objects to a desired type using `pyconvert(T, x)` for example, or ```@pyv `...`::T```.
Now you can do `jl.rand(jl.Bool, 5, 5)`, which is equivalent to `rand(Bool, 5, 5)` in Julia.
18
18
19
-
When a Python value is passed to Julia, then typically it will be converted according to [this table](../conversion/#Python-to-Julia) with `T=Any`. Sometimes a more specific type will be used, such as when assigning to an array whose element type is known.
19
+
When a Python value is passed to Julia, then typically it will be converted according to [this table](@ref py2jl) with `T=Any`. Sometimes a more specific type will be used, such as when assigning to an array whose element type is known.
20
20
21
-
When a Julia value is returned to Python, it will normally be converted according to [this table](../conversion/#Julia-to-Python).
21
+
When a Julia value is returned to Python, it will normally be converted according to [this table](@ref jl2py).
22
22
23
-
## Wrapper types
23
+
## [Wrapper types](@id julia-wrappers)
24
24
25
-
Apart from a few fundamental immutable types (see [here](../conversion/#Julia-to-Python)), all Julia values are by default converted into Python to some [`AnyValue`](#juliaaa.AnyValue) object, which wraps the original value. Some types are converted to a subclass of [`AnyValue`](#juliaaa.AnyValue) which provides additional Python semantics --- e.g. Julia vectors are interpreted as Python sequences.
25
+
Apart from a few fundamental immutable types (see [here](@ref jl2py)), all Julia values are by default converted into Python to some [`AnyValue`](#juliaaa.AnyValue) object, which wraps the original value. Some types are converted to a subclass of [`AnyValue`](#juliaaa.AnyValue) which provides additional Python semantics --- e.g. Julia vectors are interpreted as Python sequences.
26
26
27
27
There is also a [`RawValue`](#juliaaa.RawValue) object, which gives a stricter "Julia-only" interface, documented below. These types all inherit from `ValueBase`:
28
28
@@ -45,174 +45,129 @@ There is also a [`RawValue`](#juliaaa.RawValue) object, which gives a stricter "
<p>Calling, indexing, attribute access, etc. will convert the result to a Python object according to <a href="../conversion/#Julia-to-Python">this table</a>. This is typically a builtin Python type (for immutables) or a subtype of <code>AnyValue</code>.</p>
59
-
<p>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, <code>_b</code> at the end of an attribute is replaced with <code>!</code> and <code>_bb</code> is replaced with <code>!!</code>.</p>
60
-
<h6>Members</h6>
61
-
<ul>
62
-
<li><code>_jl_raw()</code>: Convert to a <a href="#juliaaa.RawValue"><code>RawValue</code></a></li>
63
-
<li><code>_jl_display()</code>: Display the object using Julia's display mechanism.</li>
64
-
<li><code>_jl_help()</code>: Display help for the object.</li>
<p>This wraps any Julia <code>Number</code> value. It is a subclass of <code>numbers.Number</code> and behaves similar to other Python numbers.</p>
77
-
<p>There are also subtypes <code>ComplexValue</code>, <code>RealValue</code>, <code>RationalValue</code>, <code>IntegerValue</code> which wrap values of the corresponding Julia types, and are subclasses of the corresponding <code>numbers</code> ABC.</p>
<p>This wraps any Julia <code>AbstractArray</code> value. It is a subclass of <code>collections.abc.Collection</code>.</p>
89
-
<p>It supports zero-up indexing, and can be indexed with integers or slices. Slicing returns a view of the original array.</p>
90
-
<p>There is also the subtype <code>VectorValue</code> which wraps any <code>AbstractVector</code>. It is a subclass of <code>collections.abc.Sequence</code> and behaves similar to a Python <code>list</code>.</p>
91
-
<p>If the array is strided and its eltype is supported (i.e. <code>Bool</code>, <code>IntXX</code>, <code>UIntXX</code>, <code>FloatXX</code>, <code>Complex{FloatXX}</code>, <code>Ptr{Cvoid}</code> or <code>Tuple</code> or <code>NamedTuple</code> of these) then it supports the buffer protocol and the numpy array interface. This means that <code>numpy.asarray(this)</code> will yield a view of the original array, so mutations are visible on the original.</p>
92
-
<p>Otherwise, the numpy <code>__array__</code> method is supported, and this returns an array of Python objects converted from the contents of the array. In this case, <code>numpy.asarray(this)</code> is a copy of the original array.</p>
93
-
<h6>Members</h6>
94
-
<ul>
95
-
<li><code>ndim</code>: The number of dimensions.</li>
96
-
<li><code>shape</code>: Tuple of lengths in each dimension.</li>
97
-
<li><code>copy()</code>: A copy of the array.</li>
98
-
<li><code>reshape(shape)</code>: A reshaped view of the array.</li>
<p>This wraps any Julia <code>AbstractDict</code> value. It is a subclass of <code>collections.abc.Mapping</code> and behaves similar to a Python <code>dict</code>.</p>
<p>This wraps any Julia <code>AbstractSet</code> value. It is a subclass of <code>collections.abc.Set</code> and behaves similar to a Python <code>set</code>.</p>
<p>This wraps any Julia <code>IO</code> value. It is a subclass of <code>io.IOBase</code> and behaves like Python files.</p>
133
-
<p>There are also subtypes <code>RawIOValue</code>, <code>BufferedIOValue</code> and <code>TextIOValue</code>, which are subclasses of <code>io.RawIOBase</code> (unbuffered bytes), <code>io.BufferedIOBase</code> (buffered bytes) and <code>io.TextIOBase</code> (text).</p>
134
-
<h6>Members</h6>
135
-
<ul>
136
-
<li><code>torawio()</code>: Convert to a <code>RawIOValue</code>, an un-buffered bytes file-like object. (See also <a href="../pythonjl/#Python.pyrawio"><code>pyrawio</code></a>.)
137
-
<li><code>tobufferedio()</code>: Convert to a <code>BufferedIOValue</code>, an buffered bytes file-like object. Julia <code>IO</code> objects are converted to this by default. (See also <a href="../pythonjl/#Python.pybufferedio"><code>pybufferedio</code></a>.)
138
-
<li><code>totextio()</code>: Convert to a <code>TextIOValue</code>, a text file-like object. (See also <a href="../pythonjl/#Python.pytextio"><code>pytextio</code></a>.)
<p>This wraps any Julia <code>Type</code> value.</p>
166
-
<p>It is the same as <a href="#juliaaa.AnyValue"><code>AnyValue</code></a> except that indexing is used to access Julia's "curly" syntax for specifying parametric types:</p>
<p>This is very similar to <a href="#juliaaa.AnyValue"><code>AnyValue</code></a> except that indexing, calling, etc. will always return a <code>RawValue</code>.</p>
183
-
<p>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.</p>
184
-
<h6>Members</h6>
185
-
<ul>
186
-
<li><code>_jl_any()</code>: Convert to a <a href="#juliaaa.AnyValue"><code>AnyValue</code></a> (or subclass). (See also <a href="../pythonjl/#Python.pyjl">pyjl</a>.)</li>
187
-
</ul>
188
-
</section>
189
-
</article>
48
+
`````@customdoc
49
+
juliaaa.AnyValue - Class
50
+
51
+
Wraps any Julia object, giving it some basic Python semantics. Subtypes provide extra semantics.
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`.
56
+
57
+
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 `!!`.
58
+
59
+
###### Members
60
+
- `_jl_raw()`: Convert to a [`RawValue`](#juliaaa.RawValue). (See also [`pyjlraw`](@ref).)
61
+
- `_jl_display()`: Display the object using Julia's display mechanism.
62
+
- `_jl_help()`: Display help for the object.
63
+
`````
64
+
65
+
`````@customdoc
66
+
juliaaa.NumberValue - Class
67
+
68
+
This wraps any Julia `Number` value. It is a subclass of `numbers.Number` and behaves similar to other Python numbers.
69
+
70
+
There are also subtypes `ComplexValue`, `RealValue`, `RationalValue`, `IntegerValue` which wrap values of the corresponding Julia types, and are subclasses of the corresponding `numbers` ABC.
71
+
`````
72
+
73
+
`````@customdoc
74
+
juliaaa.ArrayValue - Class
75
+
76
+
This wraps any Julia `AbstractArray` value. It is a subclass of `collections.abc.Collection`.
77
+
78
+
It supports zero-up indexing, and can be indexed with integers or slices. Slicing returns a view of the original array.
79
+
80
+
There is also the subtype `VectorValue` which wraps any `AbstractVector`. It is a subclass of `collections.abc.Sequence` and behaves similar to a Python `list`.
81
+
82
+
If the array is strided and its eltype is supported (i.e. `Bool`, `IntXX`, `UIntXX`, `FloatXX`, `Complex{FloatXX}`, `Ptr{Cvoid}` or `Tuple` or `NamedTuple` of these) then it supports the buffer protocol and the numpy array interface. This means that `numpy.asarray(this)` will yield a view of the original array, so mutations are visible on the original.
83
+
84
+
Otherwise, the numpy `__array__` method is supported, and this returns an array of Python objects converted from the contents of the array. In this case, `numpy.asarray(this)` is a copy of the original array.
85
+
86
+
###### Members
87
+
- `ndim`: The number of dimensions.
88
+
- `shape`: Tuple of lengths in each dimension.
89
+
- `copy()`: A copy of the array.
90
+
- `reshape(shape)`: A reshaped view of the array.
91
+
`````
92
+
93
+
`````@customdoc
94
+
juliaaa.DictValue - Class
95
+
This wraps any Julia `AbstractDict` value. It is a subclass of `collections.abc.Mapping` and behaves similar to a Python `dict`.
96
+
`````
97
+
98
+
`````@customdoc
99
+
juliaaa.SetValue - Class
100
+
This wraps any Julia `AbstractSet` value. It is a subclass of `collections.abc.Set` and behaves similar to a Python `set`.
101
+
`````
102
+
103
+
`````@customdoc
104
+
juliaaa.IOValue - Class
105
+
106
+
This wraps any Julia `IO` value. It is a subclass of `io.IOBase` and behaves like Python files.
107
+
108
+
There are also subtypes `RawIOValue`, `BufferedIOValue` and `TextIOValue`, which are subclasses of `io.RawIOBase` (unbuffered bytes), `io.BufferedIOBase` (buffered bytes) and `io.TextIOBase` (text).
109
+
110
+
###### Members
111
+
- `torawio()`: Convert to a `RawIOValue`, an un-buffered bytes file-like object. (See also [`pyrawio`](@ref).)
112
+
- `tobufferedio()`: Convert to a `BufferedIOValue`, an buffered bytes file-like object. Julia `IO` objects are converted to this by default. (See also [`pybufferedio`](@ref).)
113
+
- `totextio()`: Convert to a `TextIOValue`, a text file-like object. (See also [`pytextio`](@ref).)
114
+
`````
115
+
116
+
`````@customdoc
117
+
juliaaa.ModuleValue - Class
118
+
This wraps any Julia `Module` value.
119
+
120
+
It is the same as [`AnyValue`](#juliaaa.AnyValue) except for one additional convenience method:
121
+
- `seval([module=self], code)`: Evaluates the given code (a string) in the given module.
122
+
`````
123
+
124
+
`````@customdoc
125
+
juliaaa.TypeValue - Class
126
+
127
+
This wraps any Julia `Type` value.
128
+
129
+
It is the same as [`AnyValue`](#juliaaa.AnyValue) except that indexing is used to access Julia's "curly" syntax for specifying parametric types:
130
+
131
+
```python
132
+
from juliaaa import Main as jl
133
+
# equivalent to Vector{Int}() in Julia
134
+
jl.Vector[jl.Int]()
190
135
```
136
+
`````
137
+
138
+
`````@customdoc
139
+
juliaaa.RawValue - Class
140
+
141
+
Wraps any Julia value with a rigid interface suitable for generic programming.
This is very similar to [`AnyValue`](#juliaaa.AnyValue) except that indexing, calling, etc. will always return a `RawValue`.
146
+
147
+
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.
148
+
149
+
###### Members
150
+
- `_jl_any()`: Convert to a [`AnyValue`](#juliaaa.AnyValue) (or subclass). (See also [`pyjl`](@ref).)
0 commit comments