Services
========

Действия, которые предоставляет фреймворк `ram`, называются `сервисами`.
Набор доступных для пользователя действий определяется поставкой фреймворка.


Большинство сервисов оперируют конфигурационными юнитами (путь к юниту - обязательный параметров таких сервисов).
Есть исключения: сервис для получения списка всех сервисов (:doc:`../services/proto`)
или сервис получения подсказки по использованию (:doc:`../services/usage`)


Сервисы ориентированы на использование в разных сценариях.


Service usage scenarios
-----------------------


`shell` scenario
~~~~~~~~~~~~~~~~

Самое очевидное использование сервисов ram, это команды утилиты командной строки.
Вывод утилиты может быть использован в скриптах или показан пользователю.
В своем коде утилита командной строки опирается на использование `python internal`-контекста сервисов `ram`.

.. sourcecode:: console

    $ ram print ifconfig


`python internal` scenario
~~~~~~~~~~~~~~~~~~~~~~~~~~

Этот контекст предназначен для написания обёрток над функционалом фреймворка `ram`.
Примером такой обёртки является утилита командной строки.

Особенности:

* Доступ к функциям-сервисам по строковому идентификатору в рантайме.
* Поиск сервиса и вызов сервиса - отдельные операции.
* Вызов функции-сервиса порождает питоновский генератор.
* Итерация по элементам генератора может блокировать выполнение кода.

Следующий код даст вывод аналогичный команде написанной в shell-контексте:

.. sourcecode:: python

    import ram

    # service lookup
    _print = ram.service['print']

    # service invocation
    _items = _print('ifconfig')

    # formatting results
    print('\n'.join(_items))


`python external` scenario
~~~~~~~~~~~~~~~~~~~~~~~~~~

Этот контекст предназначен для использования в коде юнитов и других скриптов.

Особенности:

* Доступ к функциям-сервисам как к функциям модуля `ram`.
* Возможен поиск сервиса по строковому идентификатору и вызов этого сервиса в рамках одного вызова.
* Вызов функции-сервиса может породить произвольный объект специфичный для конкретного сервиса.
* Примерами порождаемых объектов могут быть простые коллекции (списки, словари) или Watch-объекты.

Следующий код даст вывод аналогичный команде написанной в shell-контексте:

.. sourcecode:: python

    # in python 2.x `print` is reserved keyword
    # prevent syntax error due usage of `print` as function name
    from __future__ import print_function

    import ram

    # defined service invocation
    _items = ram.print('ifconfig')

    # or

    # service lookup and invocation
    _items = ram('print', 'ifconfig')

    # formatting results
    print('\n'.join(_items))


See also
--------

.. toctree::
    :maxdepth: 1
    :glob:

    ../misc/services.rst