Fix #1141 - Help about Managing Data between Python and Nelson (#1150)

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## 1.4.0 (UNRELEASED)
 
+### Added
+
+- [#1141](http://github.com/nelson-lang/nelson/issues/1141) Help about Managing Data between Python and Nelson.
+
 ### Changed
 
 - [#1142](http://github.com/nelson-lang/nelson/issues/1142) Github Actions updated.

modules/python_engine/help/en_US/xml/1_The_power_of_Python.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xmldoc>
+  <copyright>SAME AS NELSON SOFTWARE</copyright>
+
+  <language>en_US</language>
+  <keyword>The power of calling Python from Nelson</keyword>
+
+  <description>
+    <p
+    >Python is a dominant force in various fields, including machine learning, data science, and general programming.</p>
+    <p
+    >Its extensive libraries, such as NumPy, SciPy and Pandas, provide an arsenal of tools for scientific computing and data manipulation.</p>
+    <p
+    >Combining the strengths of Nelson’s digital capabilities with Python’s vast ecosystem opens up a world of possibilities.</p>
+    <p />
+    <p>Why call Python from Nelson?</p>
+    <p
+    >- Access to a rich ecosystem: Python has a vast collection of libraries for various tasks, from advanced statistical analysis to machine learning and beyond.</p>
+    <p
+    >By calling Python from Nelson, users can access this rich ecosystem without sacrificing Nelson's core functionality.</p>
+    <p
+    >- Seamless integration: Nelson's ability to call external functions allows for seamless integration with Python.</p>
+    <p
+    >This means Nelson users can leverage Python capabilities within their familiar Nelson environment, improving productivity and workflow efficiency.</p>
+    <p />
+    <p
+    >- Specialized Libraries: Although Nelson offers a wide range of built-in functions, there are some niche tasks that Python libraries excel at.</p>
+    <p
+    >For example, deep learning tasks can be handled efficiently using Python libraries such as TensorFlow or PyTorch, seamlessly integrated into Nelson workflows.</p>
+    <p />
+    <p
+    >- Rapid prototyping and development: Python is often preferred for rapid prototyping and development due to its concise syntax and extensive library support.</p>
+    <p
+    >By leveraging Python from Nelson, users can leverage Python's rapid prototyping capabilities while maintaining Nelson's digital computing environment for production-level work.</p>
+    <p />
+    <p
+    >- Community Collaboration: By integrating Python into Nelson workflows, users can leverage the collective wisdom of both communities, fostering collaboration and innovation.</p>
+    <p />
+    <p
+    >In conclusion, calling Python from Nelson offers a powerful synergy that combines the strengths of both platforms.</p>
+    <p
+    >Whether accessing specialized libraries, prototyping algorithms, or fostering collaboration, integrating Python into Nelson workflows can improve productivity and open up new possibilities for scientific computing and data analysis.</p>
+  </description>
+
+  <see_also>
+    <see_also_item>
+      <link linkend="${python_engine}pyrun">pyrun</link>
+    </see_also_item>
+    <see_also_item>
+      <link linkend="${python_engine}pyenv">pyenv</link>
+    </see_also_item>
+  </see_also>
+</xmldoc>

modules/python_engine/help/en_US/xml/python_types.xml

@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xmldoc>
+  <copyright>SAME AS NELSON SOFTWARE</copyright>
+
+  <language>en_US</language>
+  <keyword>Python Nelson types</keyword>
+  <short_description
+  >Managing Data between Python and Nelson.</short_description>
+
+  <description>
+    <p><b>Managing data returned by Python functions:</b></p>
+    <table style="width:100%">
+    <tr>
+        <th>Python return type, as shown in Python</th>
+        <th>Corresponding Nelson type (scalar)</th>
+    </tr>
+    <tr>
+        <td>bool</td><td>logical</td>
+    </tr>
+    <tr>
+        <td>complex</td><td>double (complex)</td>
+    </tr>
+    <tr>
+        <td>float</td><td>double</td>
+    </tr>
+    </table>
+    <p />
+    <p><b>Convert Python types to Nelson type explicitly:</b></p>
+    <p />
+    <table style="width:100%">
+    <tr>
+        <th>Python return types or protocols shown in Nelson</th>
+        <th>Nelson conversion methods</th>
+    </tr>
+    <tr>
+        <td>py.str</td><td>char, string</td>
+    </tr>
+    <tr>
+        <td>py.int</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64</td>
+    </tr>
+    <tr>
+        <td>py.long</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64</td>
+    </tr>
+    <tr>
+        <td>py.float</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64</td>
+    </tr>
+    <tr>
+        <td>py.bool</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64, logical</td>
+    </tr>
+    <tr>
+        <td>py.bytes</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64, logical</td>
+    </tr>
+    <tr>
+        <td>py.array.array</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64</td>
+    </tr>
+    <tr>
+        <td>py.memoryview</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64</td>
+    </tr>
+    <tr>
+        <td>py.numpy.ndarray</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64</td>
+    </tr>
+    <tr>
+        <td>py.list</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64, logical, string, cell</td>
+    </tr>
+    <tr>
+        <td>py.tuple</td><td
+        >double, single, int8, uint8, int16, uint16, int32, uint32, int64, uint64, logical, string, cell</td>
+    </tr>
+    <tr>
+        <td>py.dict</td><td>struct</td>
+    </tr>
+    </table>
+
+    <p />
+    <p><b>Pass scalar Nelson type to Python:</b></p>
+    <p />
+    <table style="width:100%">
+    <tr>
+        <th>Nelson scalar input argument type</th>
+        <th>Python type</th>
+    </tr>
+        <tr><td>NaN</td><td>float("nan")</td></tr>
+    <tr><td>Inf</td><td>float("inf")</td></tr>
+    <tr><td>double (real)</td><td>py.float</td></tr>
+    <tr><td>single (real)</td><td>py.float</td></tr>
+    <tr><td>double (complex)</td><td>py.complex</td></tr>
+    <tr><td>single (complex)</td><td>py.complex</td></tr>
+    <tr><td>int8</td><td>py.int</td></tr>
+    <tr><td>uint8</td><td>py.int</td></tr>
+    <tr><td>int16</td><td>py.int</td></tr>
+    <tr><td>uint16</td><td>py.int</td></tr>
+    <tr><td>int32</td><td>py.int</td></tr>
+    <tr><td>uint32</td><td>py.int</td></tr>
+    <tr><td>int64</td><td>py.int</td></tr>
+    <tr><td>uint64</td><td>py.int</td></tr>
+    <tr><td>string scalar</td><td>py.str</td></tr>
+    <tr><td>char vector</td><td>py.str</td></tr>
+    <tr><td>logical</td><td>py.bool</td></tr>
+    <tr><td>struct</td><td>py.dict</td></tr>
+    </table>
+    <p />
+    <p><b>Pass 1-by-N Vector Nelson type to Python:</b></p>
+    <p />
+    <table style="width:100%">
+    <tr>
+        <th>Nelson 1-by-N Vector input argument type</th>
+        <th>Python type</th>
+    </tr>
+    <tr><td>double (real)</td><td>array.array('d')</td></tr>
+    <tr><td>single (real)</td><td>array.array('f')</td></tr>
+    <tr><td>int8</td><td>array.array('b')</td></tr>
+    <tr><td>uint8</td><td>array.array('B')</td></tr>
+    <tr><td>int16</td><td>array.array('h')</td></tr>
+    <tr><td>uint16</td><td>array.array('H')</td></tr>
+    <tr><td>int32</td><td>array.array('i')</td></tr>
+    <tr><td>uint32</td><td>array.array('I')</td></tr>
+    <tr><td>int64</td><td>array.array('q')</td></tr>
+    <tr><td>uint64</td><td>array.array('Q')</td></tr>
+    <tr><td>double</td><td>memoryview</td></tr>
+    <tr><td>single</td><td>memoryview</td></tr>
+    <tr><td>logical</td><td>memoryview</td></tr>
+    <tr><td>char vector</td><td>str</td></tr>
+    <tr><td>string scalar</td><td>str</td></tr>
+    <tr><td>cell vector</td><td>tuple</td></tr>
+    </table>
+
+    <p />
+    <p><b>Pass 2D Matrices and ND Arrays to Python:</b></p>
+    <p
+    >The Python language offers a protocol for accessing memory buffers, akin to the data stored in Nelson arrays.</p>
+    <p>Nelson incorporates this Python buffer protocol for its arrays.</p>
+
+
+  </description>
+
+  <used_function />
+  <bibliography />
+
+<examples>
+
+  <example_item>
+    <example_item_type>nelson</example_item_type>
+    <example_item_description />
+    <example_item_data><![CDATA[R = pyrun('', "A", 'A', magic(3))
+R.double()]]>
+    </example_item_data>
+  </example_item>
+</examples>
+
+  <see_also>
+    <see_also_item>
+      <link linkend="${python_engine}pyrun">pyrun</link>
+    </see_also_item>
+  </see_also>
+
+  <history>
+    <history_item>
+      <history_version>1.4.0</history_version>
+      <history_description>initial version</history_description>
+    </history_item>
+  </history>
+
+  <authors>
+    <author_item>Allan CORNET</author_item>
+  </authors>
+</xmldoc>