3 \page kernel_salome Using salome.py module
6 The Python module salome.py provides a functionality to access main
7 SALOME features from the Python console (either embedded in GUI
8 desktop or external one).
10 To use salome.py module, import it into the Python interpreter and
11 initialize it by calling \c salome_init() function:
18 The salome.py Python module provides a set of variables and functions
19 allowing access to different elements of the current SALOME
21 This page gives a short description of most useful variables and
24 \li \b orb Reference to the CORBA::ORB instance
26 This variable can be used to initialize different CORBA-related
27 elements of the SALOME session (for example, naming service, etc).
28 For example, to get an access to the SALOME naming service, you can
29 use the following commands:
31 import SALOME_NamingServicePy
32 NS = SALOME_NamingServicePy.SALOME_NamingServicePy_i(salome.orb)
35 The \b orb variable is also useful when it is necessary to convert
36 CORBA reference object to its string representation (IOR) and vice
39 studyIOR = salome.orb.object_to_string(salome.myStudy)
40 study = salome.orb.string_to_object(studyIOR)
41 is_same = salome.myStudy._is_equivalent(study) # is_same = True
44 \li \b naming_service SALOME naming service instance
46 This variable can be used to register/find objects created in a
47 distributed environment. For example, to get access to the SALOME
48 Module Catalog server, use \c Resolve() method:
50 import SALOME_ModuleCatalog
51 mc = salome.naming_service.Resolve('/Kernel/ModulCatalog')
54 Similarly, method \c Register() can be used to register objects
55 in the naming service:
57 salome.naming_service.Register(myObject,'/My/Object/Path')
58 o = salome.naming_service.Resolve('/My/Object/Path')
59 is_same = myObject._is_equivalent(o) # is_same = True
62 \li \b lcc Life Cycle CORBA class instance
64 This object can be used to get access to CORBA engine part of some
65 SALOME module, available in the current SALOME session. The following
66 code returns a reference to the Geometry module engine, loading it if
70 geom = salome.lcc.FindOrLoadComponent('FactoryServer', 'GEOM')
72 \b Note, that in the above example, \e "FactoryServer" is a name of the
73 SALOME container, where Geometry module engine should be loaded.
75 \li \b myStudyManager Reference to the study manager
77 SALOMEDS Study manager is used to manipulate with the studies: create,
78 open, save, close. It also can be used to find the study by its
79 numerical ID or name. The code below demonstrates main
80 functionalities of a study manager:
82 # create new study with the name "MyStudy"
83 new_study = salome.myStudyManager.NewStudy("MyStudy")
85 # open study from file /home/user/MyStudy.hdf
86 study = salome.myStudyManager.OpenStudy("/home/user/MyStudy.hdf")
89 salome.myStudyManager.Save(study, False) # not using multifile save mode
91 # save study in ASCII format
92 salome.myStudyManager.SaveASCII(study, True) # using multifile save mode
94 # save study with the new file path
95 salome.myStudyManager.SaveAs("/home/user/MyStudy.hdf", study, False)
97 # save study with the new file path in ASCII format
98 salome.myStudyManager.SaveAsASCII("/home/user/MyStudy.hdf", study, False)
101 salome.myStudyManager.Close(study)
103 # get list of all opened studies
104 studies = salome.myStudyManager.GetOpenStudies()
106 # find study by its numerical ID (integer value starting from 1)
107 study = salome.myStudyManager.GetStudyByID(studyID)
109 # find study by its name
110 study = salome.myStudyManager.GetStudyByName("/home/user/MyStudy.hdf")
115 \li \b myStudy Reference to the current (active) study
117 This variable can be used to manipulate with the date of the study:
118 create data tree, assign attributes of different types to the objects
119 in a data tree, create references between objects, etc.
121 \b Note, that the term "active" or "current" study does not make much
122 sense outise the GUI Python console. When working in GUI, user always
123 deals with one only top-level study, which desktop is currently on the
124 top if the windows stack. This is what is called \e "active study".
125 In TUI mode (without GUI or outside GUI), user has to manipulate with
126 studies manually; no any special control for the life cycle of the
127 study is done. In TUI mode, \c salome.muStudy variable is an instance
128 of the first study created when you call salome_init() function.
130 The following code demonstrates some examples of \c salome.myStudy
131 variable usage. For more details please refer to the SALOMEDS.idl file
136 studyName = salome.myStudy._get_Name()
138 # get study numerical ID
139 studyID = salome.myStudy._get_StudyId()
141 # find SALOMEDS component by its type
142 scomponent = FindComponent("MyComponent")
144 # find SALOMEDS component by its entry ID
145 scomponent = FindComponentID("0:1:1") # "0:1:1" is a component ID
147 # find SALOMEDS object by its name (first found object is returned)
148 sobject = salome.myStudy.FindObject("MyObject")
150 # find SALOMEDS object by its entry ID
151 sobject = salome.myStudy.FindObjectID() # "0:1:1:1" is an object ID
153 # find SALOMEDS object by its IOR attribute
154 sobject = salome.myStudy.FindObjectIOR(IOR)
156 # find SALOMEDS object by its path in the data tree
157 sobject = salome.myStudy.FindObjectByPath("/MyComponent/MyObject/MySubObject")
159 # get SALOMEDS object's path in a study data tree
160 sobject_path = salome.myStudy.GetObjectPath(sobject)
162 # get study properties
163 prop = salome.myStudy.GetProperties()
164 prop.GetCreationDate() # get creation date
165 prop.IsModified() # check if study has been modified (and not yet saved)
166 prop.SetLocked(True) # lock the study (prohibit modifications)
167 prop.IsLocked() # check if study is locked
169 # create objects with study builder
170 builder = salome.myStudy.NewBuilder() # create builder
171 comp = builder.NewComponent("MyComponent") # create a component of the "MyComponent" type
172 attrName = builder.FindOrCreateAttribute(comp, "AttributeName")
173 attrName.SetValue("MyComponent") # set name to the component
174 object = builder.NewObject(comp) # create new object, a child of the component
175 attrName = builder.FindOrCreateAttribute(object, "AttributeName")
176 attrName.SetValue("MyObject") # set name to the object
177 attrInt = builder.FindOrCreateAttribute(object, "AttributeInteger")
178 attrInt.SetValue(123) # assign integer attribute to the object
179 attrIOR = builder.FindOrCreateAttribute(object, "AttributeIOR")
180 attrIOR.SetValue(IOR) # assign IOR attribute to the object (to point to some CORBA object)
182 # iterate through objects of the data tree with child iterator
183 iter = salome.myStudy.NewChildIterator(comp) # initialize from the component
184 iter.InitEx(True) # init recursive mode
194 \li \b myStudyId Identifier of the current (active) study
196 This variable contains the numerical identifier of the current
197 (active) study. It is an equivalent of \c
198 salome.myStudy._get_StudyId() code.
200 \li \b myStudyName Name of the current (active) study
202 This variable contains the name of the current (active) study. It is
203 an equivalent of \c salome.myStudy._get_Name() code.
205 \li \b DumpStudy() Print study contents
207 This function prints the study data object tree to the terminal
208 window. The output for each object includes its entry ID, name, IOR
209 (if there is one) and referenced object ID (for references). I.e.
210 this is the same data the user can see in the Object Browser columns.
212 salome.DumpStudy(salome.myStudy)
215 \li \b IDToSObject() Get SALOMEDS object by its entry ID.
217 This function checks if the SObject with the specified entry ID exists
218 in the current study and returns it. Otherwise \c None is returned.
220 sobject = salome.IDToSObject("0:1:1:1") # "0:1:1:1" is an object ID
222 Actually this function is just a shortcut to the following code:
224 sobject = salome.myStudy.FindObjectID("0:1:1:1")
227 \li \b IDToObject() Get CORBA object by its entry ID.
229 This function checks if the SObject with the specified entry ID exists
230 in the current study, then retrieves IOR attribute from it and,
231 finally, if IOR is not empty, returns CORBA object corresponding to
234 object = salome.IDToObject("0:1:1:1") # "0:1:1:1" is an object ID
236 Actually this function is just a shortcut to the following code:
238 sobject = salome.myStudy.FindObjectID("0:1:1:1")
240 object = sobject.GetObject()
245 \li \b ObjectToSObject() Get SALOMEDS object corresponding to the
248 This function finds an object in the current study which corresponds
249 to the specified CORBA object (i.e. it has IOR attribute, pointing to
250 the CORBA object). If there is no corresponding SALOMEDS object in the
251 study, \c None is returned:
253 sobject = salome.ObjectToSObject(object)
255 Actually this function is just a shortcut to the following code:
257 ior = salome.orb.object_to_string(object)
258 sobject = salome.myStudy.FindObjectIOR(ior)
261 \li \b ObjectToID() Get SALOMEDS object entry ID corresponding to the
264 This function finds an object in the current study which corresponds
265 to the specified CORBA object (i.e. it has IOR attribute, pointing to
266 the CORBA object). If the object is found, its entry ID is returned,
267 otherwise empty string is returned:
269 entry = salome.ObjectToID(object)
271 Actually this function is just a shortcut to the following code:
273 ior = salome.orb.object_to_string(object)
274 sobject = salome.myStudy.FindObjectIOR(ior)
276 entry = sobject.GetID()
281 \li \b createNewStudy() Create new study
283 This function can be used to create new SALOME study. Returns an ID of
286 studyId = salome.createNewStudy()
287 study = salome.myStudyManager.GetStudyByID(s)
290 \li \b generateName() Generate unique name
292 This function adds random numerical suffix to the passed string
293 parameter ("Study" by default) and returns the resulting string:
295 name_1 = salome.generateName() # name_1 is something like "Study682"
296 name_1 = salome.generateName("Obj") # name_1 is something like "Obj32"