Mirrored_Repos/python-kasa
1
0
Fork 0
mirror of https://github.com/python-kasa/python-kasa.git synced 2025-12-02 22:28:20 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Update documentation structure and start migrating to markdown (#934)

Browse Source 
Starts structuring the documentation library usage into Tutorials, Guides, Explanations and Reference.
Continues migrating new docs from rst to markdown.
Extends the test framework discovery mocks to allow easy writing and testing of code examples.
This commit is contained in:
Steven B
2024-06-03 12:14:10 +03:00
committed by GitHub
parent 767156421b
commit 6616d68d42
31 changed files with 619 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
kasa/tests/test_readme_examples.py
View File

@@ -3,8 +3,11 @@ import asyncio
import pytest
import xdoctest
from kasa import Discover
from kasa.tests.conftest import get_device_for_fixture_protocol
from kasa.tests.conftest import (
get_device_for_fixture_protocol,
get_fixture_info,
patch_discovery,
)
def test_bulb_examples(mocker):
@@ -62,34 +65,39 @@ def test_lightstrip_examples(mocker):
assert not res["failed"]
def test_discovery_examples(mocker):
def test_discovery_examples(readmes_mock):
"""Test discovery examples."""
p = asyncio.run(get_device_for_fixture_protocol("KP303(UK)_1.0_1.0.3.json", "IOT"))
mocker.patch("kasa.discover.Discover.discover", return_value=[p])
res = xdoctest.doctest_module("kasa.discover", "all")
assert res["n_passed"] > 0
assert not res["failed"]
def test_tutorial_examples(mocker, top_level_await):
def test_deviceconfig_examples(readmes_mock):
"""Test discovery examples."""
a = asyncio.run(
get_device_for_fixture_protocol("L530E(EU)_3.0_1.1.6.json", "SMART")
)
b = asyncio.run(get_device_for_fixture_protocol("HS110(EU)_1.0_1.2.5.json", "IOT"))
a.host = "127.0.0.1"
b.host = "127.0.0.2"
# Note autospec does not work for staticmethods in python < 3.12
# https://github.com/python/cpython/issues/102978
mocker.patch(
"kasa.discover.Discover.discover_single", return_value=a, autospec=True
)
mocker.patch.object(Discover, "discover", return_value=[a, b], autospec=True)
res = xdoctest.doctest_module("docs/tutorial.py", "all")
res = xdoctest.doctest_module("kasa.deviceconfig", "all")
assert res["n_passed"] > 0
assert not res["failed"]
def test_tutorial_examples(readmes_mock):
"""Test discovery examples."""
res = xdoctest.doctest_module("docs/tutorial.py", "all")
assert res["n_passed"] > 0
assert not res["failed"]
@pytest.fixture
async def readmes_mock(mocker, top_level_await):
fixture_infos = {
"127.0.0.1": get_fixture_info("KP303(UK)_1.0_1.0.3.json", "IOT"), # Strip
"127.0.0.2": get_fixture_info("HS110(EU)_1.0_1.2.5.json", "IOT"), # Plug
"127.0.0.3": get_fixture_info("L530E(EU)_3.0_1.1.6.json", "SMART"), # Bulb
"127.0.0.4": get_fixture_info("KL430(US)_1.0_1.0.10.json", "IOT"), # Lightstrip
"127.0.0.5": get_fixture_info("HS220(US)_1.0_1.5.7.json", "IOT"), # Dimmer
}
yield patch_discovery(fixture_infos, mocker)
@pytest.fixture
def top_level_await(mocker):
"""Fixture to enable top level awaits in doctests.
@@ -99,19 +107,26 @@ def top_level_await(mocker):
"""
import ast
from inspect import CO_COROUTINE
from types import CodeType
orig_exec = exec
orig_eval = eval
orig_compile = compile
def patch_exec(source, globals=None, locals=None, /, **kwargs):
if source.co_flags & CO_COROUTINE == CO_COROUTINE:
if (
isinstance(source, CodeType)
and source.co_flags & CO_COROUTINE == CO_COROUTINE
):
asyncio.run(orig_eval(source, globals, locals))
else:
orig_exec(source, globals, locals, **kwargs)
def patch_eval(source, globals=None, locals=None, /, **kwargs):
if source.co_flags & CO_COROUTINE == CO_COROUTINE:
if (
isinstance(source, CodeType)
and source.co_flags & CO_COROUTINE == CO_COROUTINE
):
return asyncio.run(orig_eval(source, globals, locals, **kwargs))
else:
return orig_eval(source, globals, locals, **kwargs)