Add README and docs.

Author: dariusstefan

README.md

@@ -0,0 +1,76 @@
+# OpenSIPS Python Packages
+
+This repository contains a collection of Python packages for OpenSIPS. These modules are designed to be as lightweight as possible and provide a simple interface for interacting with OpenSIPS.
+
+## Features
+
+Currently, the following packages are available:
+- `mi` - can be used to execute OpenSIPS Management Interface (MI) commands.
+- `event` - allows you to use OpenSIPS Event Interface subscriptions.
+
+## Usage
+
+1. Install the package from source code:
+    
+    ```bash
+    git clone
+    cd python-opebsips
+    pip install .
+    ```
+
+2. Import the package in your Python code:
+
+    ```python
+    from opensips.mi import OpenSIPSMI, OpenSIPSMIException
+    from opensips.event import OpenSIPSEvent, OpenSIPSEventException
+    ```
+
+3. Use the methods provided by the modules:
+
+    ```python
+    mi = OpenSIPSMI('http', url='http://localhost:8888/mi')
+    try:
+        response = mi.execute('ps')
+        # do something with the response
+    except OpenSIPSMIException as e:
+        # handle the exception
+    ```
+
+    ```python
+    mi_connector = OpenSIPSMI('http', url='http://localhost:8888/mi')
+    event = OpenSIPSEvent(mi_connector, 'datagram', ip='127.0.0.1', port=50012)
+
+    def some_callback(message):
+        # do something with the message
+        pass
+
+    try:
+        event.subscribe('E_PIKE_BLOCKED', some_callback)
+    except OpenSIPSEventException as e:
+        # handle the exception
+
+    try:
+        event.unsubscribe('E_PIKE_BLOCKED')
+    except OpenSIPSEventException as e:
+        # handle the exception
+    ```
+
+## Documentation
+
+* [MI](docs/mi.md) - contains information about supported MI communication types and required parameters for each type.
+* [Event Interface](docs/event.md) - lists the supported event transport protocols and provides information about the required parameters for each protocol.
+
+## License
+
+<!-- License source -->
+[License-GPLv3]: https://www.gnu.org/licenses/gpl-3.0.en.html "GNU GPLv3"
+[Logo-CC_BY]: https://i.creativecommons.org/l/by/4.0/88x31.png "Creative Common Logo"
+[License-CC_BY]: https://creativecommons.org/licenses/by/4.0/legalcode "Creative Common License"
+
+The `python-opensips` source code is licensed under the [GNU General Public License v3.0][License-GPLv3]
+
+All documentation files (i.e. `.md` extension) are licensed under the [Creative Common License 4.0][License-CC_BY]
+
+![Creative Common Logo][Logo-CC_BY]
+
+© 2024 - OpenSIPS Solutions

docs/event.md

@@ -0,0 +1,36 @@
+# OpenSIPS Python Packages - Event Interface
+
+This package can be used to subscribe to OpenSIPS Event Interface events.
+
+## Supported backend protocols
+
+The following event transport protocols are supported:
+* `datagram` - uses either UDP or UNIX datagram to receive notifications for subscribed events. If using UDP, the `ip` and `port` parameters are required. If using UNIX datagram, the `socket_path` parameter is required.
+* `stream` - uses TCP to communicate with the Event Interface. Requires the `ip` and `port` parameters to be set.
+
+## How to use
+
+To instantiate the `OpenSIPSEvent` class, you need to provide a MI connector, the backend protocol and the required parameters in a key-value format. Then `subscribe` and `unsubscribe` methods can be used to manage the subscriptions.
+
+```python
+mi_connector = OpenSIPSMI('http', url='http://localhost:8888/mi')
+event = OpenSIPSEvent(mi_connector, 'datagram', ip='127.0.0.1', port=50012)
+
+try:
+    event.subscribe('E_PIKE_BLOCKED', some_callback)
+except OpenSIPSEventException as e:
+    # handle the exception
+
+try:
+    event.unsubscribe('E_PIKE_BLOCKED')
+except OpenSIPSEventException as e:
+    # handle the exception
+```
+
+## Subscribing
+
+By default, the subscription will be permanent. If you want to set a timeout, you can use the `expires` parameter. The value should be an integer representing the number of seconds the subscription will be active.
+
+## How it works
+
+When subscribing to an event, a new thread is created to listen for notifications. The thread will call the callback function provided when an event is received. When unsubscribing, the thread will be stopped and the socket will be closed if no exceptions occur.

docs/mi.md

@@ -0,0 +1,28 @@
+# OpenSIPS Python Packages - MI
+
+This package can be used to execute OpenSIPS Management Interface (MI) commands.
+
+## Supported Communication Types
+
+The following communication types are supported:
+* `http` - uses the HTTP protocol to communicate with the MI interface. Requires the `url` parameter to be set.
+* `datagram` - uses the UDP protocol to communicate with the MI interface. Requires the `ip` and `port` parameters to be set.
+* `fifo` - uses a FIFO file to communicate with the MI interface. Requires 3 parameters: `fifo_file`, `fifo_file_fallback` and `fifo_reply_dir`.
+
+To instantiate the `OpenSIPSMI` class, you need to provide the communication type and the required parameters in a key-value format. For example:
+
+```python
+mi = OpenSIPSMI('http', url='http://localhost:8888/mi')
+
+# or
+mi = OpenSIPSMI('datagram', ip='127.0.0.1', port=8080)
+
+# or
+mi = OpenSIPSMI('fifo', fifo_file='/tmp/opensips_fifo', fifo_file_fallback='/tmp/opensips_fifo_fallback', fifo_reply_dir='/tmp/opensips/')
+```
+
+## Methods
+
+The `OpenSIPSMI` class provides the following methods:
+* `execute` - to run an MI command and get the response. If an error occurs, an `OpenSIPSMIException` is raised.
+* `valid` - to check if the MI connection is valid. Returns a tuple with a boolean value and a list of error messages.