pyimaprotect 3.2.5
Get alarm status and informations from the IMA Protect API.
License: MIT license
Requires Python: >=3.9
Keywords: pyimaprotect

===========================================================
pyimaprotect - Python `IMA Protect Alarm`_ *UNOFFICIAL*
===========================================================


.. image:: https://img.shields.io/pypi/v/pyimaprotect.svg
        :target: https://pypi.python.org/pypi/pyimaprotect

.. image:: https://img.shields.io/pypi/pyversions/pyimaprotect.svg
        :target: https://pypi.python.org/pypi/pyimaprotect

.. image:: https://img.shields.io/travis/pcourbin/pyimaprotect.svg
        :target: https://travis-ci.com/pcourbin/pyimaprotect

.. image:: https://readthedocs.org/projects/pyimaprotect/badge/?version=latest
        :target: https://pyimaprotect.readthedocs.io/en/latest/?version=latest
        :alt: Documentation Status

.. image:: https://pyup.io/repos/github/pcourbin/pyimaprotect/shield.svg
     :target: https://pyup.io/repos/github/pcourbin/pyimaprotect/
     :alt: Updates

.. image:: https://codecov.io/gh/pcourbin/pyimaprotect/branch/main/graph/badge.svg
     :target: https://codecov.io/gh/pcourbin/pyimaprotect

.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen
     :target: `pre-commit`_
     :alt: pre-commit

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: `black`_
     :alt: Black

.. image:: https://img.shields.io/badge/maintainer-%40pcourbin-blue.svg
     :target: `user_profile`_
     :alt: Project Maintenance

.. image:: https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg
     :target: `buymecoffee`_
     :alt: BuyMeCoffee


| Get and set alarm status from your `IMA Protect Alarm`_.
| You can get and set the status, get the list of contacts and download your images.

This work is originally developed for use with `Home Assistant`_ and the *custom component* `imaprotect`_.


* Free software: MIT license
* Documentation: https://pyimaprotect.readthedocs.io.

Features
--------

Since the last update of IMAProtect "API" (05/2021), this plugin allows you to:

- **get the status** of your alarm:

.. code-block:: python

  from pyimaprotect import IMAProtect, STATUS_NUM_TO_TEXT
  ima = IMAProtect('myusername','mysuperpassword')
  # Use contract_number if you have multiple contracts, headless if you want to run in headless mode, timeout if you want to set a custom timeout and remote_webdriver if you use a remote webdriver for selenium, see https://hub.docker.com/r/selenium/standalone-firefox
  # ima = IMAProtect(username='myusername', password='mysuperpassword', contract_number='contractid', headless=True, timeout=30, remote_webdriver='http://localhost:4444')

  print("# Get Status")
  imastatus = ima.status
  print("Current Alarm Status: %d (%s)" % (imastatus,STATUS_NUM_TO_TEXT[imastatus]))

- **set the status** of your alarm:

.. code-block:: python

  from pyimaprotect import IMAProtect
  ima = IMAProtect('myusername','mysuperpassword')

  print("# Set Status")
  ima.status = 0 # 0 to OFF, 1 to PARTIAL and 2 to On


- **get** the list and information of your **registered contacts**:

.. code-block:: python

  from pyimaprotect import IMAProtect
  ima = IMAProtect('myusername','mysuperpassword')

  print("# Get Contact List")
  contact_list = ima.get_contact_list()
  for contact in contact_list:
      print(contact)

- **download the images/photos** taken with your connected elements:

.. code-block:: python

  from pyimaprotect import IMAProtect
  ima = IMAProtect('myusername','mysuperpassword')

  print("# Download Images")
  ima.download_images() # Download images to 'Images/' folder. One subfolder per camera.
  ima.download_images("MyImages/") # Download images to a defined directory 'MyImages/' folder.

Parameters
==========

- `username`: Username used to connect to https://www.imaprotect.com/
- `password`: Password used to connect to https://www.imaprotect.com/
- `contract_number` (optional): Contract number if you have multiple contracts.
- `remote_webdriver` (optional): URL of the remote webdriver server if you use one (e.g. `http://localhost:4444`).

Using the remote_webdriver parameter
====================================
Using the remote_webdriver parameter is useful if you are using a selenium server like the `selenium/standalone-firefox`_ docker image.
.. note:: Example docker-compose to run a Selenium standalone-firefox server (use as remote_webdriver)

.. code-block:: yaml

  services:
    firefox:
      image: selenium/standalone-firefox:130.0-20251025
      shm_size: 2g
      ports:
        - "4444:4444"
        - "7900:7900"

# Usage:
- 1. Save this as docker-compose.yml in the project folder.
- 2. Start with: docker-compose up -d
- 3. Use remote_webdriver='http://localhost:4444' when creating IMAProtect.

Methods
=======

- `login()`: open a session with the IMA Protect Alarm website
- `logout()`: close the session with the IMA Protect Alarm website
- `status`: property to get or set the status of your IMA Protect Alarm. See the next table to understand the values.
- `get_contact_list()`: get a JSON with the list and information about your registered contacts.
- `download_images()`: download the images/photos taken with your connected elements.

.. list-table:: List of Alarm status values
   :widths: auto
   :header-rows: 1

   * - Alarm Value
     - State
   * - `-1`
     - `UNKNOWN`
   * - `0`
     - `OFF`
   * - `1`
     - `PARTIAL`
   * - `2`
     - `ON`



Credits
-------

| This work was based on the work of `lplancke`_ and `chris94440`_ for `Jeedom`_.
| This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.


.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _`IMA Protect Alarm`: https://www.imaprotect.com/
.. _`Home Assistant`: https://www.home-assistant.io/
.. _`imaprotect`: https://github.com/pcourbin/imaprotect
.. _`lplancke`: https://github.com/lplancke/jeedom_alarme_IMA
.. _`Jeedom`: https://www.jeedom.com
.. _`chris94440`: https://github.com/chris94440
.. _`pre-commit`: https://github.com/pre-commit/pre-commit
.. _`black`: https://github.com/psf/black
.. _`user_profile`: https://github.com/pcourbin
.. _`buymecoffee`: https://www.buymeacoffee.com/pcourbin
.. _`selenium/standalone-firefox`: https://hub.docker.com/r/selenium/standalone-firefox


=======
History
=======

3.2.5 (2025-10-30)
------------------
* Add support for multiple user agents in IMAProtect.
* Improve error handling and logging.
* Add simulate_typing_to_element method to IMAProtect to simulate human-like typing in input fields thanks to `@falconslag`_

3.2.3 (2025-10-29)
------------------
* Add timeout parameter to IMAProtect to set a custom timeout for selenium webdriver waits.
* Add headless parameter to IMAProtect to run selenium in headless mode.


3.2.2 (2025-10-28)
------------------
* Update login procedure since IMA Protect login page changed again..., thanks to `@falconslag`_


3.1.6 (2024-03-31)
------------------
* Update RE_ALARM_TOKEN since IMA Protect login page changed again..., thanks to `@Chrilk`_


3.1.5 (2023-02-18)
------------------
* Update login procedure according to new IMAProtect "API", thanks to `@Thesola10`_

3.1.2 (2021-11-05)
------------------
* Update login procedure according to new IMAProtect "API"
* Update download images procedure according to new IMAProtect "API"

3.1.0 (2021-05-22)
------------------
* Add cookie expire usage to reduce the number of login
* Add a logout function

3.0.0 (2021-05-22)
------------------

* Add option to change the alarm (set/get)
* Add function to get the list of contacts
* Add function to download the images

`get_status` has been removed, `status` is now a property to get/set the alarm.

2.0.0 (2021-05-09)
------------------

* Update using new IMAProtect "API"
* No more other info (name, contract, etc.), only alarm status but faster result.

1.0.0 (2021-04-11)
------------------

* First release on PyPI.



.. _`@Thesola10`: https://github.com/Thesola10

.. _`@Chrilk`: https://github.com/Chrilk

.. _`@falconslag`: https://github.com/falconslag