-
Notifications
You must be signed in to change notification settings - Fork 15
/
documentation.conf
195 lines (162 loc) · 6.96 KB
/
documentation.conf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
extensionName = "py"
markdownTemplate = """
# NetLogo Python extension
This NetLogo extension allows you to run Python code from NetLogo. It works with both Python 2 and 3, and should work with almost all Python libraries.
{{> BUILDING.md }}
{{> USING.md }}
## Primitives
{{#primitives}}
{{> primTemplate}}
{{/primitives}}
"""
primTemplate = """
### `{{name}}`
```NetLogo
{{#examples}}
{{primitive.fullName}}{{#args}} {{name}}{{/args}}
{{/examples}}
```
{{{description}}}
"""
filesToIncludeInManual = [ "USING.md", "primitives" ]
primitives = [
{
name: setup,
type: command,
arguments: [ { name: python-executable, type: string } ],
description: """
Create the Python session that this extension will use to execute code. The session will be started with the given Python executable. This command *must* be run before running any other Python extension primitive. Running this command again will shutdown the current Python environment and start a new one.
The executable may be specified as a relative path, absolute path, or just the executable name if it is on your PATH.
Furthermore, this extension offers a few helper primitives for getting particular versions of Python in system
independent ways.
In general, unless working with a virtual environment or a specific system setup, you should do:
```NetLogo
py:setup py:python ; if your code works with either Python 2 or 3
py:setup py:python3 ; for Python 3
py:setup py:python2 ; for Python 2
```
`py:setup` may be invoked by directly referring to different Pythons as well. For instance:
```NetLogo
py:setup "python3" ; if `python3` is on your PATH
py:setup "python" ; if `python` is on your PATH
```
If you use virtualenv or Conda, simply specify the path of the Python executable in the environment you wish to use:
```NetLogo
py:setup "/path/to/myenv/bin/python"
```
The path may be relative or absolute. So, if you have a virtual environment in the same folder as your model, you can do:
```NetLogo
py:setup "myenv/bin/python"
```
"""
},
{
name: python,
type: reporter,
returns: string,
description: """
Reports either the path to the latest version of Python configured in the `python.properties` file or, if that is blank, looks for a Python executable on your system's PATH.
For Windows, there is an installation option for including Python on your PATH.
For MacOS and Linux, it will likely already be on your PATH.
The output of this reporter is meant to be used with `py:setup`, but you may also use it to see which Python installation this extension will use by default.
For example, on MacOS with Homebrew installed Python 3:
```NetLogo
observer> show py:python
observer: "/usr/local/bin/python3"
```
"""
},
{
name: python2,
type: reporter,
returns: string,
description: """
Reports either the path to Python 2 configured in the `python.properties` file or, if that is blank, looks for a Python 2 executable on your system's PATH.
For Windows, there is an installation option for including Python on your PATH.
For MacOS and Linux, it will likely already be on your PATH.
The output of this reporter is meant to be used with `py:setup`, but you may also use it to see which Python 2 installation this extension will use by default.
For example, on MacOS with Homebrew installed Python 2:
```NetLogo
observer> show py:python2
observer: "/usr/local/bin/python2"
```
"""
},
{
name: python3,
type: reporter,
returns: string,
description: """
Reports either the path to Python 3 configured in the `python.properties` file or, if that is blank, looks for a Python 3 executable on your system's PATH.
For Windows, there is an installation option for including Python on your PATH.
For MacOS and Linux, it will likely already be on your PATH.
The output of this reporter is meant to be used with `py:setup`, but you may also use it to see which Python 3 installation this extension will use by default.
For example, on MacOS with Homebrew installed Python 3:
```NetLogo
observer> show py:python3
observer: "/usr/local/bin/python3"
```
"""
},
{
name: run,
type: command,
arguments: [ {name: python-statement, type: "repeatable string"}],
description: """
Runs the given Python statements in the current Python session. To make multi-line Python code easier to run, this command will take multiple strings, each of which will be interpreted as a separate line of Python code. For instance:
```NetLogo
(py:run
"import matplotlib"
"matplotlib.use('TkAgg')"
"import numpy as np"
"import matplotlib.pyplot as plt"
"for i in range(10):"
" plt.plot([ x ** i for x in np.arange(-1, 1, 0.1) ])"
"plt.show()"
)
```
`py:run` will wait for the statements to finish running before continuing. Thus, if you have long running Python code, NetLogo will pause while it runs.
"""
},
{
name: runresult,
type: reporter,
arguments: [ {name: "python-expression", type: "repeatable string"} ],
returns: anything,
description: """
Evaluates the given Python expression and reports the result.
`py:runresult` attempts to convert from Python data types to NetLogo data types.
Numbers, strings, and booleans convert as you would expect.
Any list-like object in Python (that is, anything with a length that you can iterate through) will be converted to a NetLogo list.
For instance, Python lists and NumPy arrays will convert to NetLogo lists.
Python dicts (and dict-like objects) will convert to a NetLogo list of key-value pairs (where each pair is represented as a list).
`None` will be converted to `nobody`.
Other objects will simply be converted to a string representation.
Note that due a [current issue](https://github.com/qiemem/PythonExtension/issues/6), dict keys will always be reported as strings.
If you need to report non-string keys, report the `.items()` of the dict instead of the dict itself.
"""
},
{
name: set,
type: command,
arguments: [ {name: "variable-name", type: "string"}, {name: "value", type: "anything"} ],
description: """
Sets a variable in the Python session with the given name to the given NetLogo value. NetLogo objects will be converted to Python objects as expected.
All vanilla NetLogo objects are supported, but objects from other extensions, even other bundled extensions, are not supported.
```NetLogo
py:set "x" [1 2 3]
show py:runresult "x" ;; Shows [1 2 3]
```
Agents are converted into dictionaries with elements for each agent variable. Agentsets are converted into lists of agent dictionaries.
```NetLogo
breed [goats goat]
goats-own [energy ]
create-goats 1 [ set heading 0 set color 75 ]
ask goat 0 [ set energy 42 ]
py:set "goat" goat 0
py:runresult "str(goat)" ;; Should output: "{'WHO': 0, 'COLOR': 75, 'HEADING': 0, 'XCOR': 0, 'YCOR': 0, 'SHAPE': 'default', 'LABEL': '', 'LABEL-COLOR': 9.9, 'BREED': 'GOATS', 'HIDDEN?': False, 'SIZE': 1, 'PEN-SIZE': 1, 'PEN-MODE': 'up', 'ENERGY': 42}"
```
Agents with variables containing references to agentsets will have those variables converted into the string representation of that agentset.
"""
}
]