Lesson 7: Adapters - invoke/inquire
-----------------------------
There are two mechanisms for controlling the logical flow of information in
an Orchestra system. Both of these rely on outlets (see more at <https://docs.ledr.io/en/the-orchestra-platfrom/outlets>)  
The short version is that outlets are special entities the server allocate some
resources to.  

The first is the adapter mechanism, where the outlet is the place of rendez-vous
between an adapter and an invoker/inquirer.  
This is what this lesson is about.  
see more at <https://docs.ledr.io/en/the-orchestra-platfrom/adapters>

The second is the pub/sub mechanism, where the outlet acts as an event queue. 
This will be detailed in the next lesson.  
see more at <https://docs.ledr.io/en/the-orchestra-platfrom/subscribers-events-and-pub-sub>


Ad adapter is a piece of code that calls `adapt` on an outlet. This tells the
Orchestra server that any call to `invoke` or `inquire` arriving on the outlet
should be handled by the adapter.  
In some sense, an adapter is a special client that connects to an Orchestra
server, and declares itself as the server that will handle any request on a 
certain outlet.  
This lesson only focuses on `invoke` and not `inquire`. They both work in very
similar way.  
TODO: document `inquire` more

The orchestra-toolkit library takes care of a lot of plumbing when creating an
adapter, including conforming to orchestra standards of how adapter works. This
makes developper's life easier.  
see <https://docs.ledr.io/en/the-orchestra-platfrom/adapters-standard> for more
details of what happens under the hood.  

The example adapter any new adapter written in python should copy/paste from
can be found at the link below. This is the definitive reference for how an
adapter is supposed to look according to our latest standards.  
<https://gitlab.com/ledr/core/dev-platform/python-adapter-wireframe>

At the moment `lesson_7_adapters.py` includes code both for the adapter as well
as  the driver logic that interacts with the adapter. This is for ease of
running the example.  

Note: For most usecases, you would run your adapter code separate from your
driver/client code.

To run the lesson_7 code:

.. code-block:: shell

   python src/module/lesson_7_adapter.py


Code
+++++++++++++++++++++++++++++++++++++++
.. literalinclude:: ../module/lesson_7_adapter.py
   :language: python
   :linenos: