Metadata-Version: 2.1
Name: homepluscontrol
Version: 0.0.4
Summary: Python-based API to interact with the Legrand Home + Control interface
Home-page: https://github.com/chemaaa/homepluscontrol
Author: chemaaa
Author-email: chemaaar@gmail.com
License: UNKNOWN
Description: # Home + Control
        This is a basic Python library that interacts with the *Legrand Home + Control* API. It is 
        primarily intended for integration into Smart Home platforms such as Home Assistant.
        
        More information of the API can be found here: https://developer.legrand.com/
        
        The library currently supports 3 types of Legrand modules:
        
        1) Plugs (power outlets)
        2) Lights (connected switches)
        3) Remotes (wireless switches)
        
        The first two - plugs and lights - are modeled as basic switches that can be interacted with to set their status to *on* or *off*.
        Remotes are presented as passive modules that only have a battery level attribute.
        
        A 'home' is represented by a *plant* which presents all of its corresponding modules in a topology. A *plant* is basically a 
        Legrand Home+ Control gateway.
        
        The status of each module in the *plant* can be accessed through a single *status* call to the *plant* or through individual *status* 
        calls to each module.
        
        ## Authentication
        The *Legrand Home + Control* API uses Oauth2 authentication, so you must first register an account at https://developer.legrand.com/. 
        
        Once registered, you will then need to create a subscription to the *Starter Kit* (currently the only subscription available) and this will
        generate your SUBSCRIPTION_KEY.
        
        As a final step, you will have to register an Application, where you will have to define a name, a redirect URL and the scopes of your application
        (for simplicity you can mark all scopes). 
        
        Once the Application is confirmed, you should receive an email containing the CLIENT_IDENTIFIER and
        the CLIENT_SECRET which you will be using to set up the authentication flows.
        
        ### Authentication Flow
        Communication with the API, first requires Oauth2 authentication to obtain an access and a refresh token. Subsequent requests to the API, require the use of the SUBSCRIPTION_KEY in addition to the access token.
        
        Information about the Oauth2 exchange is provided here: https://developer.legrand.com/tutorials/0auth2-end-point-url/
        
        ## Quickstart
        Install `homepluscontrol` using `pip`: 
        
            $ pip install homepluscontrol
        
        ### Usage Example
        The following script is a simple example of how this Python library can be used::
        
        ```python
        from homepluscontrol import authentication, homeplusplant
        import asyncio
        
        client_id = 'YOUR_CLIENT_IDENTIFIER'
        client_secret = 'YOUR_CLIENT_SECRET'
        subscription_key = 'YOUR_SUBSCRIPTION_KEY'
        redirect_uri = 'https://www.example.com'
        
        dummy_token = 
            {"refresh_token": 
                "dummy-refresh-token", 
                "access_token": "dummy-access-token", 
                "expires_at": -1, 
                "expires_on": -1}
        api_plant_url = 'https://api.developer.legrand.com/hc/api/v1.0/plants'
        
        # Create the asynchronous client to handle the authentication 
        # process and the authenitcated requests
        client = authentication.HomePlusOAuth2Async(client_id, 
                                                    client_secret, 
                                                    subscription_key, 
                                                    token=dummy_token, 
                                                    redirect_uri=redirect_uri)
        
        # The URL returned by this method launches the Oauth2 flow and 
        # allows a user to confirm the process.
        # Doing so redirects the user's browser/client to the redirect URI
        # and includes the code and the state for the next step.
        authorization_url = client.generate_authorize_url()
        print(authorization_url)
        
        # Here is where you can enter the complete redirect URL
        return_url = input('Redirect URL received:')
        
        # This function will now handle the asynchronous calls to the API
        async def interact_with_api():
            token = await client.async_fetch_initial_token(return_url)
            print(token)
            # The client now has a valid token and can be used 
            # to interact with the API.
            
            # First get the plant information
            result = await client.request('get', api_plant_url)
            plant_info = await result.json()
            print(plant_info)
            plant_array = []
            for p in plant_info['plants']:
                plant_array.append(
                    homeplusplant.HomePlusPlant(p['id'], 
                                                p['name'], 
                                                p['country'], 
                                                client)
                )
            plant = plant_array[0]
            print(plant)
            
            # Next read the module information for the plant
            await plant.update_topology_and_modules()
            for mod_id in plant.modules.keys():
                    print(plant.modules[mod_id])
            # Close the client session
            await client.oauth_client.close()
        
        loop = asyncio.get_event_loop()
        loop.run_until_complete(interact_with_api())
        ```
        
        ## Testing
        `homepluscontrol` tests are based on `pytest`. To run, change to the root directory of `homepluscontrol` and use the command: 
        
            $ pytest 
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
