[pytango] 385/483: Update documentation
Sandor Bodo-Merle
sbodomerle-guest at moszumanska.debian.org
Thu Sep 28 19:15:03 UTC 2017
This is an automated email from the git hooks/post-receive script.
sbodomerle-guest pushed a commit to annotated tag bliss_8.10
in repository pytango.
commit d6745aa2b052b80624b059cdd53b89274906a5fa
Author: tiagocoutinho <tiagocoutinho at 4e9c00fd-8f2e-0410-aa12-93ce3db5e235>
Date: Thu May 15 12:04:20 2014 +0000
Update documentation
git-svn-id: http://svn.code.sf.net/p/tango-cs/code/bindings/PyTango/trunk@25603 4e9c00fd-8f2e-0410-aa12-93ce3db5e235
---
doc/{itango => _static}/itango00.png | Bin
doc/{itango => _static}/itango01.png | Bin
doc/{itango => _static}/itango02.png | Bin
doc/{itango => _static}/itango03.png | Bin
doc/{itango => _static}/itango04.png | Bin
doc/{itango => _static}/itango05.png | Bin
doc/{itango => _static}/itango06.png | Bin
doc/contents.rst | 3 +-
doc/exception.rst | 22 +-
doc/green.rst | 8 +-
doc/howto.rst | 118 +++++--
doc/itango/features.rst | 40 ---
doc/itango/highlights.rst | 646 -----------------------------------
doc/itango/index.rst | 32 --
doc/quicktour.rst | 4 +-
doc/server_api/server.rst | 2 +
16 files changed, 118 insertions(+), 757 deletions(-)
diff --git a/doc/itango/itango00.png b/doc/_static/itango00.png
similarity index 100%
rename from doc/itango/itango00.png
rename to doc/_static/itango00.png
diff --git a/doc/itango/itango01.png b/doc/_static/itango01.png
similarity index 100%
rename from doc/itango/itango01.png
rename to doc/_static/itango01.png
diff --git a/doc/itango/itango02.png b/doc/_static/itango02.png
similarity index 100%
rename from doc/itango/itango02.png
rename to doc/_static/itango02.png
diff --git a/doc/itango/itango03.png b/doc/_static/itango03.png
similarity index 100%
rename from doc/itango/itango03.png
rename to doc/_static/itango03.png
diff --git a/doc/itango/itango04.png b/doc/_static/itango04.png
similarity index 100%
rename from doc/itango/itango04.png
rename to doc/_static/itango04.png
diff --git a/doc/itango/itango05.png b/doc/_static/itango05.png
similarity index 100%
rename from doc/itango/itango05.png
rename to doc/_static/itango05.png
diff --git a/doc/itango/itango06.png b/doc/_static/itango06.png
similarity index 100%
rename from doc/itango/itango06.png
rename to doc/_static/itango06.png
diff --git a/doc/contents.rst b/doc/contents.rst
index a2e34d8..f17733c 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -9,10 +9,11 @@ Contents
.. toctree::
:maxdepth: 2
+ :titlesonly:
start
quicktour
- itango/index
+ ITango <itango>
green
API <api>
How to <howto>
diff --git a/doc/exception.rst b/doc/exception.rst
index 6f8c2c4..9371d9b 100644
--- a/doc/exception.rst
+++ b/doc/exception.rst
@@ -3,6 +3,8 @@
.. highlight:: python
:linenothreshold: 4
+.. _pytango-exception-api:
+
Exception API
=============
@@ -55,21 +57,21 @@ all of which containing the following kind of key-value pairs:
Throwing exception in a device server
-------------------------------------
-The C++ Tango::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 :
+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 :
-- *throw_exception()* which is a static method
-- *re_throw_exception()* which is also a static method
-- *print_exception()* which is also a static method
+- :meth:`~PyTango.Except.throw_exception` which is a static method
+- :meth:`~PyTango.Except.re_throw_exception` which is also a static method
+- :meth:`~PyTango.Except.print_exception` which is also a static method
-The following code is an example of a command method requesting a command on a sub-device and re-throwing
-the exception in case of::
+The following code is an example of a command method requesting a command on a
+sub-device and re-throwing the exception in case of::
try:
dev.command_inout("SubDevCommand")
- except PyTango.DevFailed, e:
- PyTango.Except.re_throw_exception(e,
+ except PyTango.DevFailed as df:
+ PyTango.Except.re_throw_exception(df,
"MyClass_CommandFailed",
"Sub device command SubdevCommand failed",
"Command()")
diff --git a/doc/green.rst b/doc/green.rst
index eee9a4e..00cbeff 100644
--- a/doc/green.rst
+++ b/doc/green.rst
@@ -1,7 +1,7 @@
.. currentmodule:: PyTango
-Green
------
+Green mode
+----------
PyTango supports cooperative green Tango objects. Since version 8.1 two *green*
modes have been added: :obj:`~PyTango.GreenMode.Futures` and
@@ -13,8 +13,8 @@ The :obj:`~PyTango.GreenMode.Gevent` mode uses the well known gevent_ library.
Currently, in version 8.1, only :class:`DeviceProxy` has been modified to work
in a green cooperative way. If the work is found to be useful, the same can
-be implemented in the future for :class:`AttributeProxy` and even
-to :class:`Database`.
+be implemented in the future for :class:`AttributeProxy`, :class:`Database`,
+:class:`Group` or even in the server side.
You can set the PyTango green mode at a global level. Set the environment
variable :envvar:`PYTANGO_GREEN_MODE` to either *futures* or *gevent*
diff --git a/doc/howto.rst b/doc/howto.rst
index 9bb87c6..2192f87 100644
--- a/doc/howto.rst
+++ b/doc/howto.rst
@@ -9,6 +9,10 @@
How to
======
+This is a small list of how-tos specific to PyTango. A more general Tango how-to
+list can be found `here <http://www.tango-controls.org/howtos>`_.
+
+
Check the default TANGO host
----------------------------
@@ -59,7 +63,7 @@ The PyTango version::
Report a bug
------------
-Bugs can be reported `TANGO Source forge tickets <https://sourceforge.net/p/tango-cs/bugs/>`_.
+Bugs can be reported as tickets in `TANGO Source forge <https://sourceforge.net/p/tango-cs/bugs/>`_.
When making a bug report don't forget to select *PyTango* in **Category**.
@@ -68,6 +72,7 @@ It can be a dump of::
$ python -c "from PyTango.utils import info; print(info())"
+.. _pytango-howto-server:
Write a server
--------------
@@ -82,7 +87,10 @@ development of a Tango device server. This helper is provided through the
:mod:`PyTango.server` module.
Here is a simple example on how to write a *Clock* device server using the
-high level API::
+high level API
+
+.. code-block:: python
+ :linenos:
import time
from PyTango.server import run
@@ -104,10 +112,43 @@ high level API::
if __name__ == "__main__":
- run((Clock,))
+ run([Clock])
+
+
+**line 2-4**
+ import the necessary symbols
+
+**line 7**
+ tango device class definition. A Tango device must inherit from
+ :class:`PyTango.server.Device`
+
+**line 8**
+ mandatory *magic* line. A Tango device must define the metaclass as
+ :class:`PyTango.server.DeviceClass`. This has to be done due to a limitation
+ on boost-python
+
+**line 10**
+ 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
+
+**line 12-13**
+ the method that is called when a client reads the *time* attribute from this
+ device. By default, Tango expects a method called ``read_<attribute name>``
+ to exist for every attribute
+
+**line 15-17**
+ the method *strftime* is exported as a Tango command. In receives a string
+ as argument and it returns a string. If a method is to be exported as a
+ Tango command, it must be decorated as such with the
+ :func:`~PyTango.server.command` decorator
+**line 21**
+ start the Tango run loop. The mandatory argument is a list of python classes
+ that are to be exported as Tango classes. Check :func:`~PyTango.server.run`
+ for the complete list of options
-Here is a more complete example on how to write a *PowerSupply* device server
+Here is a more complete example on how to write a *PowerSupply* device server
using the high level API. The example contains:
#. a read-only double scalar attribute called *voltage*
@@ -123,10 +164,11 @@ using the high level API. The example contains:
from time import time
from numpy.random import random_sample
- from PyTango import AttrQuality, AttrWriteType, DispLevel, server_run
+ from PyTango import AttrQuality, AttrWriteType, DispLevel, run
from PyTango.server import Device, DeviceMeta, attribute, command
from PyTango.server import class_property, device_property
+
class PowerSupply(Device):
__metaclass__ = DeviceMeta
@@ -166,10 +208,10 @@ using the high level API. The example contains:
def ramp(self, value):
print("Ramping up...")
+
if __name__ == "__main__":
- server_run((PowerSupply,))
+ run([PowerSupply])
-*Pretty cool, uh?*
.. note::
the ``__metaclass__`` statement is mandatory due to a limitation in the
@@ -304,27 +346,50 @@ will output something like::
1282221947 [-1261438096] DEBUG test/pydsexp/1 46 <- IOLong()
-Mix multiple device classes (Python and C++) in a server
---------------------------------------------------------
+Multiple device classes (Python and C++) in a server
+----------------------------------------------------
Within the same python interpreter, it is possible to mix several Tango classes.
-Here is an example of the main function of a device server with two Tango classes
-called IRMiror and PLC::
+Let's say two of your colleagues programmed two separate Tango classes in two
+separated python files: A :class:`PLC` class in a :file:`PLC.py`::
- import PyTango
- import sys
+ # PLC.py
- if __name__ == '__main__':
- util = PyTango.Util(sys.argv)
- util.add_class(PLCClass, PLC, 'PLC')
- util.add_class(IRMirrorClass, IRMirror, 'IRMirror')
-
- U = PyTango.Util.instance()
- U.server_init()
- U.server_run()
+ from PyTango.server import Device, DeviceMeta, run
+
+ class PLC(Device):
+ __metaclass__ = DeviceMeta
+
+ # bla, bla my PLC code
-:Line 6: The Tango class PLC is registered in the device server
-:Line 7: The Tango class IRMirror is registered in the device server
+ if __name__ == "__main__":
+ run([PLC])
+
+... and a :class:`IRMirror` in a :file:`IRMirror.py`::
+
+ # IRMirror.py
+
+ from PyTango.server import Device, DeviceMeta, run
+
+ class IRMirror(Device):
+ __metaclass__ = DeviceMeta
+
+ # bla, bla my IRMirror code
+
+ if __name__ == "__main__":
+ run([IRMirror])
+
+You want to create a Tango server called `PLCMirror` that is able to contain
+devices from both PLC and IRMirror classes. All you have to do is write
+a :file:`PLCMirror.py` containing the code::
+
+ # PLCMirror.py
+
+ from PyTango.server import run
+ from PLC import PLC
+ from IRMirror import IRMirror
+
+ run([PLC, IRMirror])
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
@@ -428,6 +493,13 @@ Starting from PyTango 7.1.2 it is possible to create devices in a device server
of a device server that creates devices of (possibly) several other tango classes.
There are two ways to create a new device which are described below.
+Tango imposes a limitation: the tango class(es) of the device(s) that is(are)
+to be created must have been registered before the server starts.
+If you use the high level API, the tango class(es) must be listed in the call
+to :func:`~PyTango.server.run`. If you use the lower level server API, it must
+be done using individual calls to :meth:`~PyTango.Util.add_class`.
+
+
Dynamic device from a known tango class name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/itango/features.rst b/doc/itango/features.rst
deleted file mode 100644
index 8a5b66f..0000000
--- a/doc/itango/features.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-
-.. _itango-features:
-
-Features
-========
-
-ITango works like a normal python console, but it gives you in addition a nice
-set of features from IPython_ like:
-
- - proper (bash-like) command completion
- - automatic expansion of python variables, functions, types
- - command history (with up/down arrow keys, %hist command)
- - help system ( object? syntax, help(object))
- - persistently store your favorite variables
- - color modes
-
-(for a complete list checkout the `IPython web page <http://ipython.org/>`_)
-
-Plus an additional set o Tango_ specific features:
-
- - automatic import of Tango objects to the console namespace (:mod:`PyTango`
- module, :class:`~PyTango.DeviceProxy` (=Device),
- :class:`~PyTango.Database`, :class:`~PyTango.Group`
- and :class:`~PyTango.AttributeProxy` (=Attribute))
- - device name completion
- - attribute name completion
- - automatic tango object member completion
- - list tango devices, classes, servers
- - customized tango error message
- - tango error introspection
- - switch database
- - refresh database
- - list tango devices, classes
- - store favorite tango objects
- - store favorite tango devices
- - tango color modes
-
-Check the :ref:`itango-highlights` to see how to put these feature to good use
-:-)
-
diff --git a/doc/itango/highlights.rst b/doc/itango/highlights.rst
deleted file mode 100644
index cfdd257..0000000
--- a/doc/itango/highlights.rst
+++ /dev/null
@@ -1,646 +0,0 @@
-
-.. currentmodule:: PyTango
-
-.. _itango-highlights:
-
-Highlights
-==========
-
-Tab completion
---------------
-
-ITango exports many tango specific objects to the console namespace.
-These include:
-
- - the PyTango module itself
-
- .. sourcecode:: itango
-
- ITango [1]: PyTango
- Result [1]: <module 'PyTango' from ...>
-
- - The :class:`DeviceProxy` (=Device), :class:`AttributeProxy` (=Attribute),
- :class:`Database` and :class:`Group` classes
-
- .. sourcecode:: itango
-
- ITango [1]: De<tab>
- DeprecationWarning Device DeviceProxy
-
- ITango [2]: Device
- Result [2]: <class 'PyTango._PyTango.DeviceProxy'>
-
- ITango [3]: Device("sys/tg_test/1")
- Result [3]: DeviceProxy(sys/tg_test/1)
-
- ITango [4]: Datab<tab>
-
- ITango [4]: Database
-
- ITango [4]: Att<tab>
- Attribute AttributeError AttributeProxy
-
- - The Tango :class:`Database` object to which the itango session is
- currently connected
-
- .. sourcecode:: itango
-
- ITango [1]: db
- Result [1]: Database(homer, 10000)
-
-Device name completion
-----------------------
-
-ITango knows the complete list of device names (including alias) for the current
-tango database. This means that when you try to create a new Device, by pressing
-<tab> you can see a context sensitive list of devices.
-
-.. sourcecode:: itango
-
- ITango [1]: test = Device("<tab>
- Display all 3654 possibilities? (y or n) n
-
- ITango [1]: test = Device("sys<tab>
- sys/access_control/1 sys/database/2 sys/tautest/1 sys/tg_test/1
-
- ITango [2]: test = Device("sys/tg_test/1")
-
-Attribute name completion
--------------------------
-
-ITango can inspect the list of attributes in case the device server for the device
-where the attribute resides is running.
-
-.. sourcecode:: itango
-
- ITango [1]: short_scalar = Attribute("sys<tab>
- sys/access_control/1/ sys/database/2/ sys/tautest/1/ sys/tg_test/1/
-
- ITango [1]: short_scalar = Attribute("sys/tg_test/1/<tab>
- sys/tg_test/1/State sys/tg_test/1/no_value
- sys/tg_test/1/Status sys/tg_test/1/short_image
- sys/tg_test/1/ampli sys/tg_test/1/short_image_ro
- sys/tg_test/1/boolean_image sys/tg_test/1/short_scalar
- sys/tg_test/1/boolean_image_ro sys/tg_test/1/short_scalar_ro
- sys/tg_test/1/boolean_scalar sys/tg_test/1/short_scalar_rww
- sys/tg_test/1/boolean_spectrum sys/tg_test/1/short_scalar_w
- sys/tg_test/1/boolean_spectrum_ro sys/tg_test/1/short_spectrum
- sys/tg_test/1/double_image sys/tg_test/1/short_spectrum_ro
- sys/tg_test/1/double_image_ro sys/tg_test/1/string_image
- sys/tg_test/1/double_scalar sys/tg_test/1/string_image_ro
- ...
-
- ITango [1]: short_scalar = Attribute("sys/tg_test/1/short_scalar")
-
- ITango [29]: print test.read()
- DeviceAttribute[
- data_format = PyTango._PyTango.AttrDataFormat.SCALAR
- dim_x = 1
- dim_y = 0
- has_failed = False
- is_empty = False
- name = 'short_scalar'
- nb_read = 1
- nb_written = 1
- quality = PyTango._PyTango.AttrQuality.ATTR_VALID
- r_dimension = AttributeDimension(dim_x = 1, dim_y = 0)
- time = TimeVal(tv_nsec = 0, tv_sec = 1279723723, tv_usec = 905598)
- type = PyTango._PyTango.CmdArgType.DevShort
- value = 47
- w_dim_x = 1
- w_dim_y = 0
- w_dimension = AttributeDimension(dim_x = 1, dim_y = 0)
- w_value = 0]
-
-Automatic tango object member completion
-----------------------------------------
-
-When you create a new tango object, (ex.: a device), itango is able to find out
-dynamically which are the members of this device (including tango commands
-and attributes if the device is currently running)
-
-.. sourcecode:: itango
-
- ITango [1]: test = Device("sys/tg_test/1")
-
- ITango [2]: test.<tab>
- Display all 240 possibilities? (y or n)
- ...
- test.DevVoid test.get_access_control
- test.Init test.get_asynch_replies
- test.State test.get_attribute_config
- test.Status test.get_attribute_config_ex
- test.SwitchStates test.get_attribute_list
- ...
-
- ITango [2]: test.short_<tab>
- test.short_image test.short_scalar test.short_scalar_rww test.short_spectrum
- test.short_image_ro test.short_scalar_ro test.short_scalar_w test.short_spectrum_ro
-
- ITango [2]: test.short_scalar # old style: test.read_attribute("short_scalar").value
- Result [2]: 252
-
- ITango [3]: test.Dev<tab>
- test.DevBoolean test.DevUShort test.DevVarShortArray
- test.DevDouble test.DevVarCharArray test.DevVarStringArray
- test.DevFloat test.DevVarDoubleArray test.DevVarULongArray
- test.DevLong test.DevVarDoubleStringArray test.DevVarUShortArray
- test.DevShort test.DevVarFloatArray test.DevVoid
- test.DevString test.DevVarLongArray
- test.DevULong test.DevVarLongStringArray
-
- ITango [3]: test.DevDouble(56.433) # old style: test.command_inout("DevDouble").
- Result [3]: 56.433
-
-Tango classes as :class:`DeviceProxy`
-------------------------------------------------
-
-ITango exports all known tango classes as python alias to :class:`DeviceProxy`.
-This way, if you want to create a device of class which you already know
-(say, Libera, for example) you can do:
-
-.. sourcecode:: itango
-
- ITango [1]: lib01 = Libera("BO01/DI/BPM-01")
-
-One great advantage is that the tango device name completion is sensitive to the
-type of device you want to create. This means that if you are in the middle of
-writting a device name and you press the <tab> key, only devices of the tango
-class 'Libera' will show up as possible completions.
-
-.. sourcecode:: itango
-
- ITango [1]: bpm1 = Libera("<tab>
- BO01/DI/BPM-01 BO01/DI/BPM-09 BO02/DI/BPM-06 BO03/DI/BPM-03 BO03/DI/BPM-11 BO04/DI/BPM-08
- BO01/DI/BPM-02 BO01/DI/BPM-10 BO02/DI/BPM-07 BO03/DI/BPM-04 BO04/DI/BPM-01 BO04/DI/BPM-09
- BO01/DI/BPM-03 BO01/DI/BPM-11 BO02/DI/BPM-08 BO03/DI/BPM-05 BO04/DI/BPM-02 BO04/DI/BPM-10
- BO01/DI/BPM-04 BO02/DI/BPM-01 BO02/DI/BPM-09 BO03/DI/BPM-06 BO04/DI/BPM-03 BO04/DI/BPM-11
- BO01/DI/BPM-05 BO02/DI/BPM-02 BO02/DI/BPM-10 BO03/DI/BPM-07 BO04/DI/BPM-04
- BO01/DI/BPM-06 BO02/DI/BPM-03 BO02/DI/BPM-11 BO03/DI/BPM-08 BO04/DI/BPM-05
- BO01/DI/BPM-07 BO02/DI/BPM-04 BO03/DI/BPM-01 BO03/DI/BPM-09 BO04/DI/BPM-06
- BO01/DI/BPM-08 BO02/DI/BPM-05 BO03/DI/BPM-02 BO03/DI/BPM-10 BO04/DI/BPM-07
-
- ITango [1]: bpm1 = Libera("BO01<tab>
- BO01/DI/BPM-01 BO01/DI/BPM-03 BO01/DI/BPM-05 BO01/DI/BPM-07 BO01/DI/BPM-09 BO01/DI/BPM-11
- BO01/DI/BPM-02 BO01/DI/BPM-04 BO01/DI/BPM-06 BO01/DI/BPM-08 BO01/DI/BPM-10
-
- ITango [1]: bpm1 = Libera("BO01/DI/BPM-01")
-
-Customized device representation
---------------------------------
-
-When you use ipython >= 0.11 with a Qt console frontend::
-
- $ itango qtconsole
-
-typing a variable containing a tango device object followend by :kbd:`Enter`
-will present you with a customized representation of the object instead of the
-usual :func:`repr` :
-
- .. image:: itango06.png
-
-You can customize the icon that itango displays for a specific device.
-The first thing to do is to copy the image file into
-:mod:`PyTango.ipython.resource` installation directory (if you don't have
-permissions to do so, copy the image into a directory of your choosing
-and make sure it is accessible from itango).
-
-If you want to use the image for all devices of a certain tango class, just
-add a new tango class property called *__icon*. You can do it with jive or, of
-course, with itango itself::
-
- db.put_class_property("Libera", dict(__icon="libera.png"))
-
- # if you placed your image in a directory different than PyTango.ipython.resource
- # then, instead you have to specify the absolute directory
-
- db.put_class_property("Libera", dict(__icon="/home/homer/.config/itango/libera.png"))
-
-If you need different images for different devices of the same class, you can
-specify an *__icon* property at the device level (which takes precedence over
-the class property value, if defined)::
-
- db.put_device_property("BO01/DI/BPM-01", dict(__icon="libera2.png"))
-
-
-
-List tango devices, classes, servers
---------------------------------------
-
-ITango provides a set of magic functions (ipython lingo) that allow you to check
-for the list tango devices, classes and servers which are registered in the
-current database.
-
-.. sourcecode:: itango
-
- ITango [1]: lsdev
- Device Alias Server Class
- ---------------------------------------- ------------------------- ------------------------- --------------------
- expchan/BL99_Dummy0DCtrl/1 BL99_0D1 Pool/BL99 ZeroDExpChannel
- simulator/bl98/motor08 Simulator/BL98 SimuMotor
- expchan/BL99_Dummy0DCtrl/3 BL99_0D3 Pool/BL99 ZeroDExpChannel
- expchan/BL99_Dummy0DCtrl/2 BL99_0D2 Pool/BL99 ZeroDExpChannel
- expchan/BL99_Dummy0DCtrl/5 BL99_0D5 Pool/BL99 ZeroDExpChannel
- expchan/BL99_Dummy0DCtrl/4 BL99_0D4 Pool/BL99 ZeroDExpChannel
- expchan/BL99_Dummy0DCtrl/7 BL99_0D7 Pool/BL99 ZeroDExpChannel
- expchan/BL99_Dummy0DCtrl/6 BL99_0D6 Pool/BL99 ZeroDExpChannel
- simulator/bl98/motor01 Simulator/BL98 SimuMotor
- simulator/bl98/motor02 Simulator/BL98 SimuMotor
- simulator/bl98/motor03 Simulator/BL98 SimuMotor
- mg/BL99/_mg_macserv_26065_-1320158352 Pool/BL99 MotorGroup
- simulator/bl98/motor05 Simulator/BL98 SimuMotor
- simulator/bl98/motor06 Simulator/BL98 SimuMotor
- simulator/bl98/motor07 Simulator/BL98 SimuMotor
- simulator/BL98/motctrl01 Simulator/BL98 SimuMotorCtrl
- expchan/BL99_Simu0DCtrl1/1 BL99_0D8 Pool/BL99 ZeroDExpChannel
- expchan/BL99_UxTimerCtrl1/1 BL99_Timer Pool/BL99 CTExpChannel
- ...
-
- ITango [1]: lsdevclass
- SimuCoTiCtrl TangoAccessControl ZeroDExpChannel
- Door Motor DataBase
- MotorGroup IORegister SimuMotorCtrl
- TangoTest MacroServer TauTest
- SimuMotor SimuCounterEx MeasurementGroup
- Pool CTExpChannel
-
- ITango [1]: lsserv
- MacroServer/BL99 MacroServer/BL98 Pool/V2
- Pool/BL99 Pool/BL98 TangoTest/test
- Pool/tcoutinho Simulator/BL98
- TangoAccessControl/1 TauTest/tautest DataBaseds/2
- MacroServer/tcoutinho Simulator/BL99
-
-Customized tango error message and introspection
-----------------------------------------------------
-
-ITango intercepts tango exceptions that occur when you do tango operations
-(ex.: write an attribute with a value outside the allowed limits) and tries to
-display it in a summarized, user friendly way.
-If you need more detailed information about the last tango error, you can use
-the magic command 'tango_error'.
-
-.. sourcecode:: itango
-
- ITango [1]: test = Device("sys/tg_test/1")
-
- ITango [2]: test.no_value
- API_AttrValueNotSet : Read value for attribute no_value has not been updated
- For more detailed information type: tango_error
-
- ITango [3]: tango_error
- Last tango error:
- DevFailed[
- DevError[
- desc = 'Read value for attribute no_value has not been updated'
- origin = 'Device_3Impl::read_attributes_no_except'
- reason = 'API_AttrValueNotSet'
- severity = PyTango._PyTango.ErrSeverity.ERR]
- DevError[
- desc = 'Failed to read_attribute on device sys/tg_test/1, attribute no_value'
- origin = 'DeviceProxy::read_attribute()'
- reason = 'API_AttributeFailed'
- severity = PyTango._PyTango.ErrSeverity.ERR]]
-
-Switching database
----------------------
-
-You can switch database simply by executing the 'switchdb <host> [<port>]' magic
-command.
-
-.. sourcecode:: itango
-
- ITango [1]: switchdb
-
- Must give new database name in format <host>[:<port>].
- <port> is optional. If not given it defaults to 10000.
-
- Examples:
- switchdb homer:10005
- switchdb homer 10005
- switchdb homer
-
- ITango [2]: db
- Database(homer, 10000)
-
- ITango [3]: switchdb bart # by default port is 10000
-
- ITango [4]: db
- Database(bart, 10000)
-
- ITango [5]: switchdb lisa 10005 # you can use spaces between host and port
-
- ITango [6]: db
- Database(lisa, 10005)
-
- ITango [7]: switchdb marge:10005 # or the traditional ':'
-
- ITango [8]: db
- Database(marge, 10005)
-
-Refreshing the database
---------------------------
-
-When itango starts up or when the database is switched, a query is made to the
-tango Database device server which provides all necessary data. This
-data is stored locally in a itango cache which is used to provide all the nice
-features.
-If the Database server is changed in some way (ex: a new device server is registered),
-the local database cache is not consistent anymore with the tango database.
-Therefore, itango provides a magic command 'refreshdb' that allows you to reread
-all tango information from the database.
-
-.. sourcecode:: itango
-
- ITango [1]: refreshdb
-
-Storing your favorite tango objects for later usage
--------------------------------------------------------
-
-.. note::
- This feature is not available if you have installed IPython 0.11!
-
-Since version 7.1.2, :class:`DeviceProxy`, :class:`AttributeProxy` and
-:class:`Database` became pickable.
-This means that they can be used by the IPython_ 'store' magic command (type
-'store?' on the itango console to get information on how to use this command).
-You can, for example, assign your favorite devices in local python variables and
-then store these for the next time you startup IPython_ with itango profile.
-
-.. sourcecode:: itango
-
- ITango [1]: theta = Motor("BL99_M1") # notice how we used tango alias
-
- ITango [2]: store theta
- Stored 'theta' (DeviceProxy)
-
- ITango [3]: Ctrl+D
-
- (IPython session is closed and started again...)
-
- ITango [1]: store -r # in some versions of IPython you may need to do this ...
-
- ITango [1]: print theta
- DeviceProxy(motor/bl99/1)
-
-Adding itango to your own ipython profile
---------------------------------------------
-
-Adding itango to the ipython default profile
-##################################################
-
-Let's assume that you find itango so useful that each time you start ipython, you want
-itango features to be loaded by default.
-The way to do this is by editing your default ipython configuration file:
-
-1. On IPython <= 0.10
-
- $HOME/.ipython/ipy_user_conf.py and add the lines 1 and 7.
-
- .. note::
- The code shown below is a small part of your $HOME/.ipython/ipy_user_conf.py.
- It is shown here only the relevant part for this example.
-
- .. sourcecode:: python
-
- import PyTango.ipython
-
- def main():
-
- # uncomment if you want to get ipython -p sh behaviour
- # without having to use command line switches
- # import ipy_profile_sh
- PyTango.ipython.init_ipython(ip, console=False)
-
-2. On IPython > 0.10
-
- First you have to check which is the configuration directory being used by
- IPython. For this, in an IPython console type:
-
- .. sourcecode:: itango
-
- ITango [1]: import IPython.utils.path
-
- ITango [2]: IPython.utils.path.get_ipython_dir()
- <IPYTHON_DIR>
-
- now edit <IPYTHON_DIR>/profile_default/ipython_config.py and add the
- following line at the end to add itango configuration::
-
- load_subconfig('ipython_config.py', profile='tango')
-
- Alternatively, you could also load itango as an IPython extension::
-
- config = get_config()
- i_shell_app = config.InteractiveShellApp
- extensions = getattr(i_shell_app, 'extensions', [])
- extensions.append('PyTango.ipython')
- i_shell_app.extensions = extensions
-
- for more information on how to configure IPython >= 0.11 please check the
- `IPython configuration <http://ipython.org/ipython-doc/dev/config/ipython.html#configuring-the-ipython-command-line-application>`_
-
-And now, every time you start ipython::
-
- ipython
-
-itango features will also be loaded.
-
-.. sourcecode:: ipython
-
- In [1]: db
- Out[1]: Database(homer, 10000)
-
-
-Adding itango to an existing customized profile
-####################################################
-
-.. note::
- This chapter has a pending update. The contents only apply to
- IPython <= 0.10.
-
-If you have been working with IPython_ before and have already defined a
-customized personal profile, you can extend your profile with itango features
-without breaking your existing options. The trick is to initialize itango extension
-with a parameter that tells itango to maintain the existing options (like colors,
-command line and initial banner).
-
-So, for example, let's say you have created a profile called nuclear, and therefore
-you have a file called $HOME/.ipython/ipy_profile_nuclear.py with the following
-contents:
-
-.. sourcecode:: python
-
- import os
- import IPython.ipapi
-
- def main():
- ip = IPython.ipapi.get()
-
- o = ip.options
- o.banner = "Springfield nuclear powerplant CLI\n\nWelcome Homer Simpson"
- o.colors = "Linux"
- o.prompt_in1 = "Mr. Burns owns you [\\#]: "
-
- main()
-
-In order to have itango features available to this profile you simply need to
-add two lines of code (lines 3 and 7):
-
-.. sourcecode:: python
-
- import os
- import IPython.ipapi
- import PyTango.ipython
-
- def main():
- ip = IPython.ipapi.get()
- PyTango.ipython.init_ipython(ip, console=False)
-
- o = ip.options
- o.banner = "Springfield nuclear powerplant CLI\n\nMr. Burns owns you!"
- o.colors = "Linux"
- o.prompt_in1 = "The Simpsons [\\#]: "
-
- main()
-
-This will load the itango features into your profile while preserving your
-profile's console options (like colors, command line and initial banner).
-
-Creating a profile that extends itango profile
-####################################################
-
-.. note::
- This chapter has a pending update. The contents only apply to
- IPython <= 0.10.
-
-It is also possible to create a profile that includes all itango features and at
-the same time adds new ones. Let's suppose that you want to create a customized
-profile called 'orbit' that automaticaly exports devices of class
-'Libera' for the booster accelerator (assuming you are working on a synchrotron
-like institute ;-).
-Here is the code for the $HOME/.ipython/ipy_profile_orbit.py:
-
-.. sourcecode:: python
-
- import os
- import IPython.ipapi
- import IPython.genutils
- import IPython.ColorANSI
- import PyTango.ipython
- import StringIO
-
- def magic_liberas(ip, p=''):
- """Lists all known Libera devices."""
- data = PyTango.ipython.get_device_map()
- s = StringIO.StringIO()
- cols = 30, 15, 20
- l = "%{0}s %{1}s %{2}s".format(*cols)
- print >>s, l % ("Device", "Alias", "Server")
- print >>s, l % (cols[0]*"-", cols[1]*"-", cols[2]*"-")
- for d, v in data.items():
- if v[2] != 'Libera': continue
- print >>s, l % (d, v[0], v[1])
- s.seek(0)
- IPython.genutils.page(s.read())
-
- def main():
- ip = IPython.ipapi.get()
-
- PyTango.ipython.init_ipython(ip)
-
- o = ip.options
-
- Colors = IPython.ColorANSI.TermColors
- c = dict(Colors.__dict__)
-
- o.banner += "\n{Brown}Welcome to Orbit analysis{Normal}\n".format(**c)
-
- o.prompt_in1 = "Orbit [\\#]: "
- o.colors = "BlueTango"
-
- ip.expose_magic("liberas", magic_liberas)
-
- db = ip.user_ns.get('db')
- dev_class_dict = PyTango.ipython.get_class_map()
-
- if not dev_class_dict.has_key("Libera"):
- return
-
- for libera in dev_class_dict['Libera']:
- domain, family, member = libera.split("/")
- var_name = domain + "_" + member
- var_name = var_name.replace("-","_")
- ip.to_user_ns( { var_name : PyTango.DeviceProxy(libera) } )
-
- main()
-
-Then start your CLI with::
-
- $ ipython --profile=orbit
-
-and you will have something like this
-
-.. image:: itango02.png
-
-Advanced event monitoring
--------------------------
-
-.. note::
- This chapter has a pending update. The contents only apply to
- IPython <= 0.10.
-
-With itango it is possible to monitor change events triggered by any tango
-attribute which has events enabled.
-
-To start monitoring the change events of an attribute:
-
-.. sourcecode:: itango
-
- ITango [1]: mon -a BL99_M1/Position
- 'BL99_M1/Position' is now being monitored. Type 'mon' to see all events
-
-To list all events that have been intercepted:
-
-.. sourcecode:: itango
-
- ITango [2]: mon
- ID Device Attribute Value Quality Time
- ---- ---------------- ------------ ---------------- ------------- ----------------
- 0 motor/bl99/1 state ON ATTR_VALID 17:11:08.026472
- 1 motor/bl99/1 position 190.0 ATTR_VALID 17:11:20.691112
- 2 motor/bl99/1 state MOVING ATTR_VALID 17:12:11.858985
- 3 motor/bl99/1 position 188.954072857 ATTR_CHANGING 17:12:11.987817
- 4 motor/bl99/1 position 186.045533882 ATTR_CHANGING 17:12:12.124448
- 5 motor/bl99/1 position 181.295838155 ATTR_CHANGING 17:12:12.260884
- 6 motor/bl99/1 position 174.55354729 ATTR_CHANGING 17:12:12.400036
- 7 motor/bl99/1 position 166.08870515 ATTR_CHANGING 17:12:12.536387
- 8 motor/bl99/1 position 155.77528943 ATTR_CHANGING 17:12:12.672846
- 9 motor/bl99/1 position 143.358230136 ATTR_CHANGING 17:12:12.811878
- 10 motor/bl99/1 position 131.476140017 ATTR_CHANGING 17:12:12.950391
- 11 motor/bl99/1 position 121.555421781 ATTR_CHANGING 17:12:13.087970
- 12 motor/bl99/1 position 113.457930987 ATTR_CHANGING 17:12:13.226531
- 13 motor/bl99/1 position 107.319423091 ATTR_CHANGING 17:12:13.363559
- 14 motor/bl99/1 position 102.928229946 ATTR_CHANGING 17:12:13.505102
- 15 motor/bl99/1 position 100.584726495 ATTR_CHANGING 17:12:13.640794
- 16 motor/bl99/1 position 100.0 ATTR_ALARM 17:12:13.738136
- 17 motor/bl99/1 state ALARM ATTR_VALID 17:12:13.743481
-
- ITango [3]: mon -l mot.* state
- ID Device Attribute Value Quality Time
- ---- ---------------- ------------ ---------------- ------------- ----------------
- 0 motor/bl99/1 state ON ATTR_VALID 17:11:08.026472
- 2 motor/bl99/1 state MOVING ATTR_VALID 17:12:11.858985
- 17 motor/bl99/1 state ALARM ATTR_VALID 17:12:13.743481
-
-To stop monitoring the attribute:
-
-.. sourcecode:: itango
-
- ITango [1]: mon -d BL99_M1/Position
- Stopped monitoring 'BL99_M1/Position'
-
-.. note::
- Type 'mon?' to see detailed information about this magic command
-
-
diff --git a/doc/itango/index.rst b/doc/itango/index.rst
deleted file mode 100644
index 25f123b..0000000
--- a/doc/itango/index.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-.. highlight:: python
- :linenothreshold: 4
-
-.. _itango:
-
-ITango
-======
-
-ITango is a PyTango CLI based on IPython_. It is designed to be used as an
-IPython profile.
-
-ITango is available since PyTango 7.1.2
-
-You can start ITango by typing on the command line::
-
- $ itango
-
-or the equivalent::
-
- $ ipython --profile=tango
-
-and you should get something like this:
-
-.. image:: itango00.png
- :align: center
- :width: 75%
-
-.. toctree::
- :maxdepth: 1
-
- features
- highlights
diff --git a/doc/quicktour.rst b/doc/quicktour.rst
index fe31e19..cd346a2 100644
--- a/doc/quicktour.rst
+++ b/doc/quicktour.rst
@@ -201,7 +201,9 @@ Here is the code for the :file:`PowerSupplyDS.py`
.. literalinclude:: _static/PowerSupplyDS.py
:linenos:
-The server API :ref:`pytango-hlapi`.
+Check the :ref:`high level server API <pytango-hlapi>` for the complete
+reference API. The :ref:`write a server how to <pytango-howto-server>` can help
+as well.
Before running this brand new server we need to register it in the Tango system.
You can do it with Jive (`Jive->Edit->Create server`):
diff --git a/doc/server_api/server.rst b/doc/server_api/server.rst
index 601af1c..9a3a65b 100644
--- a/doc/server_api/server.rst
+++ b/doc/server_api/server.rst
@@ -6,6 +6,8 @@
High level server API
=====================
+.. automodule:: PyTango.server
+
.. hlist::
* :class:`~PyTango.server.Device`
--
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