Python Bindings
===============

The Python content shipped in ``examples/language_bindings/python`` is a
reference integration that wraps the CosmicSDK C shared library with
``ctypes``. It is intended as a complete example of how to integrate the
library into a Python environment. It is not an official Python API.

Example Layout
--------------

The Python examples mirror the native C/C++ examples under
``examples/blocking_api``:

.. code-block:: text

   examples/language_bindings/python/
   |- cosmic_driver/
   |- system/example.py
   |- i2c/example.py
   |- spi/example.py
   |- uart/example.py
   |- gpio/example.py
   |- i3c/basic/example.py
   |- i3c/daa/example.py
   |- i3c/ccc/example.py
   |- i3c/hdr-ddr/example.py
   |- i3c/hj-ibi/example.py
   |- example_helpers.py

Windows
-------

1. **Navigate to the Python example directory**

.. code-block:: powershell

   cd /path/to/CosmicSDK/examples/language_bindings/python

2. **Set `COSMICSDK_LIB_PATH`**

Point it either to the directory that contains the shared library, or to the
full path of the library file itself.

- Command Prompt

.. code-block:: bat

   set COSMICSDK_LIB_PATH=<path-to-CosmicSDK-library-or-lib-folder>

- PowerShell

.. code-block:: powershell

   $env:COSMICSDK_LIB_PATH="<path-to-CosmicSDK-library-or-lib-folder>"

3. **Run one of the example scripts**

.. code-block:: powershell

   python system\example.py
   python i2c\example.py
   python spi\example.py
   python uart\example.py
   python gpio\example.py
   python i3c\basic\example.py

macOS
-------------

1. **Navigate to the Python example directory**

.. code-block:: bash

   cd /path/to/CosmicSDK/examples/language_bindings/python

2. **Set `COSMICSDK_LIB_PATH` and run an example**

.. code-block:: bash

   export COSMICSDK_LIB_PATH=/path/to/cosmicsdk/lib
   python3 i2c/example.py

Linux
-----

To run the Python example:

1. **Navigate to the Python example directory**

.. code-block:: bash

   cd /path/to/cosmicsdk/examples/language_bindings/python

2. **Set library variables and run**

.. code-block:: bash

   export COSMICSDK_LIB_PATH=/path/to/CosmicSDK/lib
   export LD_LIBRARY_PATH=$COSMICSDK_LIB_PATH:$LD_LIBRARY_PATH
   python3 i2c/example.py


Notes
-----

- The Python wrapper loads the CosmicSDK shared library internally. Users do
  not need to call ``ctypes.CDLL`` manually.
- Notification-driven examples such as ``uart``, ``gpio`` and ``i3c/hj-ibi``
  register Python callbacks through the C notification API.
- These scripts intentionally stay close to the C/C++ flows so they can be
  used as a starting point for custom integrations.