Basic question: Python API documentation

Matthias

I got this question and I'd like to answer it here. I think it's a common question:

I am interested in python scripting using your software. Is there anywhere in the documentation that specifies python syntax? For example, is
there somewhere that shows what information I input into the SimplePolygon constructor that would give me the output I want? It is not clear
if I need to input a list of integers.. etc.

Matthias

This is my answer:

There is documentation, but it needs a little bit of encoding. The reason is the multi-language binding and I don't want to write that huge pile of documentation twice.

The documentation is mainly based on Ruby, simply because this was there first. There is a guide explaining the mapping to Python here: https://www.klayout.de/doc-qt5/programming/python.html ("Python Implementation Notes").

For the SimplePolygon constructor here is the worked-out example:

1. The basic documentation is found here (goto https://www.klayout.de/doc-qt5/ and search for "SimplePolygon", pick "API Reference"): https://www.klayout.de/doc-qt5/code/class_SimplePolygon.html#k_1

2. The constructors are listed under "Public constructors": there are four of them. The first takes a DSimplePolygon argument. This is the constructor converting a floating-point type polygon into a integer-type one. The second constructor is the argument-less default constructor. The forth one is the constructor taking a Box and turning into a polygon with four points. The third one is the one you look for.

3. This third constructor takes two parameters. I'll ignore the second one now because the default value is good usually. From the constructor signature you can tell that the first argument is something called "Point[] pts". This is a formal type description. It's not specific to a certain language and means "array of Point objects". There are some more details about the formal method description documented here: https://www.klayout.de/doc-qt5/about/rba_notation.html

4. So the answer is to create an array of Point objects and pass this to the SimplePolygon constructor. Here is some sample code:

# A triangle
pts = [ pya.Point(0, 0), pya.Point(1000, 0), pya.Point(0,1000) ]
poly = pya.SimplePolygon(pts)

I'm aware that documentation isn't perfect. I typed my fingers bloody, still there is so much to document. Basically, KLayout is open source and documentation is part of that, so everyone is invited to enhance or correct the documentation. I'd also appreciate if you could take this discussion to the forum (https://www.klayout.de/forum/). This is a public place where people can look up answers. Without this