Skip to content

Commit 2b33743

Browse files
alissonlaufferalissonlauffer
committed
chore: update docstrings
1 parent 50b2697 commit 2b33743

16 files changed

+648
-163
lines changed

‎hydrogram/handlers/callback_query_handler.py‎

Lines changed: 42 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
# along with Hydrogram. If not, see <http://www.gnu.org/licenses/>.
1919

2020
from asyncio import iscoroutinefunction
21-
from typing import Callable, Tuple
21+
from typing import Callable, Optional, Tuple
2222

2323
import hydrogram
2424
from hydrogram.types import CallbackQuery, Identifier, Listener, ListenerTypes
@@ -55,12 +55,16 @@ def __init__(self, callback: Callable, filters=None):
5555
self.original_callback = callback
5656
super().__init__(self.resolve_future_or_callback, filters)
5757

58-
def compose_data_identifier(self, query: CallbackQuery):
58+
def compose_data_identifier(self, query: CallbackQuery) -> Identifier:
5959
"""
6060
Composes an Identifier object from a CallbackQuery object.
6161
62-
:param query: The CallbackQuery object to compose of.
63-
:return: An Identifier object.
62+
Parameters:
63+
query (:obj:`~hydrogram.types.CallbackQuery`):
64+
The CallbackQuery object to compose of.
65+
66+
Returns:
67+
:obj:`~hydrogram.types.Identifier`: An Identifier object.
6468
"""
6569
from_user = query.from_user
6670
from_user_id = from_user.id if from_user else None
@@ -84,15 +88,20 @@ def compose_data_identifier(self, query: CallbackQuery):
8488

8589
async def check_if_has_matching_listener(
8690
self, client: "hydrogram.Client", query: CallbackQuery
87-
) -> Tuple[bool, Listener]:
91+
) -> Tuple[bool, Optional[Listener]]:
8892
"""
8993
Checks if the CallbackQuery object has a matching listener.
9094
91-
:param client: The Client object to check with.
92-
:param query: The CallbackQuery object to check with.
93-
:return: A tuple of a boolean and a Listener object. The boolean indicates whether
94-
the found listener has filters and its filters matches with the CallbackQuery object.
95-
The Listener object is the matching listener.
95+
Parameters:
96+
client (:obj:`~hydrogram.Client`):
97+
The Client object to check with.
98+
99+
query (:obj:`~hydrogram.types.CallbackQuery`):
100+
The CallbackQuery object to check with.
101+
102+
Returns:
103+
A tuple of whether the CallbackQuery object has a matching listener and its filters does match with the
104+
CallbackQuery and the matching listener;
96105
"""
97106
data = self.compose_data_identifier(query)
98107

@@ -114,14 +123,19 @@ async def check_if_has_matching_listener(
114123

115124
return listener_does_match, listener
116125

117-
async def check(self, client: "hydrogram.Client", query: CallbackQuery):
126+
async def check(self, client: "hydrogram.Client", query: CallbackQuery) -> bool:
118127
"""
119128
Checks if the CallbackQuery object has a matching listener or handler.
120129
121-
:param client: The Client object to check with.
122-
:param query: The CallbackQuery object to check with.
123-
:return: A boolean indicating whether the CallbackQuery object has a matching listener or the handler
124-
filter matches.
130+
Parameters:
131+
client (:obj:`~hydrogram.Client`):
132+
The Client object to check with.
133+
134+
query (:obj:`~hydrogram.types.CallbackQuery`):
135+
The CallbackQuery object to check with.
136+
137+
Returns:
138+
``bool``: A boolean indicating whether the CallbackQuery object has a matching listener or the handler filter matches.
125139
"""
126140
listener_does_match, listener = await self.check_if_has_matching_listener(client, query)
127141

@@ -167,14 +181,22 @@ async def check(self, client: "hydrogram.Client", query: CallbackQuery):
167181

168182
async def resolve_future_or_callback(
169183
self, client: "hydrogram.Client", query: CallbackQuery, *args
170-
):
184+
) -> None:
171185
"""
172186
Resolves the future or calls the callback of the listener. Will call the original handler if no listener.
173187
174-
:param client: The Client object to resolve or call with.
175-
:param query: The CallbackQuery object to resolve or call with.
176-
:param args: The arguments to call the callback with.
177-
:return: None
188+
Parameters:
189+
client (:obj:`~hydrogram.Client`):
190+
The Client object to resolve or call with.
191+
192+
query (:obj:`~hydrogram.types.CallbackQuery`):
193+
The CallbackQuery object to resolve or call with.
194+
195+
args:
196+
The arguments to call the callback with.
197+
198+
Returns:
199+
``None``
178200
"""
179201
listener_does_match, listener = await self.check_if_has_matching_listener(client, query)
180202

‎hydrogram/handlers/message_handler.py‎

Lines changed: 34 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@
1818
# along with Hydrogram. If not, see <http://www.gnu.org/licenses/>.
1919

2020
from inspect import iscoroutinefunction
21-
from typing import Callable
21+
from typing import Callable, Optional, Tuple
2222

2323
import hydrogram
24-
from hydrogram.types import Identifier, ListenerTypes, Message
24+
from hydrogram.types import Identifier, Listener, ListenerTypes, Message
2525

2626
from .handler import Handler
2727

@@ -54,14 +54,22 @@ def __init__(self, callback: Callable, filters=None):
5454
self.original_callback = callback
5555
super().__init__(self.resolve_future_or_callback, filters)
5656

57-
async def check_if_has_matching_listener(self, client: "hydrogram.Client", message: Message):
57+
async def check_if_has_matching_listener(
58+
self, client: "hydrogram.Client", message: Message
59+
) -> Tuple[bool, Optional[Listener]]:
5860
"""
5961
Checks if the message has a matching listener.
6062
61-
:param client: The Client object to check with.
62-
:param message: The Message object to check with.
63-
:return: A tuple of whether the message has a matching listener and its filters does match with the Message
64-
and the matching listener;
63+
Parameters:
64+
client (:obj:`~hydrogram.Client`):
65+
The Client object to check with.
66+
67+
message (:obj:`~hydrogram.types.Message`):
68+
The Message object to check with.
69+
70+
Returns:
71+
``tuple``: A tuple of two elements, the first one is whether the message has a matching listener or not,
72+
the second one is the matching listener if exists.
6573
"""
6674
from_user = message.from_user
6775
from_user_id = from_user.id if from_user else None
@@ -93,13 +101,19 @@ async def check_if_has_matching_listener(self, client: "hydrogram.Client", messa
93101

94102
return listener_does_match, listener
95103

96-
async def check(self, client: "hydrogram.Client", message: Message):
104+
async def check(self, client: "hydrogram.Client", message: Message) -> bool:
97105
"""
98106
Checks if the message has a matching listener or handler and its filters does match with the Message.
99107
100-
:param client: Client object to check with.
101-
:param message: Message object to check with.
102-
:return: Whether the message has a matching listener or handler and its filters does match with the Message.
108+
Parameters:
109+
client (:obj:`~hydrogram.Client`):
110+
The Client object to check with.
111+
112+
message (:obj:`~hydrogram.types.Message`):
113+
The Message object to check with.
114+
115+
Returns:
116+
``bool``: Whether the message has a matching listener or handler and its filters does match with the Message.
103117
"""
104118
listener_does_match = (await self.check_if_has_matching_listener(client, message))[0]
105119

@@ -123,10 +137,15 @@ async def resolve_future_or_callback(
123137
"""
124138
Resolves the future or calls the callback of the listener if the message has a matching listener.
125139
126-
:param client: Client object to resolve or call with.
127-
:param message: Message object to resolve or call with.
128-
:param args: Arguments to call the callback with.
129-
:return: None
140+
Parameters:
141+
client (:obj:`~hydrogram.Client`):
142+
The Client object to resolve or call with.
143+
144+
message (:obj:`~hydrogram.types.Message`):
145+
The Message object to resolve or call with.
146+
147+
args (``tuple``):
148+
Arguments to call the callback with.
130149
"""
131150
listener_does_match, listener = await self.check_if_has_matching_listener(client, message)
132151

‎hydrogram/helpers/helpers.py‎

Lines changed: 65 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717
# You should have received a copy of the GNU Lesser General Public License
1818
# along with Hydrogram. If not, see <http://www.gnu.org/licenses/>.
1919

20+
from typing import List, Optional, Tuple, Union
21+
2022
from hydrogram.types import (
2123
ForceReply,
2224
InlineKeyboardButton,
@@ -26,11 +28,16 @@
2628
)
2729

2830

29-
def ikb(rows=None):
31+
def ikb(rows: Optional[List[List[Union[str, Tuple[str, str]]]]] = None) -> InlineKeyboardMarkup:
3032
"""
3133
Create an InlineKeyboardMarkup from a list of lists of buttons.
32-
:param rows: List of lists of buttons. Defaults to empty list.
33-
:return: InlineKeyboardMarkup
34+
35+
Parameters:
36+
rows (List[List[Union[str, Tuple[str, str]]]]):
37+
List of lists of buttons. Defaults to empty list.
38+
39+
Returns:
40+
:obj:`~hydrogram.types.InlineKeyboardMarkup`: An InlineKeyboardMarkup object.
3441
"""
3542
if rows is None:
3643
rows = []
@@ -48,26 +55,38 @@ def ikb(rows=None):
4855
# return {'inline_keyboard': lines}
4956

5057

51-
def btn(text, value, type="callback_data"):
58+
def btn(text: str, value: str, type="callback_data") -> InlineKeyboardButton:
5259
"""
5360
Create an InlineKeyboardButton.
5461
55-
:param text: Text of the button.
56-
:param value: Value of the button.
57-
:param type: Type of the button. Defaults to "callback_data".
58-
:return: InlineKeyboardButton
62+
Parameters:
63+
text (str):
64+
Text of the button.
65+
66+
value (str):
67+
Value of the button.
68+
69+
type (str):
70+
Type of the button. Defaults to "callback_data".
71+
72+
Returns:
73+
:obj:`~hydrogram.types.InlineKeyboardButton`: An InlineKeyboardButton object.
5974
"""
6075
return InlineKeyboardButton(text, **{type: value})
6176
# return {'text': text, type: value}
6277

6378

64-
# The inverse of above
65-
def bki(keyboard):
79+
# The inverse of ikb()
80+
def bki(keyboard: InlineKeyboardButton) -> List[List[Union[str, Tuple[str, str]]]]:
6681
"""
6782
Create a list of lists of buttons from an InlineKeyboardMarkup.
6883
69-
:param keyboard: InlineKeyboardMarkup
70-
:return: List of lists of buttons
84+
Parameters:
85+
keyboard (:obj:`~hydrogram.types.InlineKeyboardMarkup`):
86+
An InlineKeyboardMarkup object.
87+
88+
Returns:
89+
List of lists of buttons.
7190
"""
7291
lines = []
7392
for row in keyboard.inline_keyboard:
@@ -80,12 +99,16 @@ def bki(keyboard):
8099
# return ikb() format
81100

82101

83-
def ntb(button):
102+
def ntb(button: InlineKeyboardButton) -> list:
84103
"""
85104
Create a button list from an InlineKeyboardButton.
86105
87-
:param button: InlineKeyboardButton
88-
:return: Button as a list to be used in btn()
106+
Parameters:
107+
button (:obj:`~hydrogram.types.InlineKeyboardButton`):
108+
An InlineKeyboardButton object.
109+
110+
Returns:
111+
``list``: A button list.
89112
"""
90113
for btn_type in [
91114
"callback_data",
@@ -104,13 +127,19 @@ def ntb(button):
104127
# return {'text': text, type: value}
105128

106129

107-
def kb(rows=None, **kwargs):
130+
def kb(rows=None, **kwargs) -> ReplyKeyboardMarkup:
108131
"""
109132
Create a ReplyKeyboardMarkup from a list of lists of buttons.
110133
111-
:param rows: List of lists of buttons. Defaults to empty list.
112-
:param kwargs: Other arguments to pass to ReplyKeyboardMarkup.
113-
:return: ReplyKeyboardMarkup
134+
Parameters:
135+
rows (List[List[str]]):
136+
List of lists of buttons. Defaults to an empty list.
137+
138+
kwargs:
139+
Other arguments to pass to ReplyKeyboardMarkup.
140+
141+
Returns:
142+
:obj:`~hydrogram.types.ReplyKeyboardMarkup`: A ReplyKeyboardMarkup object.
114143
"""
115144
if rows is None:
116145
rows = []
@@ -136,22 +165,32 @@ def kb(rows=None, **kwargs):
136165
"""
137166

138167

139-
def force_reply(selective=True):
168+
def force_reply(selective=True) -> ForceReply:
140169
"""
141170
Create a ForceReply.
142171
143-
:param selective: Whether the reply should be selective. Defaults to True.
144-
:return: ForceReply
172+
Parameters:
173+
selective (bool):
174+
Whether the reply should be selective. Defaults to True.
175+
176+
Returns:
177+
:obj:`~hydrogram.types.ForceReply`: A ForceReply object.
145178
"""
146179
return ForceReply(selective=selective)
147180

148181

149-
def array_chunk(input_array, size):
182+
def array_chunk(input_array, size) -> List[List]:
150183
"""
151184
Split an array into chunks.
152185
153-
:param input_array: The array to split.
154-
:param size: The size of each chunk.
155-
:return: List of chunks.
186+
Parameters:
187+
input_array (list):
188+
The array to split.
189+
190+
size (int):
191+
The size of each chunk.
192+
193+
Returns:
194+
list: A list of chunks.
156195
"""
157196
return [input_array[i : i + size] for i in range(0, len(input_array), size)]

0 commit comments

Comments
 (0)