[pytango] 67/98: Update tango imports in documentation
Sandor Bodo-Merle
sbodomerle-guest at moszumanska.debian.org
Thu Sep 28 19:17:46 UTC 2017
This is an automated email from the git hooks/post-receive script.
sbodomerle-guest pushed a commit to tag v9.2.0
in repository pytango.
commit f67bdf79429e546e05ffa47823bb752fccce37df
Author: Vincent Michel <vincent.michel at maxlab.lu.se>
Date: Fri Jul 8 18:04:49 2016 +0200
Update tango imports in documentation
---
doc/data_types.rst | 8 +--
doc/exception.rst | 192 +++++++++++++++++++++++++------------------------
doc/faq.rst | 35 +++++----
doc/howto.rst | 204 ++++++++++++++++++++++++++---------------------------
doc/quicktour.rst | 73 ++++++++++---------
doc/start.rst | 14 ++--
6 files changed, 260 insertions(+), 266 deletions(-)
diff --git a/doc/data_types.rst b/doc/data_types.rst
index eb08d47..483e621 100644
--- a/doc/data_types.rst
+++ b/doc/data_types.rst
@@ -183,13 +183,13 @@ much more efficient.
| | | 1. sequence<:py:obj:`str`> | 1. sequence<:py:obj:`str`> (decoded with *latin-1*, aka *ISO-8859-1*) |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
-For SPECTRUM and IMAGES the actual sequence object used depends on the context
+For SPECTRUM and IMAGES the actual sequence object used depends on the context
where the tango data is used, and the availability of :py:mod:`numpy`.
1. for properties the sequence is always a :py:class:`list`. Example::
-
- >>> import PyTango
- >>> db = PyTango.Database()
+
+ >>> import tango
+ >>> db = tango.Database()
>>> s = db.get_property(["TangoSynchrotrons"])
>>> print type(s)
<type 'list'>
diff --git a/doc/exception.rst b/doc/exception.rst
index 9371d9b..cd18dc8 100644
--- a/doc/exception.rst
+++ b/doc/exception.rst
@@ -44,12 +44,12 @@ all of which containing the following kind of key-value pairs:
::
- import PyTango
+ import tango
# How to protect the script from exceptions raised by the Tango
try:
# Get proxy on a non existing device should throw an exception
- device = DeviceProxy("non/existing/device")
+ device = tango.DeviceProxy("non/existing/device")
except DevFailed as df:
print("Failed to create proxy to non/existing/device:\n%s" % df)
@@ -57,8 +57,8 @@ all of which containing the following kind of key-value pairs:
Throwing exception in a device server
-------------------------------------
-The C++ :class:`~PyTango::Except` class with its most important methods have
-been wrapped to Python. Therefore, in a Python device server, you have the
+The C++ :class:`~PyTango::Except` class with its most important methods have
+been wrapped to Python. Therefore, in a Python device server, you have the
following methods to throw, re-throw or print a Tango::DevFailed exception :
- :meth:`~PyTango.Except.throw_exception` which is a static method
@@ -97,36 +97,36 @@ Exception API
.. autoexception:: PyTango.ConnectionFailed
:show-inheritance:
-
- This exception is thrown when a problem occurs during the connection
- establishment between the application and the device. The API is stateless.
- This means that DeviceProxy constructors filter most of the exception
- except for cases described in the following table.
-
+
+ This exception is thrown when a problem occurs during the connection
+ establishment between the application and the device. The API is stateless.
+ This means that DeviceProxy constructors filter most of the exception
+ except for cases described in the following table.
+
The desc DevError structure field allows a user to get more precise information. These informations are :
-
+
**DB_DeviceNotDefined**
- The name of the device not defined in the database
- **API_CommandFailed**
- The device and command name
- **API_CantConnectToDevice**
- The device name
- **API_CorbaException**
- The name of the CORBA exception, its reason, its locality, its completed
- flag and its minor code
- **API_CantConnectToDatabase**
- The database server host and its port number
- **API_DeviceNotExported**
+ The name of the device not defined in the database
+ **API_CommandFailed**
+ The device and command name
+ **API_CantConnectToDevice**
+ The device name
+ **API_CorbaException**
+ The name of the CORBA exception, its reason, its locality, its completed
+ flag and its minor code
+ **API_CantConnectToDatabase**
+ The database server host and its port number
+ **API_DeviceNotExported**
The device name
.. autoexception:: PyTango.CommunicationFailed
:show-inheritance:
-
- This exception is thrown when a communication problem is detected during
- the communication between the client application and the device server. It
+
+ This exception is thrown when a communication problem is detected during
+ the communication between the client application and the device server. It
is a two levels Tango::DevError structure. In case of time-out, the DevError
- structures fields are:
+ structures fields are:
+-------+--------------------+-------------------------------------------------+----------+
| Level | Reason | Desc | Severity |
@@ -136,7 +136,7 @@ Exception API
| 1 | API_DeviceTimedOut | String with time-out value and device name | ERR |
+-------+--------------------+-------------------------------------------------+----------+
- For all other communication errors, the DevError structures fields are:
+ For all other communication errors, the DevError structures fields are:
+-------+-------------------------+----------------------------------------------------+----------+
| Level | Reason | Desc | Severity |
@@ -150,86 +150,86 @@ Exception API
.. autoexception:: PyTango.WrongNameSyntax
:show-inheritance:
-This exception has only one level of Tango::DevError structure. The possible
+This exception has only one level of Tango::DevError structure. The possible
value for the reason field are :
**API_UnsupportedProtocol**
- This error occurs when trying to build a DeviceProxy or an AttributeProxy
- instance for a device with an unsupported protocol. Refer to the appendix
- on device naming syntax to get the list of supported database modifier
+ This error occurs when trying to build a DeviceProxy or an AttributeProxy
+ instance for a device with an unsupported protocol. Refer to the appendix
+ on device naming syntax to get the list of supported database modifier
**API_UnsupportedDBaseModifier**
- This error occurs when trying to build a DeviceProxy or an AttributeProxy
- instance for a device/attribute with a database modifier unsupported.
- Refer to the appendix on device naming syntax to get the list of
- supported database modifier
+ This error occurs when trying to build a DeviceProxy or an AttributeProxy
+ instance for a device/attribute with a database modifier unsupported.
+ Refer to the appendix on device naming syntax to get the list of
+ supported database modifier
**API_WrongDeviceNameSyntax**
- This error occurs for all the other error in device name syntax. It is
- thrown by the DeviceProxy class constructor.
+ This error occurs for all the other error in device name syntax. It is
+ thrown by the DeviceProxy class constructor.
**API_WrongAttributeNameSyntax**
- This error occurs for all the other error in attribute name syntax. It
- is thrown by the AttributeProxy class constructor.
+ This error occurs for all the other error in attribute name syntax. It
+ is thrown by the AttributeProxy class constructor.
**API_WrongWildcardUsage**
- This error occurs if there is a bad usage of the wildcard character
+ This error occurs if there is a bad usage of the wildcard character
.. autoexception:: PyTango.NonDbDevice
:show-inheritance:
- This exception has only one level of Tango::DevError structure. The reason
- field is set to API_NonDatabaseDevice. This exception is thrown by the API
- when using the DeviceProxy or AttributeProxy class database access for
- non-database device.
+ This exception has only one level of Tango::DevError structure. The reason
+ field is set to API_NonDatabaseDevice. This exception is thrown by the API
+ when using the DeviceProxy or AttributeProxy class database access for
+ non-database device.
.. autoexception:: PyTango.WrongData
:show-inheritance:
- This exception has only one level of Tango::DevError structure.
+ This exception has only one level of Tango::DevError structure.
The possible value for the reason field are :
**API_EmptyDbDatum**
- This error occurs when trying to extract data from an empty DbDatum
- object
+ This error occurs when trying to extract data from an empty DbDatum
+ object
**API_IncompatibleArgumentType**
- This error occurs when trying to extract data with a type different
- than the type used to send the data
+ This error occurs when trying to extract data with a type different
+ than the type used to send the data
**API_EmptyDeviceAttribute**
- This error occurs when trying to extract data from an empty
- DeviceAttribute object
+ This error occurs when trying to extract data from an empty
+ DeviceAttribute object
**API_IncompatibleAttrArgumentType**
- This error occurs when trying to extract attribute data with a type
- different than the type used to send the data
+ This error occurs when trying to extract attribute data with a type
+ different than the type used to send the data
**API_EmptyDeviceData**
- This error occurs when trying to extract data from an empty DeviceData
- object
+ This error occurs when trying to extract data from an empty DeviceData
+ object
**API_IncompatibleCmdArgumentType**
- This error occurs when trying to extract command data with a type
- different than the type used to send the data
+ This error occurs when trying to extract command data with a type
+ different than the type used to send the data
.. autoexception:: PyTango.NonSupportedFeature
:show-inheritance:
- This exception is thrown by the API layer when a request to a feature
- implemented in Tango device interface release n is requested for a device
- implementing Tango device interface n-x. There is one possible value for
- the reason field which is API_UnsupportedFeature.
+ This exception is thrown by the API layer when a request to a feature
+ implemented in Tango device interface release n is requested for a device
+ implementing Tango device interface n-x. There is one possible value for
+ the reason field which is API_UnsupportedFeature.
.. autoexception:: PyTango.AsynCall
:show-inheritance:
This exception is thrown by the API layer when a the asynchronous model id
- badly used. This exception has only one level of Tango::DevError structure.
+ badly used. This exception has only one level of Tango::DevError structure.
The possible value for the reason field are :
**API_BadAsynPollId**
- This error occurs when using an asynchronous request identifier which is not
- valid any more.
+ This error occurs when using an asynchronous request identifier which is not
+ valid any more.
**API_BadAsyn**
- This error occurs when trying to fire callback when no callback has been
- previously registered
+ This error occurs when trying to fire callback when no callback has been
+ previously registered
**API_BadAsynReqType**
- This error occurs when trying to get result of an asynchronous request with
- an asynchronous request identifier returned by a non-coherent asynchronous
- request (For instance, using the asynchronous request identifier returned
- by a command_inout_asynch() method with a read_attribute_reply() attribute).
+ This error occurs when trying to get result of an asynchronous request with
+ an asynchronous request identifier returned by a non-coherent asynchronous
+ request (For instance, using the asynchronous request identifier returned
+ by a command_inout_asynch() method with a read_attribute_reply() attribute).
.. autoexception:: PyTango.AsynReplyNotArrived
:show-inheritance:
@@ -239,50 +239,50 @@ value for the reason field are :
- a request to get asynchronous reply is made and the reply is not yet arrived
- a blocking wait with timeout for asynchronous reply is made and the timeout expired.
- There is one possible value for the reason field which is API_AsynReplyNotArrived.
+ There is one possible value for the reason field which is API_AsynReplyNotArrived.
.. autoexception:: PyTango.EventSystemFailed
:show-inheritance:
- This exception is thrown by the API layer when subscribing or unsubscribing
- from an event failed. This exception has only one level of Tango::DevError
+ This exception is thrown by the API layer when subscribing or unsubscribing
+ from an event failed. This exception has only one level of Tango::DevError
structure. The possible value for the reason field are :
**API_NotificationServiceFailed**
- This error occurs when the subscribe_event() method failed trying to
- access the CORBA notification service
+ This error occurs when the subscribe_event() method failed trying to
+ access the CORBA notification service
**API_EventNotFound**
- This error occurs when you are using an incorrect event_id in the
- unsubscribe_event() method
+ This error occurs when you are using an incorrect event_id in the
+ unsubscribe_event() method
**API_InvalidArgs**
- This error occurs when NULL pointers are passed to the subscribe or
- unsubscribe event methods
+ This error occurs when NULL pointers are passed to the subscribe or
+ unsubscribe event methods
**API_MethodArgument**
- This error occurs when trying to subscribe to an event which has already
- been subsribed to
+ This error occurs when trying to subscribe to an event which has already
+ been subsribed to
**API_DSFailedRegisteringEvent**
- This error means that the device server to which the device belongs to
- failed when it tries to register the event. Most likely, it means that
- there is no event property defined
+ This error means that the device server to which the device belongs to
+ failed when it tries to register the event. Most likely, it means that
+ there is no event property defined
**API_EventNotFound**
- Occurs when using a wrong event identifier in the unsubscribe_event
- method
+ Occurs when using a wrong event identifier in the unsubscribe_event
+ method
.. autoexception:: PyTango.DeviceUnlocked
:show-inheritance:
- This exception is thrown by the API layer when a device locked by the
- process has been unlocked by an admin client. This exception has two levels
- of Tango::DevError structure. There is only possible value for the reason
+ This exception is thrown by the API layer when a device locked by the
+ process has been unlocked by an admin client. This exception has two levels
+ of Tango::DevError structure. There is only possible value for the reason
field which is
**API_DeviceUnlocked**
- The device has been unlocked by another client (administration client)
+ The device has been unlocked by another client (administration client)
- The first level is the message reported by the Tango kernel from the server
+ The first level is the message reported by the Tango kernel from the server
side. The second layer is added by the client API layer with informations on
- which API call generates the exception and device name.
+ which API call generates the exception and device name.
.. autoexception:: PyTango.NotAllowed
:show-inheritance:
@@ -291,14 +291,12 @@ value for the reason field are :
.. autoexception:: PyTango.NamedDevFailedList
:show-inheritance:
- This exception is only thrown by the DeviceProxy::write_attributes()
- method. In this case, it is necessary to have a new class of exception
- to transfer the error stack for several attribute(s) which failed during
+ This exception is only thrown by the DeviceProxy::write_attributes()
+ method. In this case, it is necessary to have a new class of exception
+ to transfer the error stack for several attribute(s) which failed during
the writing. Therefore, this exception class contains for each attributes
which failed :
- The name of the attribute
- Its index in the vector passed as argumen tof the write_attributes() method
- The error stack
-
-
diff --git a/doc/faq.rst b/doc/faq.rst
index 9d6bb86..2ab7532 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -57,11 +57,11 @@ PyTango3.
Changing your python import from::
import PyTango
-
+
to::
import PyTango3 as PyTango
-
+
should allow you to execute your old PyTango code using the new PyTango 7 library.
Please note that you should as soon as possible migrate the code to Tango 7
@@ -133,7 +133,7 @@ not always the same. The following table summarizes the differences:
| | 2. sequence<str> | 2. list<str> |
+-------------------------+-------------------------------------------+-------------------------------------------+
-Note that starting from PyTango 7 you **cannot assume anything** about the concrete
+Note that starting from PyTango 7 you **cannot assume anything** about the concrete
sequence implementation for the tango array types in PyTango.
This means that the following code (valid in PyTango <= 3.0.4)::
@@ -152,7 +152,7 @@ must be replaced with::
if operator.isSequence(da.value) and not type(da.value) in types.StringTypes:
print "array_attr is NOT a scalar attribute"
-Note that the above example is intended for demonstration purposes only. For
+Note that the above example is intended for demonstration purposes only. For
reference, the proper code would be::
import PyTango
@@ -160,7 +160,7 @@ reference, the proper code would be::
da = dp.read_attribute("array_attr")
if not da.data_format is PyTango.AttrDataFormat.SCALAR:
print "array_attr is NOT a scalar attribute"
-
+
*Server*
@@ -181,19 +181,19 @@ reference, the proper code would be::
- the result of a read_attribute call on a :class:`DeviceProxy` / :class:`Group`
is now a :class:`DeviceAttribute` object
- write_attribute does not accept AttributeValue anymore
-
+
(See :class:`DeviceProxy` API documentation for more details)
-
+
#. command_inout for commands with parameter type DevVar****StringArray don't accept items in second sequence not being strings:
For example, a tango command 'DevVoid Go(DevVarDoubleArray)' in tango 3.0.4
could be executed by calling::
-
+
dev_proxy.command_inout( 'Go', [[1.0, 2.0], [1, 2, 3]] )
-
+
and the second list would internally be converted to ['1', '2', '3'].
- Starting from PyTango 7 this is not allowed anymore. So the above code
+ Starting from PyTango 7 this is not allowed anymore. So the above code
must be changed to::
-
+
dev_proxy.command_inout( 'Go', [[1.0, 2.0], ['1', '2', '3']] )
#. :class:`EventType` enumeration constants changed to match C++ enumeration
@@ -205,7 +205,7 @@ reference, the proper code would be::
- ATTR_CONF_EVENT remains
#. Exception handling
- in 3.0.4 :class:`DevFailed` was a tuple of dictionaries.
+ in 3.0.4 :class:`DevFailed` was a tuple of dictionaries.
Now :class:`DevFailed` is a tuple of :class:`DevError`.
This means that code::
@@ -224,9 +224,9 @@ reference, the proper code would be::
*Optional*
-The following is a list of API improvements. Some where added for performance
-reasons, others to allow for a more pythonic interface, others still to reflect
-more adequately the C++ interface. They are not mandatory since the original
+The following is a list of API improvements. Some where added for performance
+reasons, others to allow for a more pythonic interface, others still to reflect
+more adequately the C++ interface. They are not mandatory since the original
interface will still be available.
**Why is there a "-Wstrict-prototypes" warning when I compile PyTango?**
@@ -235,10 +235,10 @@ interface will still be available.
The PyTango prefered build system (distutils) uses the same flags used to compile
Python to compile PyTango. It happens that Python is compiled as a pure C library
while PyTango is a C++ library. Unfortunately one of the flags used by Python is
-the "-Wstrict-prototypes" which makes sence in a C compilation but not in a C++
+the "-Wstrict-prototypes" which makes sence in a C compilation but not in a C++
compilation.
For reference here is the complete error message you may have:
-
+
`cc1plus: warning: command line option "-Wstrict-prototypes" is valid for Ada/C/ObjC but not for C++`
Do not worry about this warning since the compiler is ignoring the presence of this flag
@@ -256,4 +256,3 @@ you should see many warnings of type:
`(WARNING/2) error while formatting signature for PyTango.Device_4Impl.always_executed_hook: **arg is not a Python function**`
Do not worry since sphinx is able to generate the proper documentation.
-
diff --git a/doc/howto.rst b/doc/howto.rst
index b3b582d..95b46f5 100644
--- a/doc/howto.rst
+++ b/doc/howto.rst
@@ -16,16 +16,16 @@ list can be found `here <http://www.tango-controls.org/resources/howto>`_.
Check the default TANGO host
----------------------------
-The default TANGO host can be defined using the environment variable
+The default TANGO host can be defined using the environment variable
:envvar:`TANGO_HOST` or in a `tangorc` file
(see `Tango environment variables <http://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/ds_prog/node11.html#SECTION0011123000000000000000>`_
for complete information)
To check what is the current value that TANGO uses for the default configuration
simple do::
-
- >>> import PyTango
- >>> PyTango.ApiUtil.get_env_var("TANGO_HOST")
+
+ >>> import tango
+ >>> tango.ApiUtil.get_env_var("TANGO_HOST")
'homer.simpson.com:10000'
Check TANGO version
@@ -34,18 +34,18 @@ Check TANGO version
There are two library versions you might be interested in checking:
The PyTango version::
- >>> import PyTango
- >>> PyTango.__version__
- '8.1.1'
+ >>> import tango
+ >>> tango.__version__
+ '9.2.0'
- >>> PyTango.__version_info__
- (8, 1, 1, 'final', 0)
+ >>> tango.__version_info__
+ (9, 2, 0, 'b', 1)
... and the Tango C++ library version that PyTango was compiled with::
- >>> import PyTango
- >>> PyTango.constants.TgLibVers
- '8.1.2'
+ >>> import tango
+ >>> tango.constants.TgLibVers
+ '9.2.0'
Report a bug
@@ -74,7 +74,7 @@ determine if it is running or not::
# ping it
print(tango_test.ping())
-
+
# get the state
print(tango_test.state())
@@ -94,7 +94,7 @@ Basic read/write attribute operations::
scalar = tango_test.read_attribute("long_scalar")
print("Long_scalar value = {0}".format(scalar.value))
- # PyTango provides a shorter way:
+ # PyTango provides a shorter way:
scalar = tango_test.long_scalar.value
print("Long_scalar value = {0}".format(scalar))
@@ -107,7 +107,7 @@ Basic read/write attribute operations::
scalar_value = 18
tango_test.write_attribute("long_scalar", scalar_value)
- # PyTango provides a shorter way:
+ # PyTango provides a shorter way:
tango_test.long_scalar = scalar_value
# Write a spectrum attribute
@@ -147,7 +147,7 @@ Execute commands
----------------
As you can see in the following example, when scalar types are used, the Tango
-binding automagically manages the data types, and writing scripts is quite easy::
+binding automagically manages the data types, and writing scripts is quite easy::
from PyTango import DeviceProxy
@@ -182,7 +182,7 @@ structures::
print("Creating proxy to TangoTest device...")
tango_test = DeviceProxy("sys/tg_test/1")
- # The input argument is a DevVarLongStringArray so create the argin
+ # The input argument is a DevVarLongStringArray so create the argin
# variable containing an array of longs and an array of strings
argin = ([1,2,3], ["Hello", "TangoTest device"])
@@ -192,13 +192,13 @@ structures::
Work with Groups
----------------
-.. todo::
+.. todo::
write this how to
Handle errors
-------------
-.. todo::
+.. todo::
write this how to
.. _pytango-howto-server:
@@ -294,7 +294,7 @@ This chapter does not explain what a Tango device or a device server is.
This is explained in details in the
`Tango control system manual <http://www.tango-controls.org/resources/documentation/kernel/>`_
-Since version 8.1, PyTango provides a helper module which simplifies the
+Since version 8.1, PyTango provides a helper module which simplifies the
development of a Tango device server. This helper is provided through the
:mod:`PyTango.server` module.
@@ -303,7 +303,7 @@ high level API
.. code-block:: python
:linenos:
-
+
import time
from PyTango.server import run
from PyTango.server import Device, DeviceMeta
@@ -337,7 +337,7 @@ high level API
import the necessary symbols
**line 7**
- tango device class definition. A Tango device must inherit from
+ tango device class definition. A Tango device must inherit from
:class:`PyTango.server.Device`
**line 8**
@@ -346,7 +346,7 @@ high level API
on boost-python
**line 10-12**
- definition of the *time* attribute. By default, attributes are double, scalar,
+ definition of the *time* attribute. By default, attributes are double, scalar,
read-only. Check the :class:`~PyTango.server.attribute` for the complete
list of attribute options.
@@ -398,11 +398,11 @@ using the high level API. The example contains:
min_warning=0.5, max_warning=8.0,
fget="get_current", fset="set_current",
doc="the power supply current")
-
+
noise = attribute(label="Noise", dtype=((float,),),
max_dim_x=1024, max_dim_y=1024,
fget="get_noise")
-
+
host = device_property(dtype=str)
port = class_property(dtype=int, default_value=9788)
@@ -413,10 +413,10 @@ using the high level API. The example contains:
def get_current(self):
return 2.3456, time(), AttrQuality.ATTR_WARNING
-
+
def set_current(self, current):
print("Current set to %f" % current)
-
+
def get_noise(self):
return random_sample((1024, 1024))
@@ -432,9 +432,9 @@ using the high level API. The example contains:
.. note::
the ``__metaclass__`` statement is mandatory due to a limitation in the
*boost-python* library used by PyTango.
-
+
If you are using python 3 you can write instead::
-
+
class PowerSupply(Device, metaclass=DeviceMeta)
pass
@@ -457,9 +457,9 @@ by starting it with the verbose option. Example::
python PyDsExp.py PyDs1 -v4
-This activates the console tango logging target and filters messages with
+This activates the console tango logging target and filters messages with
importance level DEBUG or more.
-The links above provided detailed information on how to configure log levels
+The links above provided detailed information on how to configure log levels
and log targets. In this document we will focus on how to write log messages on
your device server.
@@ -479,7 +479,7 @@ Example::
def read_voltage(self):
self.info_stream("read voltage attribute")
- # ...
+ # ...
return voltage_value
This will print a message like::
@@ -551,7 +551,7 @@ The decorators receive three optional arguments:
* show_ret - shows return value in log message (defaults to False)
Example::
-
+
@PyTango.DebugIt(show_args=True, show_ret=True)
def IOLong(self, in_data):
return in_data * 2
@@ -572,7 +572,7 @@ separated python files: A :class:`PLC` class in a :file:`PLC.py`::
# PLC.py
from PyTango.server import Device, DeviceMeta, run
-
+
class PLC(Device):
__metaclass__ = DeviceMeta
@@ -586,7 +586,7 @@ separated python files: A :class:`PLC` class in a :file:`PLC.py`::
# IRMirror.py
from PyTango.server import Device, DeviceMeta, run
-
+
class IRMirror(Device):
__metaclass__ = DeviceMeta
@@ -611,23 +611,23 @@ It is also possible to add C++ Tango class in a Python device server as soon as:
1. The Tango class is in a shared library
2. It exist a C function to create the Tango class
-For a Tango class called MyTgClass, the shared library has to be called
-MyTgClass.so and has to be in a directory listed in the LD_LIBRARY_PATH
-environment variable. The C function creating the Tango class has to be called
-_create_MyTgClass_class() and has to take one parameter of type "char \*" which
-is the Tango class name. Here is an example of the main function of the same
+For a Tango class called MyTgClass, the shared library has to be called
+MyTgClass.so and has to be in a directory listed in the LD_LIBRARY_PATH
+environment variable. The C function creating the Tango class has to be called
+_create_MyTgClass_class() and has to take one parameter of type "char \*" which
+is the Tango class name. Here is an example of the main function of the same
device server than before but with one C++ Tango class called SerialLine::
- import PyTango
+ import tango
import sys
-
+
if __name__ == '__main__':
- py = PyTango.Util(sys.argv)
+ py = tango.Util(sys.argv)
util.add_class('SerialLine', 'SerialLine', language="c++")
util.add_class(PLCClass, PLC, 'PLC')
util.add_class(IRMirrorClass, IRMirror, 'IRMirror')
-
- U = PyTango.Util.instance()
+
+ U = tango.Util.instance()
U.server_init()
U.server_run()
@@ -637,24 +637,24 @@ device server than before but with one C++ Tango class called SerialLine::
Create attributes dynamically
-----------------------------
-It is also possible to create dynamic attributes within a Python device server.
-There are several ways to create dynamic attributes. One of the way, is to
+It is also possible to create dynamic attributes within a Python device server.
+There are several ways to create dynamic attributes. One of the way, is to
create all the devices within a loop, then to create the dynamic attributes and
finally to make all the devices available for the external world. In C++ device
server, this is typically done within the <Device>Class::device_factory() method.
In Python device server, this method is generic and the user does not have one.
Nevertheless, this generic device_factory method calls a method named dyn_attr()
allowing the user to create his dynamic attributes. It is simply necessary to
-re-define this method within your <Device>Class and to create the dynamic
+re-define this method within your <Device>Class and to create the dynamic
attribute within this method:
``dyn_attr(self, dev_list)``
-
- where dev_list is a list containing all the devices created by the
+
+ where dev_list is a list containing all the devices created by the
generic device_factory() method.
-There is another point to be noted regarding dynamic attribute within Python
-device server. The Tango Python device server core checks that for each
+There is another point to be noted regarding dynamic attribute within Python
+device server. The Tango Python device server core checks that for each
attribute it exists methods named <attribute_name>_read and/or
<attribute_name>_write and/or is_<attribute_name>_allowed. Using dynamic
attribute, it is not possible to define these methods because attributes name
@@ -663,23 +663,23 @@ To address this issue, the Device_3Impl::add_attribute() method has a diferent
signature for Python device server which is:
``add_attribute(self, attr, r_meth = None, w_meth = None, is_allo_meth = None)``
-
-attr is an instance of the Attr class, r_meth is the method which has to be
-executed with the attribute is read, w_meth is the method to be executed
+
+attr is an instance of the Attr class, r_meth is the method which has to be
+executed with the attribute is read, w_meth is the method to be executed
when the attribute is written and is_allo_meth is the method to be executed
to implement the attribute state machine. The method passed here as argument
-as to be class method and not object method. Which argument you have to use
-depends on the type of the attribute (A WRITE attribute does not need a
+as to be class method and not object method. Which argument you have to use
+depends on the type of the attribute (A WRITE attribute does not need a
read method). Note, that depending on the number of argument you pass to this
-method, you may have to use Python keyword argument. The necessary methods
+method, you may have to use Python keyword argument. The necessary methods
required by the Tango Python device server core will be created automatically
as a forward to the methods given as arguments.
-Here is an example of a device which has a TANGO command called
+Here is an example of a device which has a TANGO command called
*createFloatAttribute*. When called, this command creates a new scalar floating
point attribute with the specified name::
-
+
from PyTango import Util, Attr
from PyTango.server import DeviceMeta, Device, command
@@ -688,7 +688,7 @@ point attribute with the specified name::
@command(dtype_in=str)
def CreateFloatAttribute(self, attr_name):
- attr = Attr(attr_name, PyTango.DevDouble)
+ attr = Attr(attr_name, PyTango.DevDouble)
self.add_attribute(attr, self.read_General, self.write_General)
def read_General(self, attr):
@@ -720,9 +720,9 @@ Dynamic device from a known tango class name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you know the tango class name but you don't have access to the :class:`PyTango.DeviceClass`
-(or you are too lazy to search how to get it ;-) the way to do it is call
+(or you are too lazy to search how to get it ;-) the way to do it is call
:meth:`~PyTango.Util.create_device` / :meth:`~PyTango.Util.delete_device`.
-Here is an example of implementing a tango command on one of your devices that
+Here is an example of implementing a tango command on one of your devices that
creates a device of some arbitrary class (the example assumes the tango commands
'CreateDevice' and 'DeleteDevice' receive a parameter of type DevVarStringArray
with two strings. No error processing was done on the code for simplicity sake)::
@@ -738,7 +738,7 @@ with two strings. No error processing was done on the code for simplicity sake):
klass_name, dev_name = pars
util = Util.instance()
util.create_device(klass_name, dev_name, alias=None, cb=None)
-
+
@command(dtype_in=[str])
def DeleteDevice(self, pars):
klass_name, dev_name = pars
@@ -756,27 +756,27 @@ Dynamic device from a known tango class
If you already have access to the :class:`~PyTango.DeviceClass` object that
corresponds to the tango class of the device to be created you can call directly
the :meth:`~PyTango.DeviceClass.create_device` / :meth:`~PyTango.DeviceClass.delete_device`.
-For example, if you wish to create a clone of your device, you can create a
+For example, if you wish to create a clone of your device, you can create a
tango command called *Clone*::
class MyDevice(PyTango.Device_4Impl):
-
+
def fill_new_device_properties(self, dev_name):
prop_names = db.get_device_property_list(self.get_name(), "*")
prop_values = db.get_device_property(self.get_name(), prop_names.value_string)
db.put_device_property(dev_name, prop_values)
-
+
# do the same for attributes...
- ...
-
+ ...
+
def Clone(self, dev_name):
klass = self.get_device_class()
klass.create_device(dev_name, alias=None, cb=self.fill_new_device_properties)
-
+
def DeleteSibling(self, dev_name):
klass = self.get_device_class()
klass.delete_device(dev_name)
-
+
Note that the cb parameter is optional. In the example it is given for
demonstration purposes only.
@@ -788,7 +788,7 @@ Write a server (original API)
This chapter describes how to develop a PyTango device server using the
original PyTango server API. This API mimics the C++ API and is considered
low level.
-You should write a server using this API if you are using code generated by
+You should write a server using this API if you are using code generated by
`Pogo tool <http://www.esrf.eu/computing/cs/tango/tango_doc/tools_doc/pogo_doc/index.html>`_
or if for some reason the high level API helper doesn't provide a feature
you need (in that case think of writing a mail to tango mailing list explaining
@@ -811,7 +811,7 @@ The following is a typical code for this main function::
if __name__ == '__main__':
util = PyTango.Util(sys.argv)
util.add_class(PyDsExpClass, PyDsExp)
-
+
U = PyTango.Util.instance()
U.server_init()
U.server_run()
@@ -820,10 +820,10 @@ The following is a typical code for this main function::
Create the Util object passing it the interpreter command line arguments
**Line 3**
Add the Tango class *PyDsExp* to the device server. The :meth:`Util.add_class`
- method of the Util class has two arguments which are the Tango class
+ method of the Util class has two arguments which are the Tango class
PyDsExpClass instance and the Tango PyDsExp instance.
- This :meth:`Util.add_class` method is only available since version
- 7.1.2. If you are using an older version please use
+ This :meth:`Util.add_class` method is only available since version
+ 7.1.2. If you are using an older version please use
:meth:`Util.add_TgClass` instead.
**Line 7**
Initialize the Tango device server
@@ -860,22 +860,22 @@ In our example, the code of this Python class looks like::
PyTango.AttrWriteType.READ_WRITE ] ]
}
-
-**Line 1**
+
+**Line 1**
The PyDsExpClass class has to inherit from the :class:`DeviceClass` class
-
+
**Line 3 to 7**
- Definition of the cmd_list :class:`dict` defining commands. The *IOLong* command
- is defined at lines 3 and 4. The *IOStringArray* command is defined in
+ Definition of the cmd_list :class:`dict` defining commands. The *IOLong* command
+ is defined at lines 3 and 4. The *IOStringArray* command is defined in
lines 5 and 6
**Line 9 to 17**
Definition of the attr_list :class:`dict` defining attributes. The *Long_attr*
- attribute is defined at lines 9 to 12 and the *Short_attr_rw* attribute is
+ attribute is defined at lines 9 to 12 and the *Short_attr_rw* attribute is
defined at lines 14 to 16
-
+
If you have something specific to do in the class constructor like
-initializing some specific data member, you will have to code a class
+initializing some specific data member, you will have to code a class
constructor. An example of such a contructor is ::
def __init__(self, name):
@@ -892,7 +892,7 @@ called *cmd_list* as a data member of the xxxClass class of the Tango class.
This :class:`dict` has one element per command. The element key is the command
name. The element value is a python list which defines the command. The generic
form of a command definition is:
-
+
``'cmd_name' : [ [in_type, <"In desc">], [out_type, <"Out desc">], <{opt parameters}>]``
The first element of the value list is itself a list with the command input
@@ -921,7 +921,7 @@ As shown in the previous example, attributes have to be defined in a :class:`dic
called **attr_list** as a data
member of the xxxClass class of the Tango class. This :class:`dict` has one element
per attribute. The element key is the attribute name. The element value is a
-python :class:`list` which defines the attribute. The generic form of an
+python :class:`list` which defines the attribute. The generic form of an
attribute definition is:
``'attr_name' : [ [mandatory parameters], <{opt parameters}>]``
@@ -929,7 +929,7 @@ attribute definition is:
For any kind of attributes, the mandatory parameters are:
``[attr data type, attr data format, attr data R/W type]``
-
+
The attribute data type is one of the possible value for attributes of the
:class:`PyTango.ArgType` pseudo enunmeration. The attribute data format is one
of the possible value of the :class:`PyTango.AttrDataFormat` pseudo enumeration
@@ -1117,7 +1117,7 @@ In our example, the code of this class looks like::
General methods
###############
-The following array summarizes how the general methods we have in a Tango
+The following array summarizes how the general methods we have in a Tango
device server are implemented in Python.
+----------------------+-------------------------+-------------+-----------+
@@ -1137,14 +1137,14 @@ device server are implemented in Python.
Implementing a command
######################
-Commands are defined as described above. Nevertheless, some methods implementing
-them have to be written. These methods names are fixed and depend on command
+Commands are defined as described above. Nevertheless, some methods implementing
+them have to be written. These methods names are fixed and depend on command
name. They have to be called:
- ``is_<Cmd_name>_allowed(self)``
- ``<Cmd_name>(self, arg)``
-For instance, with a command called *MyCmd*, its is_allowed method has to be
+For instance, with a command called *MyCmd*, its is_allowed method has to be
called `is_MyCmd_allowed` and its execution method has to be called simply *MyCmd*.
The following array gives some more info on these methods.
@@ -1186,20 +1186,20 @@ calls a command named IOLong::
more information about PyTango log system).
**Line 9**
return the output of executing the tango command
-
+
Implementing an attribute
#########################
Attributes are defined as described in chapter 5.3.2. Nevertheless, some methods
-implementing them have to be written. These methods names are fixed and depend
+implementing them have to be written. These methods names are fixed and depend
on attribute name. They have to be called:
- ``is_<Attr_name>_allowed(self, req_type)``
- ``read_<Attr_name>(self, attr)``
- ``write_<Attr_name>(self, attr)``
-For instance, with an attribute called *MyAttr*, its is_allowed method has to be
-called *is_MyAttr_allowed*, its read method has to be called *read_MyAttr* and
+For instance, with an attribute called *MyAttr*, its is_allowed method has to be
+called *is_MyAttr_allowed*, its read method has to be called *read_MyAttr* and
its write method has to be called *write_MyAttr*.
The *attr* parameter is an instance of :class:`Attr`.
Unlike the commands, the is_allowed method for attributes receives a parameter
@@ -1210,7 +1210,7 @@ that can be used in attribute.
The following code is an example of how you write code executed when a client
read an attribute which is called *Long_attr*::
-
+
def read_Long_attr(self, the_att):
self.info_stream("read attribute name Long_attr")
the_att.set_value(self.attr_long)
@@ -1222,10 +1222,10 @@ read an attribute which is called *Long_attr*::
write a log message to the tango INFO stream (click :ref:`here <logging>`
for more information about PyTango log system).
**Line 3**
- Set the attribute value using the method set_value() with the attribute
+ Set the attribute value using the method set_value() with the attribute
value as parameter.
-
-The following code is an example of how you write code executed when a client
+
+The following code is an example of how you write code executed when a client
write the Short_attr_rw attribute::
def write_Short_attr_rw(self,the_att):
@@ -1233,14 +1233,12 @@ write the Short_attr_rw attribute::
self.attr_short_rw = the_att.get_write_value(data)
**Line 1**
- Method declaration with "the_att" being an instance of the Attribute
+ Method declaration with "the_att" being an instance of the Attribute
class representing the Short_attr_rw attribute
**Line 2**
write a log message to the tango INFO stream (click :ref:`here <logging>` for
more information about PyTango log system).
**Line 3**
Get the value sent by the client using the method get_write_value() and
- store the value written in the device object. Our attribute is a scalar
+ store the value written in the device object. Our attribute is a scalar
short attribute so the return value is an int
-
-
diff --git a/doc/quicktour.rst b/doc/quicktour.rst
index d4380f1..d0627b9 100644
--- a/doc/quicktour.rst
+++ b/doc/quicktour.rst
@@ -12,13 +12,13 @@ Before you begin there are some fundamental TANGO concepts you should be aware o
Tango consists basically of a set of *devices* running somewhere on the network.
-A device is identified by a unique case insensitive name in the format
-*<domain>/<family>/<member>*. Examples: `LAB-01/PowerSupply/01`,
-`ID21/OpticsHutch/energy`.
+A device is identified by a unique case insensitive name in the format
+*<domain>/<family>/<member>*. Examples: `LAB-01/PowerSupply/01`,
+`ID21/OpticsHutch/energy`.
Each device has a series of *attributes*, *pipes*, *properties* and *commands*.
-An attribute is identified by a name in a device. It has a value that can
+An attribute is identified by a name in a device. It has a value that can
be read. Some attributes can also be changed (read-write attributes). Each
attribute has a well known, fixed data type.
@@ -26,18 +26,18 @@ A pipe is a kind of attribute. Unlike attributes, the pipe data type is strucure
(in the sence of C struct) and it is dynamic.
A property is identified by a name in a device. Usually, devices properties are
-used to provide a way to configure a device.
+used to provide a way to configure a device.
A command is also identified by a name. A command may or not receive a parameter
and may or not return a value when it is executed.
Any device has **at least** a *State* and *Status* attributes and *State*,
-*Status* and *Init* commands. Reading the *State* or *Status* attributes has
+*Status* and *Init* commands. Reading the *State* or *Status* attributes has
the same effect as executing the *State* or *Status* commands.
-Each device as an associated *TANGO Class*. Most of the times the TANGO class
+Each device as an associated *TANGO Class*. Most of the times the TANGO class
has the same name as the object oriented programming class which implements it
-but that is not mandatory.
+but that is not mandatory.
TANGO devices *live* inside a operating system process called *TANGO Device Server*.
This server acts as a container of devices. A device server can host multiple
@@ -45,8 +45,8 @@ devices of multiple TANGO classes. Devices are, therefore, only accessible when
the corresponding TANGO Device Server is running.
A special TANGO device server called the *TANGO Database Server* will act as
-a naming service between TANGO servers and clients. This server has a known
-address where it can be reached. The machines that run TANGO Device Servers
+a naming service between TANGO servers and clients. This server has a known
+address where it can be reached. The machines that run TANGO Device Servers
and/or TANGO clients, should export an environment variable called
:envvar:`TANGO_HOST` that points to the TANGO Database server address. Example:
``TANGO_HOST=homer.lab.eu:10000``
@@ -59,22 +59,22 @@ This chapter assumes you have already installed PyTango.
To explore PyTango you should have a running Tango system. If you are working in
a facility/institute that uses Tango, this has probably already been prepared
for you. You need to ask your facility/institute tango contact for the
-:envvar:`TANGO_HOST` variable where Tango system is running.
+:envvar:`TANGO_HOST` variable where Tango system is running.
If you are working in an isolate machine you first need to make sure the Tango
system is installed and running (see `tango how to <http://www.tango-controls.org/resources/howto>`_).
-Most examples here connect to a device called *sys/tg_test/1* that runs in a
+Most examples here connect to a device called *sys/tg_test/1* that runs in a
TANGO server called *TangoTest* with the instance name *test*.
This server comes with the TANGO installation. The TANGO installation
-also registers the *test* instance. All you have to do is start the TangoTest
+also registers the *test* instance. All you have to do is start the TangoTest
server on a console::
$ TangoTest test
Ready to accept request
.. note::
- if you receive a message saying that the server is already running,
+ if you receive a message saying that the server is already running,
it just means that somebody has already started the test server so you don't
need to do anything.
@@ -85,11 +85,11 @@ Finally you can get your hands dirty. The first thing to do is start a python
console and import the :mod:`PyTango` module. The following example shows
how to create a proxy to an existing TANGO device, how to read and write
attributes and execute commands from a python console::
-
- >>> import PyTango
-
- >>> # create a device object
- >>> test_device = PyTango.DeviceProxy("sys/tg_test/1")
+
+ >>> import tango
+
+ >>> # create a device object
+ >>> test_device = tango.DeviceProxy("sys/tg_test/1")
>>> # every device has a state and status which can be checked with:
>>> print(test_device.state())
@@ -104,7 +104,7 @@ attributes and execute commands from a python console::
>>> # ...PyTango provides a shortcut to do the same:
>>> data = test_device["long_scalar"]
- >>> # the result of reading an attribute is a DeviceAttribute python object.
+ >>> # the result of reading an attribute is a DeviceAttribute python object.
>>> # It has a member called "value" which contains the value of the attribute
>>> data.value
136
@@ -132,7 +132,7 @@ attributes and execute commands from a python console::
>>> # PyTango provides a handy pythonic shortcut to read the attribute value:
>>> test_device.long_scalar
- 136
+ 136
>>> # Setting an attribute value is equally easy:
>>> test_device.write_attribute("long_scalar", 8776)
@@ -140,7 +140,7 @@ attributes and execute commands from a python console::
>>> # ... and a handy shortcut to do the same exists as well:
>>> test_device.long_scalar = 8776
- >>> # TangoTest has a command called "DevDouble" which receives a number
+ >>> # TangoTest has a command called "DevDouble" which receives a number
>>> # as parameter and returns the same number as a result. Let's
>>> # execute this command:
>>> test_device.command_inout("DevDouble", 45.67)
@@ -153,11 +153,11 @@ attributes and execute commands from a python console::
>>> # Introspection: check the list of attributes:
>>> test_device.get_attribute_list()
['ampli', 'boolean_scalar', 'double_scalar', '...', 'State', 'Status']
-
- >>>
+
+ >>>
This is just the tip of the iceberg. Check the :class:`~PyTango.DeviceProxy` for
-the complete API.
+the complete API.
PyTango comes with an integrated IPython_ based console called :ref:`itango`.
It provides helpers to simplify console usage. You can use this console instead
@@ -175,7 +175,7 @@ Before creating a server you need to decide:
1. The name of the device server (example: `PowerSupplyDS`). This will be
the mandatory name of your python file.
-2. The Tango Class name of your device (example: `PowerSupply`). In our
+2. The Tango Class name of your device (example: `PowerSupply`). In our
example we will use the same name as the python class name.
3. the list of attributes of the device, their data type, access (read-only vs
read-write), data_format (scalar, 1D, 2D)
@@ -186,7 +186,7 @@ will be called `PowerSupplyDS`. There will be a class called `PowerSupply`
which will have attributes:
* *voltage* (scalar, read-only, numeric)
-* *current* (scalar, read_write, numeric, expert mode)
+* *current* (scalar, read_write, numeric, expert mode)
* *noise* (2D, read-only, numeric)
pipes:
@@ -220,14 +220,14 @@ You can do it with Jive (`Jive->Edit->Create server`):
... or in a python script::
- >>> import PyTango
-
- >>> dev_info = PyTango.DbDevInfo()
+ >>> import tango
+
+ >>> dev_info = tango.DbDevInfo()
>>> dev_info.server = "PowerSupplyDS/test"
>>> dev_info._class = "PowerSupply"
>>> dev_info.name = "test/power_supply/1"
-
- >>> db = PyTango.Database()
+
+ >>> db = tango.Database()
>>> db.add_device(dev_info)
After, you can run the server on a console with::
@@ -237,23 +237,22 @@ After, you can run the server on a console with::
Now you can access it from a python console::
- >>> import PyTango
+ >>> import tango
- >>> power_supply = PyTango.DeviceProxy("test/power/supply/1")
+ >>> power_supply = tango.DeviceProxy("test/power/supply/1")
>>> power_supply.state()
STANDBY
>>> power_supply.current = 2.3
-
+
>>> power_supply.current
2.3
>>> power_supply.PowerOn()
>>> power_supply.Ramp(2.1)
True
-
+
>>> power_supply.state()
ON
Next steps: Check out the :ref:`pytango-api`.
-
diff --git a/doc/start.rst b/doc/start.rst
index 835334c..2faad75 100644
--- a/doc/start.rst
+++ b/doc/start.rst
@@ -37,7 +37,7 @@ First, make sure you have the following packages already installed (all of them
are available from the major official distribution repositories):
* `boost-python`_ (including boost-python-dev)
-* `numpy`_
+* `numpy`_
* `IPython`_ (optional, highly recommended)
Then install PyTango either from pip:
@@ -61,7 +61,7 @@ PyTango team provides a limited set of binary PyTango distributables for
Windows XP/Vista/7/8. The complete list of binaries can be downloaded from
`PyPI`_.
-Select the proper windows package, download it and finally execute the
+Select the proper windows package, download it and finally execute the
installion wizard.
Compiling
@@ -70,10 +70,10 @@ Compiling
Linux
~~~~~
-Since PyTango 7 the build system used to compile PyTango is the standard python
+Since PyTango 7 the build system used to compile PyTango is the standard python
distutils.
-Besides the binaries for the three dependencies mentioned above, you also need
+Besides the binaries for the three dependencies mentioned above, you also need
the development files for the respective libraries.
You can get the latest ``.tar.gz`` from `PyPI`_ or directly
@@ -92,7 +92,7 @@ version 8.0.0, it will also install :ref:`itango` as an IPython_ extension.
If you whish to install in a different directory, replace the last line with:
.. sourcecode:: console
-
+
$ # private installation to your user (usually ~/.local/lib/python<X>.<Y>/site-packages)
$ python setup.py install --user
@@ -110,11 +110,11 @@ source package under :file:`doc/windows_notes.txt`.
Testing
-------
-To test the installation, import ``PyTango`` and check ``PyTango.Release.version``:
+To test the installation, import ``tango`` and check ``tango.Release.version``:
.. sourcecode:: console
- $ python -c "import PyTango; print(PyTango.Release.version)"
+ $ python -c "import tango; print(tango.Release.version)"
9.2.0
Next steps: Check out the :ref:`pytango-quick-tour`.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/pytango.git
More information about the debian-science-commits
mailing list