From 38145b87dee7d7447581bfae5c3a92fe3fe8aef0 Mon Sep 17 00:00:00 2001 From: "Ilia (Elias) Motornyi" Date: Tue, 23 Jul 2024 11:53:29 +0300 Subject: [PATCH 1/8] Update network.pyi a bit, Fixes #241 --- typehints/micropython/network.pyi | 77 ++++++++++++++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index ef84a3b0..722dcb1a 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -3,6 +3,7 @@ network configuration. Descriptions taken from: https://raw.githubusercontent.com/micropython/micropython/master/docs/library/network.rst. +https://github.com/Josverl/micropython-stubs/blob/main/stubs/micropython-v1_19_1-esp32-GENERIC/network.py **************************************** .. module:: network @@ -45,10 +46,49 @@ __license__ = "MIT https://opensource.org/licenses/MIT (as used by MicroPython). __version__ = "7.3.0" # Version set by https://github.com/hlovatt/tag2ver from abc import abstractmethod -from typing import Protocol, Callable, overload, Any, ClassVar, Final +from typing import Protocol, Callable, overload, Any, ClassVar, Final, NoReturn import pyb +@overload +def country(code: str, /) -> NoReturn | str: + """ + Get or set the two-letter ISO 3166-1 Alpha-2 country code to be used for + radio compliance. + + If the *code* parameter is provided, the country will be set to this value. + If the function is called without parameters, it returns the current + country. + + The default code ``"XX"`` represents the "worldwide" region. + """ + +def hostname(self, name: str) -> NoReturn | str: + """Get or set the hostname that will identify this device on the network. It will + be used by all interfaces. + + This hostname is used for: + * Sending to the DHCP server in the client request. (If using DHCP) + * Broadcasting via mDNS. (If enabled) + + If the *name* parameter is provided, the hostname will be set to this value. + If the function is called without parameters, it returns the current + hostname. + + A change in hostname is typically only applied during connection. For DHCP + this is because the hostname is part of the DHCP client request, and the + implementation of mDNS in most ports only initialises the hostname once + during connection. For this reason, you must set the hostname before + activating/connecting your network interfaces. + + The length of the hostname is limited to 32 characters. + :term:`MicroPython ports ` may choose to set a lower + limit for memory reasons. If the given name does not fit, a `ValueError` + is raised. + + The default hostname is typically the name of the board. + """ + MODE_11B: Final[int] = ... """IEEE 802.11b""" @@ -57,6 +97,41 @@ MODE_11G: Final[int] = ... MODE_11N: Final[int] = ... """IEEE 802.11n""" + +STA_IF:int = 0 +"""station interface""" + +AP_IF:int = 1 +"""access point interface""" + +STAT_IDLE:int = 0 +"""no connection and no activity""" + +STAT_CONNECTING:int = 1 +"""connecting in progress""" + +STAT_WRONG_PASSWORD:int = 2 +"""failed due to incorrect password""" + +STAT_NO_AP_FOUND:int = 3 +"""failed because no access point replied""" + +STAT_CONNECT_FAIL:int = 4 +"""failed due to other problems""" + +STAT_GOT_IP:int = 5 +"""connection successful""" + +AUTH_OPEN:int = 0 + +AUTH_WEP:int = 1 + +AUTH_WPA_PSK:int = 2 + +AUTH_WPA2_PSK:int = 3 + +AUTH_WPA_WPA2_PSK:int = 4 + @overload def phy_mode(self) -> int: """ From a75bfabf1487a2f5ae9333445f4c481b3488d851 Mon Sep 17 00:00:00 2001 From: Pavel Karateev Date: Tue, 23 Jul 2024 13:16:11 +0200 Subject: [PATCH 2/8] `country()` and `hostname()` always return --- typehints/micropython/network.pyi | 32 +++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index 722dcb1a..d557ebbc 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -46,12 +46,12 @@ __license__ = "MIT https://opensource.org/licenses/MIT (as used by MicroPython). __version__ = "7.3.0" # Version set by https://github.com/hlovatt/tag2ver from abc import abstractmethod -from typing import Protocol, Callable, overload, Any, ClassVar, Final, NoReturn +from typing import Protocol, Callable, overload, Any, ClassVar, Final import pyb @overload -def country(code: str, /) -> NoReturn | str: +def country(code: str, /) -> str: """ Get or set the two-letter ISO 3166-1 Alpha-2 country code to be used for radio compliance. @@ -63,7 +63,7 @@ def country(code: str, /) -> NoReturn | str: The default code ``"XX"`` represents the "worldwide" region. """ -def hostname(self, name: str) -> NoReturn | str: +def hostname(self, name: str) -> str: """Get or set the hostname that will identify this device on the network. It will be used by all interfaces. @@ -98,39 +98,39 @@ MODE_11G: Final[int] = ... MODE_11N: Final[int] = ... """IEEE 802.11n""" -STA_IF:int = 0 +STA_IF: int = 0 """station interface""" -AP_IF:int = 1 +AP_IF: int = 1 """access point interface""" -STAT_IDLE:int = 0 +STAT_IDLE: int = 0 """no connection and no activity""" -STAT_CONNECTING:int = 1 +STAT_CONNECTING: int = 1 """connecting in progress""" -STAT_WRONG_PASSWORD:int = 2 +STAT_WRONG_PASSWORD: int = 2 """failed due to incorrect password""" -STAT_NO_AP_FOUND:int = 3 +STAT_NO_AP_FOUND: int = 3 """failed because no access point replied""" -STAT_CONNECT_FAIL:int = 4 +STAT_CONNECT_FAIL: int = 4 """failed due to other problems""" -STAT_GOT_IP:int = 5 +STAT_GOT_IP: int = 5 """connection successful""" -AUTH_OPEN:int = 0 +AUTH_OPEN: int = 0 -AUTH_WEP:int = 1 +AUTH_WEP: int = 1 -AUTH_WPA_PSK:int = 2 +AUTH_WPA_PSK: int = 2 -AUTH_WPA2_PSK:int = 3 +AUTH_WPA2_PSK: int = 3 -AUTH_WPA_WPA2_PSK:int = 4 +AUTH_WPA_WPA2_PSK: int = 4 @overload def phy_mode(self) -> int: From 7451dd00718e117e9ec8fe4c2220500570abe1f3 Mon Sep 17 00:00:00 2001 From: Pavel Karateev Date: Tue, 23 Jul 2024 13:17:04 +0200 Subject: [PATCH 3/8] `country()` has no other overloads --- typehints/micropython/network.pyi | 1 - 1 file changed, 1 deletion(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index d557ebbc..b66a8773 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -50,7 +50,6 @@ from typing import Protocol, Callable, overload, Any, ClassVar, Final import pyb -@overload def country(code: str, /) -> str: """ Get or set the two-letter ISO 3166-1 Alpha-2 country code to be used for From e4f8093c74e724a506b38027b1a59bc7480e90ae Mon Sep 17 00:00:00 2001 From: Pavel Karateev Date: Tue, 23 Jul 2024 13:20:03 +0200 Subject: [PATCH 4/8] `country()` and `hostname()` can be called with no arguments provided --- typehints/micropython/network.pyi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index b66a8773..a35893ee 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -50,7 +50,7 @@ from typing import Protocol, Callable, overload, Any, ClassVar, Final import pyb -def country(code: str, /) -> str: +def country(code: str = "", /) -> str: """ Get or set the two-letter ISO 3166-1 Alpha-2 country code to be used for radio compliance. @@ -62,7 +62,7 @@ def country(code: str, /) -> str: The default code ``"XX"`` represents the "worldwide" region. """ -def hostname(self, name: str) -> str: +def hostname(self, name: str = "") -> str: """Get or set the hostname that will identify this device on the network. It will be used by all interfaces. From ba825110c1715eacbca4b6d9937ee8654e2d7c1e Mon Sep 17 00:00:00 2001 From: Pavel Karateev Date: Tue, 23 Jul 2024 13:21:11 +0200 Subject: [PATCH 5/8] `hostname()` has no `self` parameter --- typehints/micropython/network.pyi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index a35893ee..78233ef8 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -62,7 +62,7 @@ def country(code: str = "", /) -> str: The default code ``"XX"`` represents the "worldwide" region. """ -def hostname(self, name: str = "") -> str: +def hostname(name: str = "") -> str: """Get or set the hostname that will identify this device on the network. It will be used by all interfaces. From 2263688664aad1cf14e897bceeac904f40a23067 Mon Sep 17 00:00:00 2001 From: Pavel Karateev Date: Tue, 23 Jul 2024 13:27:46 +0200 Subject: [PATCH 6/8] Declare `hostname()` arguments positional-only --- typehints/micropython/network.pyi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index 78233ef8..83feace8 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -62,7 +62,7 @@ def country(code: str = "", /) -> str: The default code ``"XX"`` represents the "worldwide" region. """ -def hostname(name: str = "") -> str: +def hostname(name: str = "", /) -> str: """Get or set the hostname that will identify this device on the network. It will be used by all interfaces. From 323cebeb252771ac0bd299923d1f414de6eab573 Mon Sep 17 00:00:00 2001 From: "Ilia (Elias) Motornyi" Date: Tue, 23 Jul 2024 16:29:42 +0300 Subject: [PATCH 7/8] Two variants for `hostname()` and `country()` --- typehints/micropython/network.pyi | 43 +++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index 83feace8..2333edf4 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -46,33 +46,48 @@ __license__ = "MIT https://opensource.org/licenses/MIT (as used by MicroPython). __version__ = "7.3.0" # Version set by https://github.com/hlovatt/tag2ver from abc import abstractmethod -from typing import Protocol, Callable, overload, Any, ClassVar, Final +from typing import Protocol, Callable, overload, Any, ClassVar, Final, NoReturn import pyb -def country(code: str = "", /) -> str: +@overload +def country() -> str: """ - Get or set the two-letter ISO 3166-1 Alpha-2 country code to be used for + Get the two-letter ISO 3166-1 Alpha-2 country code to be used for radio compliance. - If the *code* parameter is provided, the country will be set to this value. - If the function is called without parameters, it returns the current - country. + The default code ``"XX"`` represents the "worldwide" region. + """ + +@overload +def country(code: str) -> NoReturn: + """ + Set the two-letter ISO 3166-1 Alpha-2 country code to be used for + radio compliance. The default code ``"XX"`` represents the "worldwide" region. """ -def hostname(name: str = "", /) -> str: - """Get or set the hostname that will identify this device on the network. It will +@overload +def hostname() -> str: + """Get the hostname that will identify this device on the network. It will be used by all interfaces. This hostname is used for: * Sending to the DHCP server in the client request. (If using DHCP) * Broadcasting via mDNS. (If enabled) - If the *name* parameter is provided, the hostname will be set to this value. - If the function is called without parameters, it returns the current - hostname. + The default hostname is typically the name of the board. + """ + +@overload +def hostname(name: str) -> NoReturn: + """Set the hostname that will identify this device on the network. It will + be used by all interfaces. + + This hostname is used for: + * Sending to the DHCP server in the client request. (If using DHCP) + * Broadcasting via mDNS. (If enabled) A change in hostname is typically only applied during connection. For DHCP this is because the hostname is part of the DHCP client request, and the @@ -123,7 +138,7 @@ STAT_GOT_IP: int = 5 AUTH_OPEN: int = 0 -AUTH_WEP: int = 1 +AUTH_WEP:int = 1 AUTH_WPA_PSK: int = 2 @@ -132,7 +147,7 @@ AUTH_WPA2_PSK: int = 3 AUTH_WPA_WPA2_PSK: int = 4 @overload -def phy_mode(self) -> int: +def phy_mode() -> int: """ Get or set the PHY mode. @@ -148,7 +163,7 @@ def phy_mode(self) -> int: """ @overload -def phy_mode(self, mode: int, /) -> None: +def phy_mode(mode: int, /) -> None: """ Get or set the PHY mode. From bd81323c3937ec647de95dac527e74fae9cd57af Mon Sep 17 00:00:00 2001 From: "Ilia (Elias) Motornyi" Date: Tue, 23 Jul 2024 17:41:31 +0300 Subject: [PATCH 8/8] None instead of Noreturn --- typehints/micropython/network.pyi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/typehints/micropython/network.pyi b/typehints/micropython/network.pyi index 2333edf4..c7d23c97 100644 --- a/typehints/micropython/network.pyi +++ b/typehints/micropython/network.pyi @@ -46,7 +46,7 @@ __license__ = "MIT https://opensource.org/licenses/MIT (as used by MicroPython). __version__ = "7.3.0" # Version set by https://github.com/hlovatt/tag2ver from abc import abstractmethod -from typing import Protocol, Callable, overload, Any, ClassVar, Final, NoReturn +from typing import Protocol, Callable, overload, Any, ClassVar, Final import pyb @@ -60,7 +60,7 @@ def country() -> str: """ @overload -def country(code: str) -> NoReturn: +def country(code: str) -> None: """ Set the two-letter ISO 3166-1 Alpha-2 country code to be used for radio compliance. @@ -81,7 +81,7 @@ def hostname() -> str: """ @overload -def hostname(name: str) -> NoReturn: +def hostname(name: str) -> None: """Set the hostname that will identify this device on the network. It will be used by all interfaces.