Code Documentation

Application run scripts

pyscripts/request_handlers.py

Request handlers for the Switcher WebAPI.

async request_handlers._create_raw_schedule_data(schedule_days: List[int], start_hours: int, start_minutes: int, stop_hours: int, stop_minutes: int) → str[source]

Use as helper creating raw schedule data for creating schedules.

Parameters
  • schedule_days – selected days for the schedule to run in.

  • start_hours – hour to start the device at.

  • start_minutes – minutes to start the device at.

  • stop_hours – hour to stop the device at.

  • stop_minutes – minutes to stop the device at.

Returns

Raw schedule data needed for creating the requested schedule.

async request_handlers._parse_schedule_body(body: Dict) → str[source]

Use as helper parsing body of create schedule requests.

Parameters

body – json body of the create schedule requests.

Raises

sanic.exceptions.InvalidUsage – when missing a mandatory argument.

Returns

Schedule data object needed for creating the new schedules.

request_handlers._validate_day_to_int(day: str) → int[source]

Use as helper converting string weekday to int for creating schedules.

Parameters

day – string represntation of the weekday.

Raises

sanic.exceptions.InvalidUsage – when encounterd unknown weekday string.

Returns

The in represntation of the weekday.

More information is available in the Usage section.

request_handlers._validate_time_integers(start_hours: int, start_minutes: int, stop_hours: int, stop_minutes: int) → None[source]

Use as helper validating time arguments of creating schedule requests.

Parameters
  • start_hours – hour to start the device at (0-23).

  • start_minutes – minutes to start the device at (0-59).

  • stop_hours – hour to stop the device at (0-23).

  • stop_minutes – minutes to stop the device at (0-59).

Raises

sanic.exceptions.InvalidUsage – when the validation failes.

async request_handlers.create_schedule_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/create_schedule.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises

sanic.exceptions.ServerError – when encounterd an error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Warning

Accepts json body only, no query parameters allowed.

async request_handlers.delete_schedule_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/delete_schedule.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises
  • sanic.exceptions.InvalidUsage – when encounterd unknown weekday.

  • sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.disable_schedule_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/disable_schedule.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises
  • sanic.exceptions.InvalidUsage – when encounterd faulty data.

  • sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.enable_schedule_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/enable_schedule.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises
  • sanic.exceptions.InvalidUsage – when encounterd faulty data.

  • sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.get_schedules_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/get_schedules.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises

sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the configured schedules on the device.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.get_state_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/get_state.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises

sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the current state of the device.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.set_auto_shutdown_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/set_auto_shutdown.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises
  • sanic.exceptions.InvalidUsage – when requested is not 59-180 minutes.

  • sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.set_device_name_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/set_device_name.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises
  • sanic.exceptions.InvalidUsage – when name length is no 2-32 characters.

  • sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.turn_off_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/turn_off.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises

sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

async request_handlers.turn_on_handler(request: sanic.request.Request, ip_address: str, phone_id: str, device_id: str, device_password: str) → sanic.response.HTTPResponse[source]

Use for handling requests to /switcher/turn_on.

Parameters
  • requestsanic’s request object.

  • ip_address – the local ip address.

  • phone_id – the extracted phone id.

  • device_id – the extracted device id.

  • device_password – the extracted device password.

Raises
  • sanic.exceptions.InvalidUsage – when timer is no 1-180 minutes.

  • sanic.exceptions.ServerError – when encounterd any error.

Returns

Json object represnting the request status.

More information is available in the Usage section.

Note

Accepts arguments as json body or query parameters.

pyscripts/start_server.py

Sanic server for the Switcher WebAPI.

start_server.before_start(app: sanic.Sanic, loop: asyncio.events.AbstractEventLoop) → None[source]

Use for preparing data and register mappings before start.

This function is annotated with sanic.Sanic.listener("before_server_start").

It is called by Sanic just before the server starts. Its job is:

  • Gather the initial data for running the server.

  • Register a middleware for aquiring a throttler for all requests.

  • Add routes using the mappings module and the request_handlers module.

Parameters
  • app – the running sanic app.

  • loop – the main event loop.

start_server.timeout(request: sanic.request.Request, exception: sanic.exceptions.SanicException) → sanic.response.HTTPResponse[source]

Use as custom handler for logging internal service errors.

This function is annotated with `sanic.Sanic.exception(ServerError).

It is called by Sanic for every ServerError exception.

Its job is to log the exception and return a code 500 response.

Parameters
  • request – the incoming request object.

  • exception – the exception thrown.

Unit testing scripts

pyscripts/conftest.py

Fixtures and mockings for unit testing the Switcher WebAPI.

conftest.mock_control_response() → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the control response.

Yields

Mocked SwitcherV2ControlResponseMSG object.

conftest.mock_create_schedule_request() → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the create_schedule response.

Yields

Mocked SwitcherV2CreateScheduleResponseMSG object.

conftest.mock_delete_schedule_request() → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the delete_schedule response.

Yields

Mocked SwitcherV2DeleteScheduleResponseMSG object.

conftest.mock_disable_enable_schedule_request() → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the disable_enable_schedule response.

Yields

Mocked SwitcherV2DisableEnableScheduleResponseMSG object.

conftest.mock_get_schedules_response(schedule_object) → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the get_schedules response.

Parameters

schedule_object – Fixture of mocked SwitcherV2Schedule object.

Yields

Mocked SwitcherV2GetScheduleResponseMSG object.

conftest.mock_get_state_response() → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the get_state response.

Yields

Mocked SwitcherV2StateResponseMSG object.

conftest.mock_loop() → Generator[asyncio.events.AbstractEventLoop, Any, None][source]

Fixture for running an event loop.

Yields

Test event loop for running test server.

conftest.mock_sanic_test_app() → Generator[sanic.Sanic, Any, None][source]

Fixture for creating a test instance on the sanic app.

Yields

Test sanic application for mocking testing server.

conftest.mock_schedule_object() → Generator[None, None, aioswitcher.schedules.SwitcherV2Schedule][source]

Fixture for the aioswitcher.schedules.SwitcherV2Schedule object.

Returns

Mocked SwitcherV2Schedule object.

conftest.mock_set_auto_shutdown_response() → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the set_auto_shutdown response.

Yields

Mocked SwitcherV2SetAutoOffResponseMSG object.

conftest.mock_set_device_name_response() → Generator[asynctest.MagicMock, Any, None][source]

Fixture for mocking the set_device_name response.

Yields

Mocked SwitcherV2UpdateNameResponseMSG object.

conftest.mock_switcher_api_context_manager() → Generator[None, Any, None][source]

Fixture for mocking the SwitcherV2Api context manager.

conftest.mock_tcp_connection() → Generator[None, Any, None][source]

Fixture for mocking asyncio.open_connection.

conftest.mock_test_client(loop: asyncio.events.AbstractEventLoop, sanic_test_app: sanic.Sanic) → Generator[None, None, asyncio.events.AbstractEventLoop][source]

Fixture for starting server in the event loop.

Parameters
  • loop – Fixture of mocked AbstractEventLoop object.

  • sanic_test_app – Fixture of mocked Sanic object.

Returns

An event loop with a running server.

pyscripts/helpers.py

Helper functions for unit testing the Switcher WebAPI.

helpers.get_local_ip_address() → str[source]

Use for getting the local host’s ip address.

Returns

The local ip address.

helpers.get_next_weekday(is_iso: bool = False) → int[source]

Use for getting next day weekday.

Parameters

is_iso – If true, Monday=1 and Sunday=7. Else Monday=0 and Sunday=6.

Returns

The int value represnting the the next weekday (tommorow).

pyscripts/test_server.py

Unit tests for the Switcher WebAPI.

async test_server.test_create_schedule_request(create_schedule_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/create_schedule request.

Parameters

create_schedule_response – fixture of mocked SwitcherV2CreateScheduleResponseMSG object.

async test_server.test_delete_schedule_request(delete_schedule_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/delete_schedule request.

Parameters

delete_schedule_response – fixture of mocked SwitcherV2DeleteScheduleResponseMSG object.

async test_server.test_disable_schedule_request(disable_enable_schedule_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/disable_schedule request.

Parameters

disable_enable_schedule_response – fixture of mocked SwitcherV2DisableEnableScheduleResponseMSG object.

async test_server.test_enable_schedule_request(disable_enable_schedule_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/enable_schedule request.

Parameters

disable_enable_schedule_response – fixture of mocked SwitcherV2DisableEnableScheduleResponseMSG object.

async test_server.test_get_schedules_request(get_schedules_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/get_schedules request.

Parameters

get_schedules_response – fixture of mocked SwitcherV2GetScheduleResponseMSG object.

async test_server.test_get_state_request(get_state_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/get_state request.

Parameters

get_state_response – fixture of mocked SwitcherV2StateResponseMSG object.

async test_server.test_set_auto_shutdown_request(set_auto_shutdown_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/set_auto_shutdown request.

Parameters

set_auto_shutdown_response – fixture of mocked SwitcherV2SetAutoOffResponseMSG object.

async test_server.test_set_device_name_request(set_device_name_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/set_device_name request.

Parameters

set_device_name_response – fixture of mocked SwitcherV2UpdateNameResponseMSG object.

async test_server.test_turn_off_request(control_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/turn_off request.

Parameters

control_response – fixture of mocked SwitcherV2ControlResponseMSG object.

async test_server.test_turn_on_request(control_response: asynctest.MagicMock) → None[source]

Unit test-cases for /switcher/turn_on request.

Parameters

control_response – fixture of mocked SwitcherV2ControlResponseMSG object.

Shared scripts

pyscripts/consts.py

Various constants and test values for the Switcher WebAPI project.

pyscripts/mappings.py

Url mappings for the Switcher WebAPI project are located here.