Skip to content

Commit aafea92

Browse files
HitaloMHitaloM
authored
feat(storage): make BaseStorage an abstract class and document it
* feat(storage): make `BaseStorage` an abstract class * doc(storage): add documentation for Custom Storage
1 parent 232339c commit aafea92

File tree

8 files changed

+145
-31
lines changed

8 files changed

+145
-31
lines changed

‎docs/source/conf.py‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -162,8 +162,3 @@
162162
},
163163
],
164164
}
165-
166-
latex_theme_options = {
167-
"light_logo": "hydrogram-light.png",
168-
"dark_logo": "hydrogram-dark.png",
169-
}

‎docs/source/topics/storage-engines.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,20 @@ login using the same session; the storage used will still be in-memory:
8383
8484
Session strings are useful when you want to run authorized Hydrogram clients on platforms where their ephemeral
8585
filesystems makes it harder for a file-based storage engine to properly work as intended.
86+
87+
Custom Storages
88+
---------------
89+
90+
If you want to use a custom storage engine, you can do so by implementing the :class:`~hydrogram.storage.BaseStorage` class.
91+
This class is an abstract base class that defines the interface that all storage engines must implement.
92+
93+
An abstract base class is a class that cannot be instantiated, but can be used to define a common interface for its
94+
subclasses. In this case, the :class:`~hydrogram.storage.BaseStorage` class defines the interface that all storage
95+
engines must implement.
96+
97+
Custom Storage can be defined in :class:`~hydrogram.Client` by passing ``session_storage_engine`` parameter with a
98+
:class:`~hydrogram.storage.BaseStorage` subclass.
99+
100+
.. automodule:: hydrogram.storage.base
101+
:members:
102+
:noindex:

‎hydrogram/client.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ class Client(Methods):
115115
Pass a session string to load the session in-memory.
116116
Implies ``in_memory=True``.
117117
118-
session_storage_engine (:obj:`~pyrogram.storage.BaseStorage`, *optional*):
118+
session_storage_engine (:obj:`~hydrogram.storage.BaseStorage`, *optional*):
119119
Pass an instance of your own implementation of session storage engine.
120120
Useful when you want to store your session in databases like Mongo, Redis, etc.
121121

‎hydrogram/storage/base.py‎

Lines changed: 107 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,66 +19,168 @@
1919

2020
import base64
2121
import struct
22+
from abc import ABC, abstractmethod
2223
from typing import List, Tuple
2324

2425

25-
class BaseStorage:
26-
OLD_SESSION_STRING_FORMAT = ">B?256sI?"
27-
OLD_SESSION_STRING_FORMAT_64 = ">B?256sQ?"
28-
SESSION_STRING_SIZE = 351
29-
SESSION_STRING_SIZE_64 = 356
26+
class BaseStorage(ABC):
27+
"""The BaseStorage class is an abstract base class that defines the interface
28+
for different storage engines used by Hyrogram.
29+
30+
Parameters:
31+
name (``str``):
32+
The name of the session.
33+
"""
3034

3135
SESSION_STRING_FORMAT = ">BI?256sQ?"
3236

3337
def __init__(self, name: str):
3438
self.name = name
3539

40+
@abstractmethod
3641
async def open(self):
42+
"""Opens the storage engine."""
3743
raise NotImplementedError
3844

45+
@abstractmethod
3946
async def save(self):
47+
"""Saves the current state of the storage engine."""
4048
raise NotImplementedError
4149

50+
@abstractmethod
4251
async def close(self):
52+
"""Closes the storage engine."""
4353
raise NotImplementedError
4454

55+
@abstractmethod
4556
async def delete(self):
57+
"""Deletes the storage."""
4658
raise NotImplementedError
4759

60+
@abstractmethod
4861
async def update_peers(self, peers: List[Tuple[int, int, str, str, str]]):
62+
"""
63+
Update the peers table with the provided information.
64+
65+
Parameters:
66+
peers (``List[Tuple[int, int, str, str, str]]``): A list of tuples containing the
67+
information of the peers to be updated. Each tuple must contain the following
68+
information:
69+
70+
- ``int``: The peer id.
71+
- ``int``: The peer access hash.
72+
- ``str``: The peer type (user, chat or channel).
73+
- ``str``: The peer username (if any).
74+
- ``str``: The peer phone number (if any).
75+
"""
4976
raise NotImplementedError
5077

78+
@abstractmethod
5179
async def get_peer_by_id(self, peer_id: int):
80+
"""Retrieve a peer by its ID.
81+
82+
Parameters:
83+
peer_id (``int``):
84+
The ID of the peer to retrieve.
85+
"""
5286
raise NotImplementedError
5387

88+
@abstractmethod
5489
async def get_peer_by_username(self, username: str):
90+
"""Retrieve a peer by its username.
91+
92+
Parameters:
93+
username (``str``):
94+
The username of the peer to retrieve.
95+
"""
5596
raise NotImplementedError
5697

98+
@abstractmethod
5799
async def get_peer_by_phone_number(self, phone_number: str):
100+
"""Retrieve a peer by its phone number.
101+
102+
Parameters:
103+
phone_number (``str``):
104+
The phone number of the peer to retrieve.
105+
"""
58106
raise NotImplementedError
59107

108+
@abstractmethod
60109
async def dc_id(self, value: int = object):
110+
"""Get or set the DC ID of the current session.
111+
112+
Parameters:
113+
value (``int``, *optional*):
114+
The DC ID to set.
115+
"""
61116
raise NotImplementedError
62117

118+
@abstractmethod
63119
async def api_id(self, value: int = object):
120+
"""Get or set the API ID of the current session.
121+
122+
Parameters:
123+
value (``int``, *optional*):
124+
The API ID to set.
125+
"""
64126
raise NotImplementedError
65127

128+
@abstractmethod
66129
async def test_mode(self, value: bool = object):
130+
"""Get or set the test mode of the current session.
131+
132+
Parameters:
133+
value (``bool``, *optional*):
134+
The test mode to set.
135+
"""
67136
raise NotImplementedError
68137

138+
@abstractmethod
69139
async def auth_key(self, value: bytes = object):
140+
"""Get or set the authorization key of the current session.
141+
142+
Parameters:
143+
value (``bytes``, *optional*):
144+
The authorization key to set.
145+
"""
70146
raise NotImplementedError
71147

148+
@abstractmethod
72149
async def date(self, value: int = object):
150+
"""Get or set the date of the current session.
151+
152+
Parameters:
153+
value (``int``, *optional*):
154+
The date to set.
155+
"""
73156
raise NotImplementedError
74157

158+
@abstractmethod
75159
async def user_id(self, value: int = object):
160+
"""Get or set the user ID of the current session.
161+
162+
Parameters:
163+
value (``int``, *optional*):
164+
The user ID to set.
165+
"""
76166
raise NotImplementedError
77167

168+
@abstractmethod
78169
async def is_bot(self, value: bool = object):
170+
"""Get or set the bot flag of the current session.
171+
172+
Parameters:
173+
value (``bool``, *optional*):
174+
The bot flag to set.
175+
"""
79176
raise NotImplementedError
80177

81178
async def export_session_string(self):
179+
"""Exports the session string for the current session.
180+
181+
Returns:
182+
``str``: The session string for the current session.
183+
"""
82184
packed = struct.pack(
83185
self.SESSION_STRING_FORMAT,
84186
await self.dc_id(),

‎hydrogram/types/user_and_chats/forum_topic_closed.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# Pyrogram - Telegram MTProto API Client Library for Python
1+
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
33
#
4-
# This file is part of Pyrogram.
4+
# This file is part of Hydrogram.
55
#
6-
# Pyrogram is free software: you can redistribute it and/or modify
6+
# Hydrogram is free software: you can redistribute it and/or modify
77
# it under the terms of the GNU Lesser General Public License as published
88
# by the Free Software Foundation, either version 3 of the License, or
99
# (at your option) any later version.
1010
#
11-
# Pyrogram is distributed in the hope that it will be useful,
11+
# Hydrogram is distributed in the hope that it will be useful,
1212
# but WITHOUT ANY WARRANTY; without even the implied warranty of
1313
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1414
# GNU Lesser General Public License for more details.
1515
#
1616
# You should have received a copy of the GNU Lesser General Public License
17-
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
17+
# along with Hydrogram. If not, see <http://www.gnu.org/licenses/>.
1818

1919
from hydrogram.types.object import Object
2020

‎hydrogram/types/user_and_chats/forum_topic_reopened.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# Pyrogram - Telegram MTProto API Client Library for Python
1+
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
33
#
4-
# This file is part of Pyrogram.
4+
# This file is part of Hydrogram.
55
#
6-
# Pyrogram is free software: you can redistribute it and/or modify
6+
# Hydrogram is free software: you can redistribute it and/or modify
77
# it under the terms of the GNU Lesser General Public License as published
88
# by the Free Software Foundation, either version 3 of the License, or
99
# (at your option) any later version.
1010
#
11-
# Pyrogram is distributed in the hope that it will be useful,
11+
# Hydrogram is distributed in the hope that it will be useful,
1212
# but WITHOUT ANY WARRANTY; without even the implied warranty of
1313
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1414
# GNU Lesser General Public License for more details.
1515
#
1616
# You should have received a copy of the GNU Lesser General Public License
17-
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
17+
# along with Hydrogram. If not, see <http://www.gnu.org/licenses/>.
1818

1919
from hydrogram.types.object import Object
2020

‎hydrogram/types/user_and_chats/general_forum_topic_hidden.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# Pyrogram - Telegram MTProto API Client Library for Python
1+
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
33
#
4-
# This file is part of Pyrogram.
4+
# This file is part of Hydrogram.
55
#
6-
# Pyrogram is free software: you can redistribute it and/or modify
6+
# Hydrogram is free software: you can redistribute it and/or modify
77
# it under the terms of the GNU Lesser General Public License as published
88
# by the Free Software Foundation, either version 3 of the License, or
99
# (at your option) any later version.
1010
#
11-
# Pyrogram is distributed in the hope that it will be useful,
11+
# Hydrogram is distributed in the hope that it will be useful,
1212
# but WITHOUT ANY WARRANTY; without even the implied warranty of
1313
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1414
# GNU Lesser General Public License for more details.
1515
#
1616
# You should have received a copy of the GNU Lesser General Public License
17-
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
17+
# along with Hydrogram. If not, see <http://www.gnu.org/licenses/>.
1818

1919
from hydrogram.types.object import Object
2020

‎hydrogram/types/user_and_chats/general_forum_topic_unhidden.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# Pyrogram - Telegram MTProto API Client Library for Python
1+
# Hydrogram - Telegram MTProto API Client Library for Python
22
# Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
33
#
4-
# This file is part of Pyrogram.
4+
# This file is part of Hydrogram.
55
#
6-
# Pyrogram is free software: you can redistribute it and/or modify
6+
# Hydrogram is free software: you can redistribute it and/or modify
77
# it under the terms of the GNU Lesser General Public License as published
88
# by the Free Software Foundation, either version 3 of the License, or
99
# (at your option) any later version.
1010
#
11-
# Pyrogram is distributed in the hope that it will be useful,
11+
# Hydrogram is distributed in the hope that it will be useful,
1212
# but WITHOUT ANY WARRANTY; without even the implied warranty of
1313
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1414
# GNU Lesser General Public License for more details.
1515
#
1616
# You should have received a copy of the GNU Lesser General Public License
17-
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
17+
# along with Hydrogram. If not, see <http://www.gnu.org/licenses/>.
1818

1919
from hydrogram.types.object import Object
2020

0 commit comments

Comments
 (0)