Changeset e7ad08 for doc

Timestamp:

Apr 11, 2018, 6:30:10 AM (7 years ago)

Author:

Frederik Heber <frederik.heber@…>

Branches:

Candidate_v1.6.1, ChemicalSpaceEvaluator, PythonUI_with_named_parameters, TremoloParser_IncreasedPrecision

Children:

cd91bd

Parents:

8819d2

git-author:

Frederik Heber <frederik.heber@…> (09/06/17 12:58:47)

git-committer:

Frederik Heber <frederik.heber@…> (04/11/18 06:30:10)

Message:

Python interface now converts dashes in tokens to underscores, store-session used keyword arguments.

• MoleCuilder's python functions (i.e. commands) typically have quite a number of arguments and therefore can be easily confused. We circumvent this by using keyword (or named) arguments that are also independent of position. Moreover, in that case only the non-default arguments need to be given.
• TESTS: Marked failing python tests as XFAIL for the moment.

File:

• doc/userguide/userguide.xml (modified) (2 diffs)

doc/userguide/userguide.xml

@@ -2610 +2610 @@
           the python interface described below, i.e. it is a full python script
           (that however requires the so-called <emphasis role="italic">pyMoleCuilder</emphasis> module).</para>
+          <note>The python session will store a file with python commands using named arguments. As some actions have quite
+          a number of arguments, all of them end up in a single function call. This makes it very hazard-prone to mix them up.
+          Therefore, it is <emphasis>strongly</emphasis> recommended to always use named arguments in python scripts
+          when employing MoleCuilder commands.</note>
+          <para>When using named arguments for MoleCuilder commands in Python scripts, remember that dashes ("-") in
+          argument names have been converted to underscores ("_") as the former characters are illegal. Apart from that
+          the argument names resemble exactly the token names as encountered on the command line, e.g.
+          <programlisting>
+          pyMoleCuilder.CommandVerbose(verbose="1")
+          ...
+          </programlisting>
+          where the keyword argument "verbose" is for the Action that changes MoleCuilder's output verbosity. Also,
+          you see that arguments are always given as string.
+          </para>
         </section>
         <section xml:id="sessions.load-session">
@@ -2999 +3013 @@
       <para>Therefore, more complex python scripts need to be called with
       python and a set PYTHONPATH as described above.</para>
+          <note>It is <emphasis>strongly</emphasis> recommended to always use named arguments in python scripts
+          when employing MoleCuilder commands. As commands tend to have many arguments, it is very easy to mix
+          them up as python is not a strongly typed language.</note>
     </section>
   </chapter>