path: root/python-sharkiqpy.spec

%global _empty_manifest_terminate_build 0
Name:		python-sharkiqpy
Version:	0.1.9
Release:	1
Summary:	Python API for Shark IQ robots
License:	MIT
URL:		https://github.com/ajmarks/sharkiq
Source0:	https://mirrors.nju.edu.cn/pypi/web/packages/28/44/9a1737dfff203762c8d13924564ff954d624a1d01acbccf207691b7ae813/sharkiqpy-0.1.9.tar.gz
BuildArch:	noarch

Requires:	python3-aiohttp
Requires:	python3-requests

%description
# sharkiqpy
Unofficial SDK for Shark IQ robot vacuums, designed primarily to support an integration for [Home Assistant](https://www.home-assistant.io/).

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.

```bash
pip install sharkiqpy
```

## Usage
### Simple Operation
```python
from sharkiqpy import get_ayla_api, OperatingModes, Properties, PowerModes

USERNAME = 'me@email.com'
PASSWORD = '$7r0nkP@s$w0rD'

ayla_api = get_ayla_api(USERNAME, PASSWORD)
ayla_api.sign_in()

shark_vacs = ayla_api.get_devices()
shark = shark_vacs[0]

shark.update()
shark.set_operating_mode(OperatingModes.START)
shark.return_to_base()
```

### Async operation
```python
import asyncio
from sharkiqpy import get_ayla_api, OperatingModes, SharkIqVacuum

USERNAME = 'me@email.com'
PASSWORD = '$7r0nkP@s$w0rD'

async def main(ayla_api) -> SharkIqVacuum:
    await ayla_api.async_sign_in()

    shark_vacs = await ayla_api.async_get_devices()
    shark = shark_vacs[0]
    await shark.async_update()
    await shark.async_find_device()
    await shark.async_set_operating_mode(OperatingModes.START)

    return shark


ayla_api = get_ayla_api(USERNAME, PASSWORD)
shark = asyncio.run(main(ayla_api))
```

## Documentation
### `get_ayla_api(username, password, websession=None)`
Returns and `AylaApi` object to interact with the Ayla Networks Device API conrolling the Shark IQ robot, with the `app_id` and `app_secret` parameters set for the Shark IQ robot.

### `class AylaAPI(username, password, app_id, app_secret, websession)`
Class for interacting with the Ayla Networks Device API underlying the Shark IQ controls.
 * `username: str`
 * `password: str`
 * `app_id: str` 
 * `app_secret: str`
 * `websession: Optional[aiohttp.ClientSession] = None` Optional `aiohttp.ClientSession` to use for async calls.  If
  one is not provided, a new `aiohttp.ClientSession` will be created at the first async call.
#### Methods
 * `get_devices()`/`async_get_devices()` Get a list of `SharkIqVacuum`s for every device found in `list_devices()`
 * `list_devices()`/`async_list_devices()` Get a list of known device description `dict`s
 * `refesh_auth()`/`async_refesh_auth()` Refresh the authentication token
 * `request(method, url, headers = None, auto_refresh = True, **kwargs)`/`async_request(...)` Submit an HTTP request to
  the Ayla networks API with the auth header
   * `method: str` An HTTP method, usually `'get'` or `'post'`
   * `url: str`
   * `headers: Optional[Dict] = None` Optional `dict` of HTTP headers besides the auth header, which is included 
   automatically
   * `auto_refresh: bool = True` If `True`, automatically call `refesh_auth()`/`async_refesh_auth()` if the auth token
   is near expiration
   * `**kwargs` Passed on to `requests.request` or `aiohttp.ClientSession.request`
 * `sign_in()`/`async_sign_in()` Authenticate
 * `sign_out()`/`async_sign_out()` Sign out


### `class SharkIqRobot(ayla_api, device_dct)`
Primary API for interacting with Shark IQ vacuums
 * `ayla_api: AylaApi` An `AylaApi` with an authenticated connection
 * `device_dct: Dict` A `dict` describing the device, usually obtained from `AylaApi.list_devices()`

#### Methods
 * `find_device()`/`async_find_device()` Cause the device to emit an annoying chirp 
 * `get_file_property_url(property_name)`/`async_get_file_property_url(property_name)` Get the URL for the latest version of a `'file'`-type property
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `get_file_property(property_name)`/`async_get_file_property(property_name)` Get the contents of the latest version of a `'file'`-type property
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `get_metadata()`/`async_get_metadata()` Update some device metadata (`vac_model_number` and `vac_serial_number`)
 * `set_operating_mode(mode)`/`async_set_operating_mode(mode)` Set the operating mode.  This is just a thin wrapper 
 around `set_property_value`/`async_set_property_value` provided for convenience.
   * mode: OperatingModes Mode to set, e.g., `OperatingModes.START` to start the vacuum
 * `get_property_value(property_name)/async_get_property_value(property_name)`
   Returns the value of `property_name`, cast to the appropriate type
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `set_property_value(property_name, property_value)/async_set_property_value(property_name, property_value)`
 Set the value of `property_name`
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyName` value for the desired property
   * `property_value: Any` New value.  Type checking is currently left to the remote API.
 * `update()`/`async_update(property_list=None)` Fetch the updated robot state from the remote api
   * `property_list: Optional[Interable[str]]` An optional iterable of property names.  If specified, only those 
   properties will be updated.

#### Properties
 * `ayla_api` The underlying `AylaApi` object
 * `error_code` Error code, if any.  *NB: these can be very stale as they are not immediately reset in the API when the 
 error is cleared*.
 * `error_text` English description of the `error_code`.  The same caveat applies.
 * `name` The device name as it appears in the SharkClean app
 * `oem_model_number` A "rough" model number that does not distinguish, for example, between robots with and without
 a self-emptying base
 * `properties_full` A dictionary representing all known device properties and their metadata (type 
 `Dict[str, Dict]`)
 * `property_values` A convenience accessor into `properties_full` mapping property names to values
 * `serial_number` The unique device serial number used with the Ayla Networks API (NB: this name may change)
 * `vac_model_number` The precise model number
 * `vac_serial_number` The serial number printed on the device


### Enums
 * `OperatingModes` Operation modes to control the vacuum (`START`, `STOP`, `PAUSE`, `RETURN`)
 * `PowerModes` Vacuum power mode (`ECO`, `NORMAL`, `MAX`)
 * `Properties` Properties to use with `get_property_value`/`set_property_value`


### TODOs:
 * Add support for mapping and room selection
 * Once we have mapping, it may be possible to use the RSSI property combined with an increased update frequency
 to generate a wifi strength heatmap.  Kind of orthogonal to the main purpose, but I really want to do this.

## License
[MIT](https://choosealicense.com/licenses/mit/)




%package -n python3-sharkiqpy
Summary:	Python API for Shark IQ robots
Provides:	python-sharkiqpy
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-sharkiqpy
# sharkiqpy
Unofficial SDK for Shark IQ robot vacuums, designed primarily to support an integration for [Home Assistant](https://www.home-assistant.io/).

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.

```bash
pip install sharkiqpy
```

## Usage
### Simple Operation
```python
from sharkiqpy import get_ayla_api, OperatingModes, Properties, PowerModes

USERNAME = 'me@email.com'
PASSWORD = '$7r0nkP@s$w0rD'

ayla_api = get_ayla_api(USERNAME, PASSWORD)
ayla_api.sign_in()

shark_vacs = ayla_api.get_devices()
shark = shark_vacs[0]

shark.update()
shark.set_operating_mode(OperatingModes.START)
shark.return_to_base()
```

### Async operation
```python
import asyncio
from sharkiqpy import get_ayla_api, OperatingModes, SharkIqVacuum

USERNAME = 'me@email.com'
PASSWORD = '$7r0nkP@s$w0rD'

async def main(ayla_api) -> SharkIqVacuum:
    await ayla_api.async_sign_in()

    shark_vacs = await ayla_api.async_get_devices()
    shark = shark_vacs[0]
    await shark.async_update()
    await shark.async_find_device()
    await shark.async_set_operating_mode(OperatingModes.START)

    return shark


ayla_api = get_ayla_api(USERNAME, PASSWORD)
shark = asyncio.run(main(ayla_api))
```

## Documentation
### `get_ayla_api(username, password, websession=None)`
Returns and `AylaApi` object to interact with the Ayla Networks Device API conrolling the Shark IQ robot, with the `app_id` and `app_secret` parameters set for the Shark IQ robot.

### `class AylaAPI(username, password, app_id, app_secret, websession)`
Class for interacting with the Ayla Networks Device API underlying the Shark IQ controls.
 * `username: str`
 * `password: str`
 * `app_id: str` 
 * `app_secret: str`
 * `websession: Optional[aiohttp.ClientSession] = None` Optional `aiohttp.ClientSession` to use for async calls.  If
  one is not provided, a new `aiohttp.ClientSession` will be created at the first async call.
#### Methods
 * `get_devices()`/`async_get_devices()` Get a list of `SharkIqVacuum`s for every device found in `list_devices()`
 * `list_devices()`/`async_list_devices()` Get a list of known device description `dict`s
 * `refesh_auth()`/`async_refesh_auth()` Refresh the authentication token
 * `request(method, url, headers = None, auto_refresh = True, **kwargs)`/`async_request(...)` Submit an HTTP request to
  the Ayla networks API with the auth header
   * `method: str` An HTTP method, usually `'get'` or `'post'`
   * `url: str`
   * `headers: Optional[Dict] = None` Optional `dict` of HTTP headers besides the auth header, which is included 
   automatically
   * `auto_refresh: bool = True` If `True`, automatically call `refesh_auth()`/`async_refesh_auth()` if the auth token
   is near expiration
   * `**kwargs` Passed on to `requests.request` or `aiohttp.ClientSession.request`
 * `sign_in()`/`async_sign_in()` Authenticate
 * `sign_out()`/`async_sign_out()` Sign out


### `class SharkIqRobot(ayla_api, device_dct)`
Primary API for interacting with Shark IQ vacuums
 * `ayla_api: AylaApi` An `AylaApi` with an authenticated connection
 * `device_dct: Dict` A `dict` describing the device, usually obtained from `AylaApi.list_devices()`

#### Methods
 * `find_device()`/`async_find_device()` Cause the device to emit an annoying chirp 
 * `get_file_property_url(property_name)`/`async_get_file_property_url(property_name)` Get the URL for the latest version of a `'file'`-type property
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `get_file_property(property_name)`/`async_get_file_property(property_name)` Get the contents of the latest version of a `'file'`-type property
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `get_metadata()`/`async_get_metadata()` Update some device metadata (`vac_model_number` and `vac_serial_number`)
 * `set_operating_mode(mode)`/`async_set_operating_mode(mode)` Set the operating mode.  This is just a thin wrapper 
 around `set_property_value`/`async_set_property_value` provided for convenience.
   * mode: OperatingModes Mode to set, e.g., `OperatingModes.START` to start the vacuum
 * `get_property_value(property_name)/async_get_property_value(property_name)`
   Returns the value of `property_name`, cast to the appropriate type
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `set_property_value(property_name, property_value)/async_set_property_value(property_name, property_value)`
 Set the value of `property_name`
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyName` value for the desired property
   * `property_value: Any` New value.  Type checking is currently left to the remote API.
 * `update()`/`async_update(property_list=None)` Fetch the updated robot state from the remote api
   * `property_list: Optional[Interable[str]]` An optional iterable of property names.  If specified, only those 
   properties will be updated.

#### Properties
 * `ayla_api` The underlying `AylaApi` object
 * `error_code` Error code, if any.  *NB: these can be very stale as they are not immediately reset in the API when the 
 error is cleared*.
 * `error_text` English description of the `error_code`.  The same caveat applies.
 * `name` The device name as it appears in the SharkClean app
 * `oem_model_number` A "rough" model number that does not distinguish, for example, between robots with and without
 a self-emptying base
 * `properties_full` A dictionary representing all known device properties and their metadata (type 
 `Dict[str, Dict]`)
 * `property_values` A convenience accessor into `properties_full` mapping property names to values
 * `serial_number` The unique device serial number used with the Ayla Networks API (NB: this name may change)
 * `vac_model_number` The precise model number
 * `vac_serial_number` The serial number printed on the device


### Enums
 * `OperatingModes` Operation modes to control the vacuum (`START`, `STOP`, `PAUSE`, `RETURN`)
 * `PowerModes` Vacuum power mode (`ECO`, `NORMAL`, `MAX`)
 * `Properties` Properties to use with `get_property_value`/`set_property_value`


### TODOs:
 * Add support for mapping and room selection
 * Once we have mapping, it may be possible to use the RSSI property combined with an increased update frequency
 to generate a wifi strength heatmap.  Kind of orthogonal to the main purpose, but I really want to do this.

## License
[MIT](https://choosealicense.com/licenses/mit/)




%package help
Summary:	Development documents and examples for sharkiqpy
Provides:	python3-sharkiqpy-doc
%description help
# sharkiqpy
Unofficial SDK for Shark IQ robot vacuums, designed primarily to support an integration for [Home Assistant](https://www.home-assistant.io/).

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.

```bash
pip install sharkiqpy
```

## Usage
### Simple Operation
```python
from sharkiqpy import get_ayla_api, OperatingModes, Properties, PowerModes

USERNAME = 'me@email.com'
PASSWORD = '$7r0nkP@s$w0rD'

ayla_api = get_ayla_api(USERNAME, PASSWORD)
ayla_api.sign_in()

shark_vacs = ayla_api.get_devices()
shark = shark_vacs[0]

shark.update()
shark.set_operating_mode(OperatingModes.START)
shark.return_to_base()
```

### Async operation
```python
import asyncio
from sharkiqpy import get_ayla_api, OperatingModes, SharkIqVacuum

USERNAME = 'me@email.com'
PASSWORD = '$7r0nkP@s$w0rD'

async def main(ayla_api) -> SharkIqVacuum:
    await ayla_api.async_sign_in()

    shark_vacs = await ayla_api.async_get_devices()
    shark = shark_vacs[0]
    await shark.async_update()
    await shark.async_find_device()
    await shark.async_set_operating_mode(OperatingModes.START)

    return shark


ayla_api = get_ayla_api(USERNAME, PASSWORD)
shark = asyncio.run(main(ayla_api))
```

## Documentation
### `get_ayla_api(username, password, websession=None)`
Returns and `AylaApi` object to interact with the Ayla Networks Device API conrolling the Shark IQ robot, with the `app_id` and `app_secret` parameters set for the Shark IQ robot.

### `class AylaAPI(username, password, app_id, app_secret, websession)`
Class for interacting with the Ayla Networks Device API underlying the Shark IQ controls.
 * `username: str`
 * `password: str`
 * `app_id: str` 
 * `app_secret: str`
 * `websession: Optional[aiohttp.ClientSession] = None` Optional `aiohttp.ClientSession` to use for async calls.  If
  one is not provided, a new `aiohttp.ClientSession` will be created at the first async call.
#### Methods
 * `get_devices()`/`async_get_devices()` Get a list of `SharkIqVacuum`s for every device found in `list_devices()`
 * `list_devices()`/`async_list_devices()` Get a list of known device description `dict`s
 * `refesh_auth()`/`async_refesh_auth()` Refresh the authentication token
 * `request(method, url, headers = None, auto_refresh = True, **kwargs)`/`async_request(...)` Submit an HTTP request to
  the Ayla networks API with the auth header
   * `method: str` An HTTP method, usually `'get'` or `'post'`
   * `url: str`
   * `headers: Optional[Dict] = None` Optional `dict` of HTTP headers besides the auth header, which is included 
   automatically
   * `auto_refresh: bool = True` If `True`, automatically call `refesh_auth()`/`async_refesh_auth()` if the auth token
   is near expiration
   * `**kwargs` Passed on to `requests.request` or `aiohttp.ClientSession.request`
 * `sign_in()`/`async_sign_in()` Authenticate
 * `sign_out()`/`async_sign_out()` Sign out


### `class SharkIqRobot(ayla_api, device_dct)`
Primary API for interacting with Shark IQ vacuums
 * `ayla_api: AylaApi` An `AylaApi` with an authenticated connection
 * `device_dct: Dict` A `dict` describing the device, usually obtained from `AylaApi.list_devices()`

#### Methods
 * `find_device()`/`async_find_device()` Cause the device to emit an annoying chirp 
 * `get_file_property_url(property_name)`/`async_get_file_property_url(property_name)` Get the URL for the latest version of a `'file'`-type property
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `get_file_property(property_name)`/`async_get_file_property(property_name)` Get the contents of the latest version of a `'file'`-type property
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `get_metadata()`/`async_get_metadata()` Update some device metadata (`vac_model_number` and `vac_serial_number`)
 * `set_operating_mode(mode)`/`async_set_operating_mode(mode)` Set the operating mode.  This is just a thin wrapper 
 around `set_property_value`/`async_set_property_value` provided for convenience.
   * mode: OperatingModes Mode to set, e.g., `OperatingModes.START` to start the vacuum
 * `get_property_value(property_name)/async_get_property_value(property_name)`
   Returns the value of `property_name`, cast to the appropriate type
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyNames` value for the desired property
 * `set_property_value(property_name, property_value)/async_set_property_value(property_name, property_value)`
 Set the value of `property_name`
   * `property_name: Union[str, PropertyName]` Either a `str` or `PropertyName` value for the desired property
   * `property_value: Any` New value.  Type checking is currently left to the remote API.
 * `update()`/`async_update(property_list=None)` Fetch the updated robot state from the remote api
   * `property_list: Optional[Interable[str]]` An optional iterable of property names.  If specified, only those 
   properties will be updated.

#### Properties
 * `ayla_api` The underlying `AylaApi` object
 * `error_code` Error code, if any.  *NB: these can be very stale as they are not immediately reset in the API when the 
 error is cleared*.
 * `error_text` English description of the `error_code`.  The same caveat applies.
 * `name` The device name as it appears in the SharkClean app
 * `oem_model_number` A "rough" model number that does not distinguish, for example, between robots with and without
 a self-emptying base
 * `properties_full` A dictionary representing all known device properties and their metadata (type 
 `Dict[str, Dict]`)
 * `property_values` A convenience accessor into `properties_full` mapping property names to values
 * `serial_number` The unique device serial number used with the Ayla Networks API (NB: this name may change)
 * `vac_model_number` The precise model number
 * `vac_serial_number` The serial number printed on the device


### Enums
 * `OperatingModes` Operation modes to control the vacuum (`START`, `STOP`, `PAUSE`, `RETURN`)
 * `PowerModes` Vacuum power mode (`ECO`, `NORMAL`, `MAX`)
 * `Properties` Properties to use with `get_property_value`/`set_property_value`


### TODOs:
 * Add support for mapping and room selection
 * Once we have mapping, it may be possible to use the RSSI property combined with an increased update frequency
 to generate a wifi strength heatmap.  Kind of orthogonal to the main purpose, but I really want to do this.

## License
[MIT](https://choosealicense.com/licenses/mit/)




%prep
%autosetup -n sharkiqpy-0.1.9

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "\"/%h/%f.gz\"\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-sharkiqpy -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Thu Jun 08 2023 Python_Bot <Python_Bot@openeuler.org> - 0.1.9-1
- Package Spec generated