Connection and Session
======================

The XiBIF Connection package provides two main ways to communicate with a board:

- ``XibifConnection`` for explicit connect/disconnect control.
- ``XibifSession`` for context-managed usage with automatic cleanup.

XibifConnection
---------------

Use ``XibifConnection`` when you want manual lifecycle control, for example in
long-running applications or tools that keep one board connection open for
multiple operations.

.. code-block:: python

   from xibif_connection.api import XibifConnection

   board = XibifConnection("192.168.1.10", 0xDEAD_CAFE)
   board.connect()
   print(board.read(0))
   board.write(0, 10)
   board.disconnect()

Benefits:

- Full control over when the connection opens and closes.
- Useful for custom retry logic and reconnect behavior.

XibifSession
------------

Use ``XibifSession`` when you prefer concise and safe code. The session uses a
``with`` block and handles cleanup automatically, even if an exception happens.

.. code-block:: python

   from xibif_connection.api import XibifSession

   with XibifSession("192.168.1.10", 0xDEAD_CAFE) as board:
       print(board.read(0))
       board.write(0, 10)

Benefits:

- Less boilerplate.
- Automatic disconnect on block exit.
- Good default for scripts and notebooks.

Shared API surface
------------------

Both approaches expose the same core board operations such as:

- Register read/write
- Stream read/write
- Status and reset functionality

See the API reference for complete method documentation:

- :doc:`../code/api`