.. PyTango documentation master file, created by
    sphinx-quickstart on Fri Jun  5 14:31:50 2009.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.

.. highlight:: python
   :linenothreshold: 4

Welcome to PyTango 7.1 documentation!
=====================================

.. image:: logo-medium.png

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

PyTango
-------

The python Tango binding is made accessible using the module PyTango.

The PyTango python module implements the Python Tango Device and Database API mapping but also allow to write Tango device server using Python.

It then allows access from Python environment to the Tango high level C++ classes and structures (see “The TANGO Control system manual” for complete reference).

If you want to write Tango device server in Python using this PyTango module, you need Tango C++ library release 7.1 or above.

If you simply need to write Python script which act as Tango client only, older releases of tango can be used.

These Tango high level C++ classes and structures are exported to Python using the Boost.python library (see http://boost.sourceforge.net). Details on how to install the boost library and generate the python PyTango module from source code are available in the Readme files of this packages.

.. toctree::
    :maxdepth: 3

    start
    client/index
    database
    server/index
    exception
    faq

.. _revision:

Revision
--------

:Contributers: M\. Ounsy, A\. Buteau, V\. Forchì, E\. Taurel, T\. Coutinho, R\. Suñe

:Last Update: |today|

.. _history-modifications:

History of modifications:

+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
|   Date   | Revision                                                                     |                          Description                | Author                |
+==========+==============================================================================+=====================================================+=======================+
| 18/07/03 | 1.0                                                                          | Initial Version                                     | M\. Ounsy             |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 06/10/03 | 2.0                                                                          | Extension of the "Getting Started" paragraph        | A\. Buteau/M\. Ounsy  |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 14/10/03 | 3.0                                                                          | Added Exception Handling paragraph                  | M\. Ounsy             |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 13/06/05 | 4.0                                                                          | Ported to Latex, added events, AttributeProxy       | V\. Forchì            |
|          |                                                                              | and ApiUtil                                         |                       |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
|          |                                                                              | fixed bug with python 2.5 and and state events      |                       |
| 13/06/05 | 4.1                                                                          | new Database constructor                            | V\. Forchì            |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 15/01/06 | 5.0                                                                          | Added Device Server classes                         | E\.Taurel             |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 15/03/07 | 6.0                                                                          | Added AttrInfoEx, AttributeConfig events, 64bits,   | T\. Coutinho          |
|          |                                                                              | write_attribute                                     |                       |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 21/03/07 | 6.1                                                                          | Added groups                                        | T\. Coutinho          |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 15/06/07 | `6.2 <http://www.tango-controls.org/Documents/bindings/PyTango-3.0.3.pdf/>`_ | Added dynamic attributes doc                        | E\. Taurel            |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 06/05/08 | `7.0 <http://www.tango-controls.org/Documents/bindings/PyTango-3.0.4.pdf/>`_ | Update to Tango 6.1. Added DB methods, version info | T\. Coutinho          |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 10/07/09 | 8.0                                                                          | Update to Tango 7. Major refactoring. Migrated doc  | T\. Coutinho/R\. Suñe |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 24/07/09 | 8.1                                                                          | Added migration info, added missing API doc         | T\. Coutinho/R\. Suñe |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 21/09/09 | 8.2                                                                          | Added migration info, release of 7.0.0beta2         | T\. Coutinho/R\. Suñe |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 12/11/09 | 8.3                                                                          | Update to Tango 7.1.                                | T\. Coutinho/R\. Suñe |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| ??/12/09 | 8.4                                                                          | Update to PyTango 7.1.0 rc1                         | T\. Coutinho/R\. Suñe |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+
| 25/01/10 | 8.5                                                                          | Update to PyTango 7.1.0                             | T\. Coutinho/R\. Suñe |
+----------+------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------+

.. _version-history:

Version history:

+------------+---------------------------------------------------------------------------------+
| version    | Changes                                                                         |
+============+=================================================================================+
| 7.1.0      | Features:                                                                       |
|            |     - from sourceforge:                                                         |
|            |       - 2908176: read_*, write_* and is_*_allowed() methods can now be defined  |
|            |       - 2941036: TimeVal conversion to time and datetime                        |
|            |     - added str representation on Attr, Attribute, DeviceImpl and DeviceClass   |
|            |                                                                                 |
|            | Bug fixes:                                                                      |
|            |     - from sourceforge: 2903755, 2908176, 2914194, 2909927, 2936173, 2949099    |
+------------+---------------------------------------------------------------------------------+
| 7.1.0rc1   | Features:                                                                       |
|            |     - v = image_attribute.get_write_value() returns square sequences (arrays of |
|            |       arrays, or numpy objects) now instead of flat lists. Also for spectrum    |
|            |       attributes a numpy is returned by default now instead.                    |
|            |     - image_attribute.set_value(v) accepts numpy arrays now or square sequences |
|            |       instead of just flat lists. So, dim_x and dim_y are useless now. Also the |
|            |       numpy path is faster.                                                     |
|            |     - new enum AttrSerialModel                                                  |
|            |     - Attribute new methods: set(get)_attr_serial_model, set_change_event,      |
|            |       set_archive_event, is_change_event, is_check_change_event,                |
|            |       is_archive_criteria, is_check_archive_criteria, remove_configuration      |
|            |     - added support for numpy scalars in tango operations like write_attribute  |
|            |       (ex: now a DEV_LONG attribute can receive a numpy.int32 argument in a     |
|            |       write_attribute method call)                                              |
|            |                                                                                 |
|            | Bug fixes:                                                                      |
|            |     - DeviceImpl.set_value for scalar attributes                                |
|            |     - DeviceImpl.push_***_event                                                 |
|            |     - server commands with DevVar***StringArray as parameter or as return type  |
|            |     - in windows,a bug in PyTango.Util prevented servers from starting up       |
|            |     - DeviceImpl.get_device_properties for string properties assigns only first |
|            |       character of string to object member instead of entire string             |
|            |     - added missing methods to Util                                             |
|            |     - exported SubDevDiag class                                                 |
|            |     - error in read/events of attributes of type DevBoolean READ_WRITE          |
|            |     - error in automatic unsubscribe events of DeviceProxy when the object      |
|            |       disapears (happens only on some compilers with some optimization flags)   |
|            |     - fix possible bug when comparing attribute names in DeviceProxy            |
|            |     - pretty print of DevFailed -> fix deprecation warning in python 2.6        |
|            |     - device class properties where not properly fetched when there is no       |
|            |       property value defined                                                    |
|            |     - memory leak when converting DevFailed exceptions from C++ to python       |
|            |     - python device server file without extension does not start                |
|            |                                                                                 |
|            | Documentation:                                                                  |
|            |     - Improved FAQ                                                              |
|            |     - Improved compilation chapter                                              |
|            |     - Improved migration information                                            |
+------------+---------------------------------------------------------------------------------+
