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 \anchor salome_myStudy
76 \li \b myStudy Reference to the current (active) study
78 This variable can be used to manipulate with the date of the study:
79 create data tree, assign attributes of different types to the objects
80 in a data tree, create references between objects, etc.
82 \b Note, that the term "active" or "current" study does not make much
83 sense outise the GUI Python console. When working in GUI, user always
84 deals with one only top-level study, which desktop is currently on the
85 top if the windows stack. This is what is called \e "active study".
86 In TUI mode (without GUI or outside GUI), user has to manipulate with
87 studies manually; no any special control for the life cycle of the
88 study is done. In TUI mode, \c salome.muStudy variable is an instance
89 of the first study created when you call salome_init() function.
91 The following code demonstrates some examples of \c salome.myStudy
92 variable usage. For more details please refer to the SALOMEDS.idl file
97 studyName = salome.myStudy._get_Name()
99 # open study from file /home/user/MyStudy.hdf
100 salome.myStudy.Open("/home/user/MyStudy.hdf")
103 salome.myStudy.Save(False, False) # not using multifile save mode
105 # save study in ASCII format
106 salome.myStudy.Save(True, True) # using multifile save mode
108 # save study with the new file path
109 salome.myStudy.SaveAs("/home/user/MyStudy.hdf", False, False)
111 # save study with the new file path in ASCII format
112 salome.myStudy.SaveAs("/home/user/MyStudy.hdf", False, True)
115 salome.myStudy.Clear()
118 salome.myStudy.Init()
120 # find SALOMEDS component by its type
121 scomponent = FindComponent("MyComponent")
123 # find SALOMEDS component by its entry ID
124 scomponent = FindComponentID("0:1:1") # "0:1:1" is a component ID
126 # find SALOMEDS object by its name (first found object is returned)
127 sobject = salome.myStudy.FindObject("MyObject")
129 # find SALOMEDS object by its entry ID
130 sobject = salome.myStudy.FindObjectID() # "0:1:1:1" is an object ID
132 # find SALOMEDS object by its IOR attribute
133 sobject = salome.myStudy.FindObjectIOR(IOR)
135 # find SALOMEDS object by its path in the data tree
136 sobject = salome.myStudy.FindObjectByPath("/MyComponent/MyObject/MySubObject")
138 # get SALOMEDS object's path in a study data tree
139 sobject_path = salome.myStudy.GetObjectPath(sobject)
141 # get study properties
142 prop = salome.myStudy.GetProperties()
143 prop.GetCreationDate() # get creation date
144 prop.IsModified() # check if study has been modified (and not yet saved)
145 prop.SetLocked(True) # lock the study (prohibit modifications)
146 prop.IsLocked() # check if study is locked
148 # create objects with study builder
149 builder = salome.myStudy.NewBuilder() # create builder
150 comp = builder.NewComponent("MyComponent") # create a component of the "MyComponent" type
151 attrName = builder.FindOrCreateAttribute(comp, "AttributeName")
152 attrName.SetValue("MyComponent") # set name to the component
153 object = builder.NewObject(comp) # create new object, a child of the component
154 attrName = builder.FindOrCreateAttribute(object, "AttributeName")
155 attrName.SetValue("MyObject") # set name to the object
156 attrInt = builder.FindOrCreateAttribute(object, "AttributeInteger")
157 attrInt.SetValue(123) # assign integer attribute to the object
158 attrIOR = builder.FindOrCreateAttribute(object, "AttributeIOR")
159 attrIOR.SetValue(IOR) # assign IOR attribute to the object (to point to some CORBA object)
161 # iterate through objects of the data tree with child iterator
162 iter = salome.myStudy.NewChildIterator(comp) # initialize from the component
163 iter.InitEx(True) # init recursive mode
173 \li \b myStudyName Name of the current (active) study
175 This variable contains the name of the current (active) study. It is
176 an equivalent of \c salome.myStudy._get_Name() code.
178 \li \b DumpStudy() Print study contents
180 This function prints the study data object tree to the terminal
181 window. The output for each object includes its entry ID, name, IOR
182 (if there is one) and referenced object ID (for references). I.e.
183 this is the same data the user can see in the Object Browser columns.
188 \li \b IDToSObject() Get SALOMEDS object by its entry ID.
190 This function checks if the SObject with the specified entry ID exists
191 in the current study and returns it. Otherwise \c None is returned.
193 sobject = salome.IDToSObject("0:1:1:1") # "0:1:1:1" is an object ID
195 Actually this function is just a shortcut to the following code:
197 sobject = salome.myStudy.FindObjectID("0:1:1:1")
200 \li \b IDToObject() Get CORBA object by its entry ID.
202 This function checks if the SObject with the specified entry ID exists
203 in the current study, then retrieves IOR attribute from it and,
204 finally, if IOR is not empty, returns CORBA object corresponding to
207 object = salome.IDToObject("0:1:1:1") # "0:1:1:1" is an object ID
209 Actually this function is just a shortcut to the following code:
211 sobject = salome.myStudy.FindObjectID("0:1:1:1")
213 object = sobject.GetObject()
218 \li \b ObjectToSObject() Get SALOMEDS object corresponding to the
221 This function finds an object in the current study which corresponds
222 to the specified CORBA object (i.e. it has IOR attribute, pointing to
223 the CORBA object). If there is no corresponding SALOMEDS object in the
224 study, \c None is returned:
226 sobject = salome.ObjectToSObject(object)
228 Actually this function is just a shortcut to the following code:
230 ior = salome.orb.object_to_string(object)
231 sobject = salome.myStudy.FindObjectIOR(ior)
234 \li \b ObjectToID() Get SALOMEDS object entry ID corresponding to the
237 This function finds an object in the current study which corresponds
238 to the specified CORBA object (i.e. it has IOR attribute, pointing to
239 the CORBA object). If the object is found, its entry ID is returned,
240 otherwise empty string is returned:
242 entry = salome.ObjectToID(object)
244 Actually this function is just a shortcut to the following code:
246 ior = salome.orb.object_to_string(object)
247 sobject = salome.myStudy.FindObjectIOR(ior)
249 entry = sobject.GetID()
254 \li \b generateName() Generate unique name
256 This function adds random numerical suffix to the passed string
257 parameter ("Study" by default) and returns the resulting string:
259 name_1 = salome.generateName() # name_1 is something like "Study682"
260 name_1 = salome.generateName("Obj") # name_1 is something like "Obj32"
263 \li \b GetComponentVersion() Get version of component data stored in
266 This function allows to obtain the version of the component data
267 stored in the current study.
268 \note This function does not provide a current version of the
269 component being used but that one initially stored in the study
272 The first parameter specifies the name of the component. If the
273 specified component data is not stored in the study, the result value
274 is "no component data". If the version of data is undefined, the
277 The second parameter (\c False by default), when set to \c True,
278 allows to retrieve all versions of the component data stored in the
279 study. This is useful to check if version information is valid (the
280 data might be updated and/or re-stored in %SALOME of versions different
284 # get initial version of GEOM module data stored in the study
285 geom_version = salome.GetComponentVersion('GEOM')
286 # get all versions of GEOM module data stored in the study
287 all_geom_versions = salome.GetComponentVersion('GEOM', True)
290 This function is introduced in %SALOME 6.6.0 (it does not work with
291 studies created before version 6.6.0).
293 \note The study should be initialized before calling this function
294 (see \ref salome_myStudy "salome.myStudy").