Metadata-Version: 2.1
Name: imow-webapi
Version: 0.7.4
Summary: A library to authenticate and interact with STIHL iMow mowers using their WebAPI
Home-page: https://github.com/ChrisHaPunkt/stihl-imow-webapi
Author: ChrisHaPunkt
License: GPL
Description: # STIHL iMow unofficial Python API wrapper
        
        [![PyPI version shields.io](https://img.shields.io/pypi/v/imow-webapi)](https://pypi.python.org/pypi/imow-webapi/)
        [![Docs on GitHub pages](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](hhttps://chrishapunkt.github.io/stihl-imow-webapi/imow)
        [![CI](https://github.com/ChrisHaPunkt/stihl-imow-webapi/actions/workflows/python-package.yml/badge.svg?branch=master)](https://github.com/ChrisHaPunkt/stihl-imow-webapi/actions/workflows/python-package.yml)
        [![PyPI download total](https://img.shields.io/pypi/dm/imow-webapi)](https://pypi.python.org/pypi/imow-webapi/)
        [![PyPI pyversions](https://img.shields.io/pypi/pyversions/imow-webapi)](https://pypi.python.org/pypi/imow-webapi/)
        [![PyPI license](https://img.shields.io/pypi/l/imow-webapi)](https://pypi.python.org/pypi/imow-webapi/)
        
        
        This unofficial Python API was created to provide an interface to interact with the STIHL iMow mower WebAPI. This wrapper is able to receive the current status
        status from the mowers and to send actions.  
        I wrote this library to implement an integration for the [Home Assistant Smart Home System](https://www.home-assistant.io/), which you can find [here](https://github.com/ChrisHaPunkt/ha-stihl-imow).
        
        
        
        ## Getting Started
        
        These instructions will get you a copy of the project up and running on your local machine for development and testing
        purposes. See deployment for notes on how to deploy the project on a live system.
        
        API Documentation is available on: [https://chrishapunkt.github.io/stihl-imow-webapi/imow](https://chrishapunkt.github.io/stihl-imow-webapi/imow)
        
        If you want to  
        [!["Buy Me A Coffee"](
        https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=chrishapunkt&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/chrishapunkt)
        
        
        ### Prerequisites
        
        Python 3.7+ is required to run this application, other than that there are no prerequisites for the project, as the
        dependencies are included in the repository.
        
        ### Installing
        
        To install the library is as simple as cloning the repository and running
        
        ```bash
        pip install -e .
        ```
        
        It is recommended to create an virtual environment prior to installing this library. Alternatively, you can also install
        this library via Pip:
        
        ```bash
        pip install imow-webapi
        ```
        
        And have fun!
        
        ## Usage
        
        Import the module and instantiate the `IMowApi()` constructor with credentials. Afterwards, initiate the `get_token()` method.
        Or place credentials in the `get_token()` method.
        
        ```python
        from imow.api import IMowApi
        from imow.common.actions import IMowActions
        import asyncio
        
        
        async def main():
            api = IMowApi(lang="de")
            # save token for later use if you want to recreate IMowApi(token=my_token) because the created token is valid for
            # 30 days
            token, expire_time = await api.get_token("email@account.stihl", "supersecret", return_expire_time=True)
        
            print(await api.get_token())
        
            mowers = await api.receive_mowers()
            mower = mowers[0]
        
            print(f"{mower.name} @ {mower.coordinateLatitude},{mower.coordinateLongitude}")
            print(f"Currently: {mower.stateMessage['short']}")
            await mower.update_setting("gpsProtectionEnabled", True)
        
            print(mower.stateMessage)
            print(mower.machineState)
            await mower.intent(IMowActions.TO_DOCKING)
            print(await mower.update_from_upstream())
            print(await mower.get_startpoints())
        
            # Cleanup the created http session
            await api.close()
        
        
        if __name__ == "__main__":
            asyncio.run(main())
        
        ```
        ```text
        Selection of outputs from above statements:
        > Mährlin @ 54.123456,10.12345
        > Currently: Hood blocked
        > {'short': 'Hood blocked', 'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).', 'legacyMessage': 'Abschaltung Automatikmode durch Bumper', 'errorId': '', 'error': False}
        > HOOD_BLOCKED
        > <imow.common.mowerstate.MowerState object at 0x000001B034C245F8>
        ```
        ## Testing
        For unit testing run `pytest -s tests/test_unit*`. For upstream integration testing, provide a `/secrets.py` with the following contents:
        ````python
        EMAIL = "email@account.stihl"
        PASSWORD = "supersecret"
        MOWER_NAME = "MyRobot"
        ````
        and run `pytest -s tests/test_integration*` or `pytest -s`. 
        
        ## Built With
        
        * aiohttp
        * BeautifulSoup
        * asyncio
        
        ## Versioning
        
        Navigate to [tags on this repository](https://github.com/ChrisHaPunkt/imow-webapi/releases)
        to see all available versions.
        
        ## Authors
        
        | Mail Address                | GitHub Profile                                |
        -----------------------------|-----------------------------------------------|
        | chris@homeset.de          | [ChrisHaPunkt](https://github.com/ChrisHaPunkt)     |
        
        ## License
        
        This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md)
        license file for more details.
        
        # Acknowledges
        
        Thanks to
        
        * https://github.com/nstrydom2/anonfile-api
        * https://github.com/OpenXbox/xbox-webapi-python
        
        for repo structure inspiration
        
        
        # Changelog
        
        ## Version 0.7.4 (2021-09-06)
        
        ### Bugfxes
        - Allow handling of timestamps on mower intents (StartTime/Endtime)
        
        ## Version 0.7.3 (2021-07-03)
        
        ### Bugfxes
        - Always return a MowerState on settings update
        
        ## Version 0.7.2 (2021-07-03)
        ```python
        await mower.update_setting("gpsProtectionEnabled", True)
        ```
        ### Features
        - Possibility to update a specific settings for a mower like gpsProtection on/off
        ## Version 0.7.0 (2021-06-30)
        ### Breaking Changes
        - `IMowApi.intent` Parameter `mower_action_id` is renamed to `mower_external_id` to match the upstream api expectation.
        ### Features
        - If an `api_request` is intended, and the used `access_token` expires in less than one day, it's automatically renewed. 
          
        ## Version 0.6.0 (2021-06-28)
        - ```python
          mower.machineError = 'M1120',
          mower.machineState = 'HOOD_BLOCKED',
          mower.stateMessage: dict = {
              'short': 'Hood blocked', 
              'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).', 
              'legacyMessage': 'Abschaltung Automatikmode durch Bumper', 
              'errorId': 'M1120', 
              'error': True
          }
          ```
          
        ### Breaking Changes
        - Migrated all own MowerState attributes to camelCase to match the upstream attributes style.
          ```
          - MowerState.stateMessage = None
          - MowerState.machineError = None
          - MowerState.machineState = None
          ```
        ## Version 0.5.2 (2021-06-15)
        
        ## Bugfixes
        - Also quote password string in auth request to support more special chars 
        
        ## Version 0.5.1 (2021-06-13)
        
        ## Features
        - ```python
          mower.machine_error = 'M1120',
          mower.machine_state = 'HOOD_BLOCKED',
          mower.state_message: dict = {
              'short': 'Hood blocked', 
              'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).', 
              'legacyMessage': 'Abschaltung Automatikmode durch Bumper', 
              'errorId': 'M1120', 
              'error': True
          }
          ```
          Provide a machine usable string from the short message in english
        
        ## Version 0.5.0 (2021-06-12)
        
        ### Breaking Changes
        
        - The ``MowerTask`` class is removed in favor of the new ``state_message`` property on th ``MowerState`` object.
        - The ``MowerState.get_current_task()`` method now returns the `short` property of the state message instead of a ``MowerTask``
          property and is now longer an ``async`` method.
        
        ### Features
        
        - ```python
          mower.state_message -> dict
          {
              'short': 'Hood blocked', 
              'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).', 
              'errorId': 'M1120', 
              'error': True
          }
          ```
          The MowerState Class now provides a ```state_message``` property which gives a ``short`` and``long`` text for
          description (Besides an error indication and errorId). All error and status codes are now dynamically matched and
          human readable available.  
          **This makes the ``MowerTask`` obsolete and it is removed with this release.**
        - ``api = IMowApi(lang="en")``  
          The imow api can now be instanced with a language code (fallback to ``en``).   
          The ``state_message`` property displays the messages in the corresponding language.
        
        ## Version 0.4.5 (2021-06-01)
        
        ### Features
        
        - Add 2 new identified Tasks within `MowerTask` (Thanks to @lausser)
        - Add `check_api_maintenance()` method to `IMowAPI` Class. Check if the api server is currently under maintenance.  
          This method is automatically called if the api server returns a 500 error response for any request.
        - One should call the new `close()` method for the `IMowAPI` Class when finishing the api interactions to correctly
          close the http session.
        
        ### Bugfixes
        
        - [Issue #8](https://github.com/ChrisHaPunkt/stihl-imow-webapi/issues/8) - Example not working
        
        ## Version 0.4.4 (2021-05-28)
        
        ### Features
        
        - Add `validate_token()` method to `IMowAPI` Class. Test if a token is valid and is able to call the webapi.
        
        ## Version 0.4.3 (2021-05-27)
        
        ### Features
        
        - Allow `IMowAPI` Class to use predefined `aiohttp` session when instantiating
        
        ## Version 0.4.1 (2021-05-24)
        
        ### Changes
        
        - Even more asynchronously with switch from `requests` to `aiohttp`
        
        ## Version 0.4.0 (2021-05-17)
        
        ### Breaking Changes
        
        - Reworked everything to use asyncio where possible. See Readme.md for new usage example.
        - Renamed MowerState method `update` to `update_from_upstream`
        - Renamed MowerState method `get_status` to `get_current_status`
        
        ## Version 0.3.0 (2021-05-17)
        
        ### Breaking Changes
        
        - Renamed Class/Enum `MowerState` to `MowerTask` because it describes the current task not the state
        - Renamed Class `Mower` to `MowerState` because it's just a snapshot of the last upstream state
        
        ### Features
        
        - Add methods to work on `MowerState` objects, like action intents or statistic receive
        - Add PDoc documents, available
          on [https://chrishapunkt.github.io/stihl-imow-webapi/imow](https://chrishapunkt.github.io/stihl-imow-webapi/imow)
        
        ### Bugfixes
        
        - Return a valid error message and raise if provided login credentials are wrong
        
        ## Version 0.2.2 (2021-05-00)
        
        - Initial release
        
Keywords: stihl imow mower api
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/markdown
