Difference between revisions of "Python"

From FreeCAD Documentation
Jump to: navigation, search
(Translate tag)
(Assume we are already in 2020.)
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
<languages/>
 
<languages/>
 
<translate>
 
<translate>
[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 scripts or [[macros]].
+
<!--T:25-->
 +
{{VeryImportantMessage|(January 2020) FreeCAD was originally designed to work with Python 2. Since Python 2 reached end of life in 2020, future development of FreeCAD will be done exclusively with Python 3, and backwards compatibility will not be supported.}}
  
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.
+
== Description == <!--T:26-->
  
 +
<!--T:27-->
 +
[https://www.python.org Python] is a general purpose, high level programming language that is very commonly used in large applications to automate some tasks by creating scripts or [[macros|macros]].
 +
 +
<!--T:28-->
 +
In FreeCAD, Python code can be used to create various elements programmatically, without needing to click on the graphical user interface. Additionally, many tools and workbenches of FreeCAD are programmed in Python.
 +
 +
<!--T:29-->
 +
See [[Introduction to Python|Introduction to Python]] to learn about the Python programming language, and then [[Python scripting tutorial|Python scripting tutorial]] and [[FreeCAD Scripting Basics|FreeCAD Scripting Basics]] to start scripting in FreeCAD.
 +
 +
<!--T:30-->
 
When writing Python code, it's advisable to follow [https://www.python.org/dev/peps/pep-0008/ PEP8: Style Guide for Python Code].
 
When writing Python code, it's advisable to follow [https://www.python.org/dev/peps/pep-0008/ PEP8: Style Guide for Python Code].
  
== Conventions ==
+
== Conventions == <!--T:31-->
 
In this documentation, some conventions for Python examples should be followed.
 
In this documentation, some conventions for Python examples should be followed.
  
 +
<!--T:32-->
 
This is a typical function signature
 
This is a typical function signature
 +
</translate>
 +
 
{{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)
 
}}
 
}}
 +
<translate>
  
 +
<!--T:33-->
 
* Arguments with key-value pairs are optional, with the default value indicated in the signature. This means that the following calls are equivalent:
 
* Arguments with key-value pairs are optional, with the default value indicated in the signature. This means that the following calls are equivalent:
 +
</translate>
 +
 
{{Code|code=
 
{{Code|code=
 
Wire = makeWire(pointslist, False, None, None, None)
 
Wire = makeWire(pointslist, False, None, None, None)
Line 24: Line 42:
 
}}
 
}}
  
 +
<translate>
 +
<!--T:34-->
 
: In this example the first argument doesn't have a default value so it should always be included.
 
: In this example the first argument doesn't have a default value so it should always be included.
  
 +
<!--T:35-->
 
* 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:
 
* 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:
 +
</translate>
 
{{Code|code=
 
{{Code|code=
 
Wire = makeWire(pointslist, closed=False, placement=None, face=None)
 
Wire = makeWire(pointslist, closed=False, placement=None, face=None)
Line 33: Line 55:
 
Wire = makeWire(pointslist, support=None, closed=False, placement=None, face=None)
 
Wire = makeWire(pointslist, support=None, closed=False, placement=None, face=None)
 
}}
 
}}
 +
<translate>
 +
 +
<!--T:36-->
 +
* Python's guidelines stress readability of code; in particular, parentheses should immediately follow the function name, and a space should follow a comma.
 +
</translate>
  
* Python guidelines stress readability of code; in particular, parentheses should immediately follow the function name, and a space should follow a comma.
 
 
{{Code|code=
 
{{Code|code=
import FreeCAD, Draft
+
p1 = Vector(0, 0, 0)
p1 = FreeCAD.Vector(0, 0, 0)
+
p2 = Vector(1, 1, 0)
p2 = FreeCAD.Vector(1, 1, 0)
+
p3 = Vector(2, 0, 0)
p3 = FreeCAD.Vector(2, 0, 0)
+
Wire = makeWire([p1, p2, p3], closed=True)
Wire = Draft.makeWire([p1, p2, p3], closed=True)
 
 
}}
 
}}
 +
<translate>
  
 +
<!--T:37-->
 
* 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.
 
* 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.
 +
</translate>
 +
 
{{Code|code=
 
{{Code|code=
 
a_list = [1, 2, 3,
 
a_list = [1, 2, 3,
Line 51: Line 80:
 
                 False, None,
 
                 False, None,
 
                 None, None)
 
                 None, None)
 +
}}
 +
<translate>
 +
 +
<!--T:38-->
 +
* Functions may return an object that can be used as the base of another drawing function.
 +
</translate>
 +
{{Code|code=
 +
Wire = makeWire(pointslist, closed=True, face=True)
 +
Window = makeWindow(Wire, name="Big window")
 +
}}
 +
<translate>
 +
 +
== Imports == <!--T:39-->
 +
 +
<!--T:40-->
 +
Python functions are stored in files called modules. Before using any function in that module, the module must be included in the document with the {{incode|import}} instruction.
 +
 +
<!--T:41-->
 +
This creates prefixed functions, that is, {{incode|module.function()}}. This system prevents name clashes with functions that are named the same but that come from different modules.
 +
For example, the two functions {{incode|Arch.makeWindow()}} and {{incode|myModule.makeWindow()}} may coexist without problem.
 +
 +
<!--T:42-->
 +
Full examples should include the necessary imports and the prefixed functions.
 +
 +
</translate>
 +
{{Code|code=
 +
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)
 
}}
 
}}
  
* Functions may return a value or object that can be used as the input of another drawing tool.
 
 
{{Code|code=
 
{{Code|code=
import Draft, Arch
+
import FreeCAD, Draft, Arch
 +
 
 +
p1 = FreeCAD.Vector(0, 0, 0)
 +
p2 = FreeCAD.Vector(1, 0, 0)
 +
p3 = FreeCAD.Vector(1, 1, 0)
 +
p4 = FreeCAD.Vector(0, 2, 0)
 +
pointslist = [p1, p2, p3, p4]
 +
 
 
Wire = Draft.makeWire(pointslist, closed=True, face=True)
 
Wire = Draft.makeWire(pointslist, closed=True, face=True)
Window = Arch.makeWindow(Wire, name="Big window")
+
Structure = Arch.makeStructure(Wire, name="Big pillar")
 
}}
 
}}
 +
 +
<translate>
 +
<!--T:43-->
 +
[[Category:API Documentation]]
 +
[[Category:Developer Documentation]]
 +
[[Category:Poweruser Documentation]]
 +
[[Category:User Documentation]]
 
</translate>
 
</translate>

Latest revision as of 08:44, 21 September 2019

Other languages:
Deutsch • ‎English • ‎français • ‎italiano • ‎română • ‎русский • ‎Türkçe
(January 2020) FreeCAD was originally designed to work with Python 2. Since Python 2 reached end of life in 2020, future development of FreeCAD will be done exclusively with Python 3, and backwards compatibility will not be supported.


Description

Python is a general purpose, high level programming language that is very commonly used 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 to click on the graphical user interface. Additionally, many tools and workbenches of FreeCAD are programmed in Python.

See Introduction to Python to learn about the Python programming language, and then Python scripting tutorial and FreeCAD Scripting Basics to start scripting in FreeCAD.

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's guidelines stress readability of code; in particular, parentheses should immediately follow the function name, and a space should follow a comma.
p1 = Vector(0, 0, 0)
p2 = Vector(1, 1, 0)
p3 = Vector(2, 0, 0)
Wire = 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 an object that can be used as the base of another drawing function.
Wire = makeWire(pointslist, closed=True, face=True)
Window = makeWindow(Wire, name="Big window")

Imports

Python functions are stored in files called modules. Before using any function in that module, the module must be included in the document with the import instruction.

This creates prefixed functions, that is, module.function(). This system prevents name clashes with functions that are named the same but that come from different modules. For example, the two functions Arch.makeWindow() and myModule.makeWindow() may coexist without problem.

Full examples should include the necessary imports and the prefixed functions.

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)
import FreeCAD, Draft, Arch

p1 = FreeCAD.Vector(0, 0, 0)
p2 = FreeCAD.Vector(1, 0, 0)
p3 = FreeCAD.Vector(1, 1, 0)
p4 = FreeCAD.Vector(0, 2, 0)
pointslist = [p1, p2, p3, p4]

Wire = Draft.makeWire(pointslist, closed=True, face=True)
Structure = Arch.makeStructure(Wire, name="Big pillar")