pythonizing dont know python

Pythonizing: For those who don't know Python

Don't know Python?

No problem!

We're really only using a small amount of Python, but there are a few things you need to know, mostly having to deal with Python indenting and how Python handles strings.

Specifically: everything inside the {mpi-binding} block must be in valid Python syntax. If the syntax isn't correct, building the LaTeX document will fail.

The following sections discuss a few "gotchas" that you need to watch out for, particularly if you're not familiar with the Python language.

Indenting

Python requires a constant level of indenting. You can indent to any level you want (to include zero indentation), but you must make sure that all of your Python expressions inside a single {mpi-binding} block are indented to the same level.

   # Good indenting
   foo()
   bar()

   # Bad indenting (will cause an error)
       baz()
     yow()

To be clear: each {mpi-binding} block is self-contained. You can indent one {mpi-binding} block to N characters and a different {mpi-binding} block to M characters (where N!=M). But for human readability, we suggest using a common indenting level of 4 spaces (no tabs!) for each {mpi-binding} block.

You probably won't use any conditionals or have any reason for sub-blocks of code in the MPI standard Pythonizing, but if you do, you use indenting as the delimiter for that block of code. For example:

   foo()
   if value == 3:
       print("Hey, the value was 3!")
       value = 0
       print("I reset the value to 0 for you")

   # Outdented, so now we're back outside the conditional code block
   print("The value is: " + value)

Strings

Strings can be delimited with single ' or double " quote marks. For example:

   # Like many scripting languages, you do not need
   # to declare variables before using them:
   foo = 'Hello, world'
   bar = "Hello, world"

Multi-line strings can be delimited with three single or double quote marks:

  foo == """Hello,
world"""

  bar = '''Hello,
world.
I am awesome.
This is a very long,
       multi
             line
                  string.'''

Note that inside the string, any spacing for indenting is part of the string -- it is not required for general Python indenting syntax. But the string expressions themselves -- the assignments to foo and bar in this case -- must follow proper Python indenting.

Line breaks

Line breaks are allowed inside of (). For the purposes of the MPI standard, this will likely occur within the argument list to one of the MPI Pythonizing functions. Additionally, inside (), the indenting rules are relaxed: you can indent inconsistently. For example:

   # Here's a non-line broken line:
   foo(a, b, c)

   # Here's another with multiple line breaks:
   foo(a,
       b,
       c)

   # Note that the indenting does not need to be consistent within the ():
   some_reall_long_function_name(a,
       b, c, d, e, f,
       g, h, i, j, k)

Comments

Comments are generally of two flavors: dedicated comments or useless strings.

Dedicated comments start with the # symbol, like many other scripting languages. For example:

# This is a comment line
foo()   # This is a comment at the end of a line

For lengthy, multi-line comments, some Python programmers like to have a "useless" multi-line string. I.e., it's a valid string expression, but it evaluates to no purpose when executing the Python. For example:

   """This is a multi-line string
You can do whatever you want in this string
         Including indenting inconsistently.

Hello, world!"""
   foo()

Note that the string is a valid Python expression, so it must be indentend consistently with other Python expressions. In the example above, note how the opening """ and foo() are indented to the same level.

Putting it all together

Here's a slightly-unrealistic example that shows everything from above. All of this is within \begin{mpi-binding} / \end{mpi-binding}:

  """
This is the binding for MPI_ALLOC_MEM.

It is special in many ways.

But really, I just wanted to show a multi-line string that acts like a
comment."""

  functionname('MPI_Alloc_mem')

  # Use the special ALLOC_MEM_NUM_BYTES type
  # See comment in binding_tool.py for an explanation
  parameter('size', 'ALLOC_MEM_NUM_BYTES',
            desc='size of memory segment in bytes')
  parameter('info', 'INFO')
  parameter('baseptr', 'C_BUFFER', direction='out',
            desc='''pointer to beginning of memory
segment allocated''')