Python: Difference between revisions

From FreeCAD Documentation
(Created page with "[https://www.python.org Python] is a general purpose, high level programming language that very commonly is embedded in large applications to automate some tasks by creating s...")
 
(→‎Conventions: Explanation on Python style)
Line 6: Line 6:


== Conventions ==
== Conventions ==
In this wiki, some conventions for Python examples should be followed.
In this documentation, some conventions for Python examples should be followed.


This is a typical function
This is a typical function signature
{{Code|code=
{{Code|code=
Wire = makeWire(pointslist, closed=False, placement=None, face=None, support=None)
Wire = makeWire(pointslist, closed=False, placement=None, face=None, support=None)
}}
}}


* Python indicates optional arguments by providing a default value with key-value pairs. This means that any of the following calls are valid
* Arguments with key-value pairs are optional, with the default value indicated in the signature. This means that the following calls are equivalent:
{{Code|code=
{{Code|code=
Wire = makeWire(pointslist)
Wire = makeWire(pointslist, False)
Wire = makeWire(pointslist, False, None)
Wire = makeWire(pointslist, False, None, None)
Wire = makeWire(pointslist, False, None, None, None)
Wire = makeWire(pointslist, False, None, None, None)
Wire = makeWire(pointslist, False, None, None)
Wire = makeWire(pointslist, False, None)
Wire = makeWire(pointslist, False)
Wire = makeWire(pointslist)
}}
}}


: In this example the first argument doesn't have a default value so it should always be included.
* The arguments
*


* When the arguments are given with the explicit key, the optional arguments can be given in any order. This means that the following calls are equivalent:
{{Code|code=
Wire = makeWire(pointslist, closed=False, placement=None, face=None)
Wire = makeWire(pointslist, closed=False, face=None, placement=None)
Wire = makeWire(pointslist, placement=None, closed=False, face=None)
Wire = makeWire(pointslist, support=None, closed=False, placement=None, face=None)
}}

* Python guidelines stress readability of code; in particular, parentheses should immediately follow the function name, and a space should follow a comma.
{{Code|code=
import FreeCAD, Draft
import FreeCAD, Draft
p1 = FreeCAD.Vector(0, 0, 0)
p2 = FreeCAD.Vector(1, 1, 0)
p3 = FreeCAD.Vector(2, 0, 0)
Wire = Draft.makeWire([p1, p2, p3], closed=True)
}}


* If code needs to be broken over several lines, this should be done at a comma inside brackets or parentheses; the second line should be aligned with the previous one.
In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable.
{{Code|code=
a_list = [1, 2, 3,
2, 4, 5]

Wire = makeWire(pointslist,
False, None,
None, None)
}}

* Functions may return a value or object that can be used as the input of another drawing tool.
{{Code|code=
import Draft, Arch
Wire = Draft.makeWire(pointslist, closed=True, face=True)
Window = Arch.makeWindow(Wire, name="Big window")
}}

Revision as of 21:14, 26 October 2018

Python is a general purpose, high level programming language that very commonly is embedded in large applications to automate some tasks by creating scripts or macros.

In FreeCAD, Python code can be used to create various elements programmatically, without needing the graphical user interface. Additionally, many tools and workbenches of FreeCAD are programmed in Python.

When writing Python code, it's advisable to follow PEP8: Style Guide for Python Code.

Conventions

In this documentation, some conventions for Python examples should be followed.

This is a typical function signature

Wire = makeWire(pointslist, closed=False, placement=None, face=None, support=None)
  • Arguments with key-value pairs are optional, with the default value indicated in the signature. This means that the following calls are equivalent:
Wire = makeWire(pointslist, False, None, None, None)
Wire = makeWire(pointslist, False, None, None)
Wire = makeWire(pointslist, False, None)
Wire = makeWire(pointslist, False)
Wire = makeWire(pointslist)
In this example the first argument doesn't have a default value so it should always be included.
  • When the arguments are given with the explicit key, the optional arguments can be given in any order. This means that the following calls are equivalent:
Wire = makeWire(pointslist, closed=False, placement=None, face=None)
Wire = makeWire(pointslist, closed=False, face=None, placement=None)
Wire = makeWire(pointslist, placement=None, closed=False, face=None)
Wire = makeWire(pointslist, support=None, closed=False, placement=None, face=None)
  • Python guidelines stress readability of code; in particular, parentheses should immediately follow the function name, and a space should follow a comma.
import FreeCAD, Draft
p1 = FreeCAD.Vector(0, 0, 0)
p2 = FreeCAD.Vector(1, 1, 0)
p3 = FreeCAD.Vector(2, 0, 0)
Wire = Draft.makeWire([p1, p2, p3], closed=True)
  • If code needs to be broken over several lines, this should be done at a comma inside brackets or parentheses; the second line should be aligned with the previous one.
a_list = [1, 2, 3,
          2, 4, 5]

Wire = makeWire(pointslist,
                False, None,
                None, None)
  • Functions may return a value or object that can be used as the input of another drawing tool.
import Draft, Arch
Wire = Draft.makeWire(pointslist, closed=True, face=True)
Window = Arch.makeWindow(Wire, name="Big window")