spluspy 1.0.0__tar.gz → 1.0.2__tar.gz

spluspy-1.0.2/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: spluspy
+Version: 1.0.2
+Summary: Soroush Plus library for Python
+Home-page: https://github.com/Itskillmaster/spluspy
+Download-URL: https://github.com/Itskillmaster/spluspy/releases
+Author: AliMirshekari And Soroush Fathi
+Author-email: dramff1@gmail.com
+License: GPL-3.0
+Keywords: soroush plus telegram api chat client library messaging mtproto
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Communications :: Chat
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Requires-Python: >=3.5
+Description-Content-Type: text/x-rst
+Requires-Dist: pyaes
+Requires-Dist: rsa
+Requires-Dist: websockets
+Provides-Extra: cryptg
+Requires-Dist: cryptg; extra == "cryptg"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+SPlusPy
+=======
+
+**SPlusPy** is an asynchronous Python 3 MTProto library for interacting
+with the `Soroush Plus <https://web.splus.ir>`_ platform as either a
+user account or a bot account (an alternative to the official Bot API).
+
+Built as a fork of Telethon, SPlusPy has been adapted specifically for
+the Soroush Plus ecosystem. It supports the native Soroush Plus TL
+schema (Layer 182), DC routing, RSA encryption, and WebSocket transport,
+providing a modern and reliable developer experience.
+
+.. note::
+
+   SPlusPy is an unofficial third-party library. Please use it
+   responsibly and ensure your applications comply with Soroush Plus's
+   Terms of Service. Improper use may result in account restrictions.
+
+Features
+--------
+
+- Fully asynchronous (``asyncio``)
+- User and bot account support
+- Native MTProto implementation
+- WebSocket transport
+- RSA encryption
+- Soroush Plus TL schema (Layer 182)
+- Based on the Telethon architecture
+- Modern Python 3 support
+- Convenience methods for sending files, photos, audio, video
+- Chat management: ban, unban, kick, pin/unpin messages
+- Admin and permissions management
+- High-performance encryption with optional ``cryptg`` support
+
+What is SPlusPy?
+----------------
+
+`Soroush Plus <https://web.splus.ir>`_ is a popular messaging platform.
+
+SPlusPy provides a clean, Pythonic interface for communicating with the
+Soroush Plus MTProto API. Instead of implementing the protocol yourself,
+you can focus entirely on building your application while SPlusPy
+handles authentication, networking, serialization, and protocol details.
+
+Installing
+----------
+
+Install the latest version from PyPI:
+
+.. code-block:: sh
+
+   pip install -U splusthon
+
+For faster encryption (recommended):
+
+.. code-block:: sh
+
+   pip install cryptg
+
+Creating a client
+-----------------
+
+SPlusPy includes the default Soroush Plus API credentials, so there is
+no need to obtain your own ``api_id`` or ``api_hash``.
+
+.. code-block:: python
+
+   import asyncio
+   from spluspy import SoroushClient
+
+   bot = SoroushClient('my_bot')
+
+   @bot.on_message(incoming=True)
+   async def handler(event):
+       if event.is_private and event.raw_text == 'Hello':
+           await event.reply('Hi!')
+
+   async def main():
+       await bot.start()
+       print('Bot is running!')
+       await bot.run_until_disconnected()
+
+   asyncio.run(main())
+
+Quick Examples
+--------------
+
+Sending messages and files:
+
+.. code-block:: python
+
+   # Send a text message
+   await client.send_message('username', 'Hello!')
+
+   # Send a photo
+   await client.send_photo(chat, 'photo.jpg', caption='Check this out!')
+
+   # Send audio/music
+   await client.send_audio(chat, 'song.mp3')
+
+   # Send a video
+   await client.send_video(chat, 'video.mp4')
+
+   # Send a document
+   await client.send_document(chat, 'file.pdf')
+
+Chat management:
+
+.. code-block:: python
+
+   # Ban a user
+   await client.ban_chat_member(chat, user)
+
+   # Unban a user
+   await client.unban_chat_member(chat, user)
+
+   # Pin a message
+   await client.pin_message(chat, message)
+
+   # Unpin all messages
+   await client.unpin_all_messages(chat)
+
+Documentation
+-------------
+
+More examples and complete documentation will be available in future
+releases.
+
+License
+-------
+
+SPlusPy is open-source software distributed under its respective
+license.

spluspy-1.0.2/README.rst

@@ -0,0 +1,133 @@
+SPlusPy
+=======
+
+**SPlusPy** is an asynchronous Python 3 MTProto library for interacting
+with the `Soroush Plus <https://web.splus.ir>`_ platform as either a
+user account or a bot account (an alternative to the official Bot API).
+
+Built as a fork of Telethon, SPlusPy has been adapted specifically for
+the Soroush Plus ecosystem. It supports the native Soroush Plus TL
+schema (Layer 182), DC routing, RSA encryption, and WebSocket transport,
+providing a modern and reliable developer experience.
+
+.. note::
+
+   SPlusPy is an unofficial third-party library. Please use it
+   responsibly and ensure your applications comply with Soroush Plus's
+   Terms of Service. Improper use may result in account restrictions.
+
+Features
+--------
+
+- Fully asynchronous (``asyncio``)
+- User and bot account support
+- Native MTProto implementation
+- WebSocket transport
+- RSA encryption
+- Soroush Plus TL schema (Layer 182)
+- Based on the Telethon architecture
+- Modern Python 3 support
+- Convenience methods for sending files, photos, audio, video
+- Chat management: ban, unban, kick, pin/unpin messages
+- Admin and permissions management
+- High-performance encryption with optional ``cryptg`` support
+
+What is SPlusPy?
+----------------
+
+`Soroush Plus <https://web.splus.ir>`_ is a popular messaging platform.
+
+SPlusPy provides a clean, Pythonic interface for communicating with the
+Soroush Plus MTProto API. Instead of implementing the protocol yourself,
+you can focus entirely on building your application while SPlusPy
+handles authentication, networking, serialization, and protocol details.
+
+Installing
+----------
+
+Install the latest version from PyPI:
+
+.. code-block:: sh
+
+   pip install -U splusthon
+
+For faster encryption (recommended):
+
+.. code-block:: sh
+
+   pip install cryptg
+
+Creating a client
+-----------------
+
+SPlusPy includes the default Soroush Plus API credentials, so there is
+no need to obtain your own ``api_id`` or ``api_hash``.
+
+.. code-block:: python
+
+   import asyncio
+   from spluspy import SoroushClient
+
+   bot = SoroushClient('my_bot')
+
+   @bot.on_message(incoming=True)
+   async def handler(event):
+       if event.is_private and event.raw_text == 'Hello':
+           await event.reply('Hi!')
+
+   async def main():
+       await bot.start()
+       print('Bot is running!')
+       await bot.run_until_disconnected()
+
+   asyncio.run(main())
+
+Quick Examples
+--------------
+
+Sending messages and files:
+
+.. code-block:: python
+
+   # Send a text message
+   await client.send_message('username', 'Hello!')
+
+   # Send a photo
+   await client.send_photo(chat, 'photo.jpg', caption='Check this out!')
+
+   # Send audio/music
+   await client.send_audio(chat, 'song.mp3')
+
+   # Send a video
+   await client.send_video(chat, 'video.mp4')
+
+   # Send a document
+   await client.send_document(chat, 'file.pdf')
+
+Chat management:
+
+.. code-block:: python
+
+   # Ban a user
+   await client.ban_chat_member(chat, user)
+
+   # Unban a user
+   await client.unban_chat_member(chat, user)
+
+   # Pin a message
+   await client.pin_message(chat, message)
+
+   # Unpin all messages
+   await client.unpin_all_messages(chat)
+
+Documentation
+-------------
+
+More examples and complete documentation will be available in future
+releases.
+
+License
+-------
+
+SPlusPy is open-source software distributed under its respective
+license.

{spluspy-1.0.0 → spluspy-1.0.2}/setup.py

@@ -216,6 +216,7 @@ def main(argv):
             version=version,
             description="Soroush Plus library for Python",
             long_description=long_description,
+            long_description_content_type='text/x-rst',
 
             url='https://github.com/Itskillmaster/spluspy',
             download_url='https://github.com/Itskillmaster/spluspy/releases',
@@ -225,16 +226,9 @@ def main(argv):
 
             license='GPL-3.0',
 
-            # See https://stackoverflow.com/a/40300957/4759433
-            # -> https://www.python.org/dev/peps/pep-0345/#requires-python
-            # -> http://setuptools.readthedocs.io/en/latest/setuptools.html
             python_requires='>=3.5',
 
-            # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
             classifiers=[
-                #   3 - Alpha
-                #   4 - Beta
-                #   5 - Production/Stable
                 'Development Status :: 5 - Production/Stable',
 
                 'Intended Audience :: Developers',
@@ -248,7 +242,7 @@ def main(argv):
                 'Programming Language :: Python :: 3.7',
                 'Programming Language :: Python :: 3.8',
             ],
-            keywords='telegram api chat client library messaging mtproto',
+            keywords='soroush plus telegram api chat client library messaging mtproto',
             packages=find_packages(exclude=[
                 'spluspy_*', 'tests*'
             ]),

{spluspy-1.0.0 → spluspy-1.0.2}/spluspy/__init__.py

@@ -5,6 +5,7 @@ from .tl import patched as _  # import for its side-effects
 from . import version, events, utils, errors, types, functions, custom
 from .sessions import Session, MemorySession, SQLiteSession, StringSession
 from .tl.custom import Conversation, Message, Dialog, Forward, Draft
+from .client.ratelimiter import RateLimiter, RetryConfig
 
 __version__ = version.__version__
 
@@ -16,5 +17,6 @@ __all__ = [
     'Session', 'MemorySession', 'SQLiteSession', 'StringSession',
     'Conversation', 'Message', 'Dialog', 'Forward', 'Draft',
     'types', 'functions', 'custom', 'errors',
-    'events', 'utils', 'connection'
+    'events', 'utils', 'connection',
+    'RateLimiter', 'RetryConfig'
 ]

{spluspy-1.0.0 → spluspy-1.0.2}/spluspy/client/chats.py

@@ -1334,3 +1334,249 @@ class ChatMethods:
             await self._return_exported_sender(sender)
 
     # endregion
+
+    # region Convenience methods
+
+    async def ban_chat_member(
+            self: 'SoroushClient',
+            chat: 'hints.EntityLike',
+            user: 'hints.EntityLike',
+            *,
+            until_date: 'hints.DateLike' = None,
+            view_messages: bool = True,
+            send_messages: bool = True,
+            send_media: bool = True,
+            send_stickers: bool = True,
+            send_gifs: bool = True,
+            send_inline: bool = True,
+            send_polls: bool = True,
+            embed_links: bool = True
+    ):
+        """
+        Bans a user from a chat (group, supergroup or channel).
+
+        This is a convenience wrapper around `edit_permissions`.
+
+        Arguments
+            chat (`entity`):
+                The chat where the user should be banned.
+
+            user (`entity`):
+                The user to ban.
+
+            until_date (`DateLike`, optional):
+                When the ban will be lifted. If not specified, the ban is permanent.
+
+            view_messages (`bool`, optional):
+                Whether to also prevent the user from viewing messages. Defaults to True.
+
+            send_messages (`bool`, optional):
+                Whether to prevent the user from sending messages. Defaults to True.
+
+            send_media (`bool`, optional):
+                Whether to prevent the user from sending media. Defaults to True.
+
+            send_stickers (`bool`, optional):
+                Whether to prevent the user from sending stickers. Defaults to True.
+
+            send_gifs (`bool`, optional):
+                Whether to prevent the user from sending GIFs. Defaults to True.
+
+            send_inline (`bool`, optional):
+                Whether to prevent the user from using inline bots. Defaults to True.
+
+            send_polls (`bool`, optional):
+                Whether to prevent the user from sending polls. Defaults to True.
+
+            embed_links (`bool`, optional):
+                Whether to prevent the user from embedding links. Defaults to True.
+
+        Example
+            .. code-block:: python
+
+                # Ban a user permanently
+                await client.ban_chat_member(chat, user)
+
+                # Ban for 1 hour
+                from datetime import timedelta
+                await client.ban_chat_member(chat, user, until_date=timedelta(hours=1))
+
+                # Ban but allow viewing messages
+                await client.ban_chat_member(chat, user, view_messages=False)
+        """
+        return await self.edit_permissions(
+            chat, user, until_date=until_date,
+            view_messages=view_messages,
+            send_messages=send_messages,
+            send_media=send_media,
+            send_stickers=send_stickers,
+            send_gifs=send_gifs,
+            send_inline=send_inline,
+            send_polls=send_polls,
+            embed_link_previews=embed_links
+        )
+
+    async def unban_chat_member(
+            self: 'SoroushClient',
+            chat: 'hints.EntityLike',
+            user: 'hints.EntityLike',
+            *,
+            view_messages: bool = True
+    ):
+        """
+        Unbans a previously banned user from a chat.
+
+        Arguments
+            chat (`entity`):
+                The chat where the user should be unbanned.
+
+            user (`entity`):
+                The user to unban.
+
+            view_messages (`bool`, optional):
+                Whether the user can view messages after unbanning. Defaults to True.
+
+        Example
+            .. code-block:: python
+
+                await client.unban_chat_member(chat, user)
+        """
+        return await self.edit_permissions(
+            chat, user,
+            view_messages=view_messages,
+            send_messages=True,
+            send_media=True,
+            send_stickers=True,
+            send_gifs=True,
+            send_inline=True,
+            send_polls=True,
+            embed_link_previews=True
+        )
+
+    async def kick_chat_member(
+            self: 'SoroushClient',
+            chat: 'hints.EntityLike',
+            user: 'hints.EntityLike'
+    ):
+        """
+        Kicks a user from a chat (ban + unban).
+
+        This is a convenience wrapper around `kick_participant`.
+
+        Arguments
+            chat (`entity`):
+                The chat where the user should be kicked from.
+
+            user (`entity`):
+                The user to kick.
+
+        Example
+            .. code-block:: python
+
+                await client.kick_chat_member(chat, user)
+        """
+        return await self.kick_participant(chat, user)
+
+    async def pin_message(
+            self: 'SoroushClient',
+            chat: 'hints.EntityLike',
+            message: 'typing.Union[int, types.Message]',
+            *,
+            notify: bool = False
+    ):
+        """
+        Pins a message in a chat.
+
+        Arguments
+            chat (`entity`):
+                The chat where the message should be pinned.
+
+            message (`int` | `Message`):
+                The message to pin (either the message ID or the message object).
+
+            notify (`bool`, optional):
+                Whether to notify all members about the pinned message. Defaults to False.
+
+        Example
+            .. code-block:: python
+
+                # Pin a message
+                await client.pin_message(chat, message)
+
+                # Pin and notify everyone
+                await client.pin_message(chat, message, notify=True)
+        """
+        entity = await self.get_input_entity(chat)
+        msg_id = utils.get_message_id(message)
+        return await self(functions.messages.UpdatePinnedMessageRequest(
+            peer=entity,
+            id=msg_id,
+            silent=not notify
+        ))
+
+    async def unpin_message(
+            self: 'SoroushClient',
+            chat: 'hints.EntityLike',
+            message: 'typing.Union[int, types.Message]'
+    ):
+        """
+        Unpins a specific message from a chat.
+
+        Arguments
+            chat (`entity`):
+                The chat from which to unpin the message.
+
+            message (`int` | `Message`):
+                The message to unpin.
+
+        Example
+            .. code-block:: python
+
+                await client.unpin_message(chat, message)
+        """
+        entity = await self.get_input_entity(chat)
+        msg_id = utils.get_message_id(message)
+        return await self(functions.messages.UpdatePinnedMessageRequest(
+            peer=entity,
+            id=msg_id,
+            unpin=True
+        ))
+
+    async def unpin_all_messages(
+            self: 'SoroushClient',
+            chat: 'hints.EntityLike'
+    ):
+        """
+        Unpins all pinned messages in a chat.
+
+        Arguments
+            chat (`entity`):
+                The chat from which to unpin all messages.
+
+        Example
+            .. code-block:: python
+
+                await client.unpin_all_messages(chat)
+        """
+        entity = await self.get_input_entity(chat)
+        ty = helpers._entity_type(entity)
+        if ty == helpers._EntityType.CHANNEL:
+            return await self(functions.channels.UpdatePinnedRequest(
+                channel=entity,
+                id=0  # 0 means unpin all
+            ))
+        else:
+            # For basic groups, unpin all by getting pinned messages and unpinning each
+            pinned = await self(functions.messages.GetPinnedMessagesRequest(
+                peer=entity
+            ))
+            if pinned.messages:
+                for msg in pinned.messages:
+                    await self(functions.messages.UpdatePinnedMessageRequest(
+                        peer=entity,
+                        id=msg.id,
+                        unpin=True
+                    ))
+            return None
+
+    # endregion