init-data-py 0.1.0__tar.gz → 0.2.0__tar.gz

init_data_py-0.2.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.3
+Name: init-data-py
+Version: 0.2.0
+Summary: A Python library that provides tools for using and validating Telegram web app init data.
+Author-email: nimaxin <nimaxin@proton.me>
+License-Expression: MIT
+License-File: LICENCE
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# init-data-py
+
+![Package version](https://img.shields.io/pypi/v/init-data-py?color=%2334D058&label=pypi%20package)
+![License](https://img.shields.io/github/license/nimaxin/init-data-py)
+
+A Python library that provides tools for using and validating Telegram web app init data.
+
+## Installation
+
+You can install the library using pip:
+
+```bash
+pip install init-data-py
+```
+
+## Usage
+
+### Parsing
+
+To parse the `window.Telegram.WebApp.initData` query string into an `InitData` object for easier access to attributes and validation, you can use the `InitData.parse` method:
+
+```python
+from init_data_py import InitData
+
+init_data = InitData.parse(query_string)
+```
+
+### Validation
+
+To validate the init data, you can use the `InitData.validate` method:
+
+```python
+is_valid = init_data.validate(bot_token)
+```
+
+### Signing
+
+If you need to create and sign your own init data, you can create an `InitData` object and sign it:
+
+```python
+from init_data_py import InitData
+from init_data_py.types import User
+
+user = User(id=5167898484, first_name="xin")
+init_data = InitData(user=user).sign(bot_token)
+```
+
+### Converting InitData to Query String
+
+After creating and signing init data, you can convert it to a query sting using the `InitData.to_query_string` method:
+
+```python
+query_string = init_date.to_query_string()
+```
+
+### Real-World Validation Example
+
+This example demonstrates how to validate a Telegram Mini App init data. It parses the init data query string into an `InitData` object and validate it using the provided bot token, checking that the data is valid and has not expired:
+
+```python
+from init_data_py import InitData
+
+bot_token = "7244657541:AAEgqk0HDC3WD5cdbnGMdd6L0TJ74FDp97Y"
+query_string = "query_id=AAF03wc0AgAAAHTfBzROOCVW&user=%7B%22id%22%3A5167898484%2C%22first_name%22%3A%22xin%22%2C%22last_name%22%3A%22%22%2C%22username%22%3A%22pvnimaxin%22%2C%22language_code%22%3A%22en%22%2C%22allows_write_to_pm%22%3Atrue%7D&auth_date=1722938610&hash=8654c8c617c143abf656f4f159be2539880a56f58c2d9be622f90c0346aa162b"
+
+init_data = InitData.parse(query_string)
+
+is_valid = init_data.validate(
+    bot_token=bot_token,
+    lifetime=3600,
+)
+```
+
+## License
+
+This library is licensed under the [MIT License](LICENCE).

init_data_py-0.2.0/README.md

@@ -0,0 +1,76 @@
+# init-data-py
+
+![Package version](https://img.shields.io/pypi/v/init-data-py?color=%2334D058&label=pypi%20package)
+![License](https://img.shields.io/github/license/nimaxin/init-data-py)
+
+A Python library that provides tools for using and validating Telegram web app init data.
+
+## Installation
+
+You can install the library using pip:
+
+```bash
+pip install init-data-py
+```
+
+## Usage
+
+### Parsing
+
+To parse the `window.Telegram.WebApp.initData` query string into an `InitData` object for easier access to attributes and validation, you can use the `InitData.parse` method:
+
+```python
+from init_data_py import InitData
+
+init_data = InitData.parse(query_string)
+```
+
+### Validation
+
+To validate the init data, you can use the `InitData.validate` method:
+
+```python
+is_valid = init_data.validate(bot_token)
+```
+
+### Signing
+
+If you need to create and sign your own init data, you can create an `InitData` object and sign it:
+
+```python
+from init_data_py import InitData
+from init_data_py.types import User
+
+user = User(id=5167898484, first_name="xin")
+init_data = InitData(user=user).sign(bot_token)
+```
+
+### Converting InitData to Query String
+
+After creating and signing init data, you can convert it to a query sting using the `InitData.to_query_string` method:
+
+```python
+query_string = init_date.to_query_string()
+```
+
+### Real-World Validation Example
+
+This example demonstrates how to validate a Telegram Mini App init data. It parses the init data query string into an `InitData` object and validate it using the provided bot token, checking that the data is valid and has not expired:
+
+```python
+from init_data_py import InitData
+
+bot_token = "7244657541:AAEgqk0HDC3WD5cdbnGMdd6L0TJ74FDp97Y"
+query_string = "query_id=AAF03wc0AgAAAHTfBzROOCVW&user=%7B%22id%22%3A5167898484%2C%22first_name%22%3A%22xin%22%2C%22last_name%22%3A%22%22%2C%22username%22%3A%22pvnimaxin%22%2C%22language_code%22%3A%22en%22%2C%22allows_write_to_pm%22%3Atrue%7D&auth_date=1722938610&hash=8654c8c617c143abf656f4f159be2539880a56f58c2d9be622f90c0346aa162b"
+
+init_data = InitData.parse(query_string)
+
+is_valid = init_data.validate(
+    bot_token=bot_token,
+    lifetime=3600,
+)
+```
+
+## License
+
+This library is licensed under the [MIT License](LICENCE).

{init_data_py-0.1.0 → init_data_py-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "init-data-py"
-version = "0.1.0"
+version = "0.2.0"
 description = "A Python library that provides tools for using and validating Telegram web app init data."
 authors = [
     { name = "nimaxin", email = "nimaxin@proton.me" }

{init_data_py-0.1.0 → init_data_py-0.2.0}/src/init_data_py/__init__.py

@@ -1,5 +1,5 @@
 from .init_data import InitData
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = ["InitData"]

{init_data_py-0.1.0 → init_data_py-0.2.0}/src/init_data_py/init_data.py

@@ -3,6 +3,7 @@ import hmac
 import json
 import time
 import urllib.parse
+import warnings
 from datetime import datetime, timedelta
 from typing import Literal, Optional
 
@@ -71,7 +72,12 @@ class InitData:
         self.auth_date = auth_date
         self.hash = hash
 
-    def validate(self, bot_token: str, lifetime: Optional[int] = None):
+    def validate(
+        self,
+        bot_token: str,
+        lifetime: Optional[int] = None,
+        raise_error: bool = True,
+    ):
         """Validates the init data authenticity.
 
         Parameters:
@@ -82,9 +88,12 @@ class InitData:
                 The maximum validity period of the init data in seconds.
                 Recommended for security. Default is `None`.
 
+            raise_error (`bool`, optional):
+                In case True, raises an exception on invalid data, If False, returns False instead of raising an error.
+
         Returns:
             `bool`:
-                `True` if the init data is valid; otherwise, raises an exception.
+                True if the data is valid; otherwise, returns False.
 
         Raises:
             `errors.SignMissingError`: In case the signature (hash) is missing.
@@ -93,19 +102,27 @@ class InitData:
             `errors.SignInvalidError`: In case the signature (hash) is invalid.
         """
         if self.hash is None:
-            raise errors.SignMissingError()
+            if raise_error:
+                raise errors.SignMissingError()
+            return False
 
         if self.auth_date is None:
-            raise errors.AuthDateMissingError()
+            if raise_error:
+                raise errors.AuthDateMissingError()
+            return False
 
         if lifetime is not None:
             auth_date = datetime.fromtimestamp(self.auth_date)
             expire_date = auth_date - timedelta(seconds=lifetime)
             if datetime.now() > expire_date:
-                raise errors.ExpiredError()
+                if raise_error:
+                    raise errors.ExpiredError()
+                return False
 
         if self.hash != self.calculate_hash(bot_token):
-            raise errors.SignInvalidError()
+            if raise_error:
+                raise errors.SignInvalidError()
+            return False
 
         return True
 
@@ -120,14 +137,16 @@ class InitData:
                 The timestamp (without timezone) representing the authorization date. If not provided, the current timestamp will be used.
 
         Returns:
-            `None`:
-                This method updates the current init data by setting the `auth_date` and generated signature (`hash`) attributes.
+            `InitData`:
+                This current updated init data by setting the `auth_date` and generated signature (`hash`) attributes.
         """
         if auth_date is None:
             self.auth_date = int(time.time())
         self.auth_date = auth_date
         self.hash = self.calculate_hash(bot_token)
 
+        return self
+
     def calculate_hash(
         self,
         bot_token: str,
@@ -151,17 +170,32 @@ class InitData:
         secret_key = hmac.new(
             b"WebAppData", bot_token.encode(), hashlib.sha256
         ).digest()
+
         return hmac.new(
             secret_key, data_check_string, hashlib.sha256
         ).hexdigest()
 
     @classmethod
     def from_query_string(cls, query_string: str):
+        warnings.warn(
+            "The 'from_query_string' method is deprecated and will be removed in near stable version. Use 'parse' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        return cls.parse(query_string)
+
+    @classmethod
+    def parse(cls, query_string: str):
         """Create an InitData object from a query string.
 
         Parameters:
             query_string (`str`):
-                The query string from `window.WebApp.initData` to parse and covert into an WebAppInitData object.
+                The query string from `window.WebApp.initData` to parse and convert into an InitData object.
+
+        Returns:
+            `InitData`:
+                An object of InitData with attributes set according to the values in the query_string.
 
         Raises:
             `errors.SignMissingError`: In case the signature (hash) is missing.
@@ -242,6 +276,7 @@ class InitData:
     def to_query_string(self):
         """Returns a query string representation of the object."""
         init_data = self.to_dict(nested=False)
+
         return urllib.parse.urlencode(init_data)
 
     def __str__(self) -> str:

{init_data_py-0.1.0 → init_data_py-0.2.0}/tests/test_parse.py

@@ -21,9 +21,9 @@ class TestParseInitData(unittest.TestCase):
         )
 
     def test_valid_query_string(self):
-        init_data = InitData.from_query_string(self.query_string)
+        init_data = InitData.parse(self.query_string)
         self.assertEqual(init_data, self.expected_init_data)
 
     def test_invalid_query_string(self):
         with self.assertRaises(errors.UnexpectedFormatError):
-            InitData.from_query_string(self.query_string.upper())
+            InitData.parse(self.query_string.upper())

{init_data_py-0.1.0 → init_data_py-0.2.0}/tests/test_sign.py

@@ -24,9 +24,10 @@ class TestSignInitData(unittest.TestCase):
         )
 
     def test_sign(self):
-        self.init_data.sign(
+        init_data = self.init_data.sign(
             bot_token=self.bot_token,
             auth_date=self.expected_auth_date,
         )
         self.assertEqual(self.init_data.hash, self.expected_hash)
         self.assertEqual(self.init_data.auth_date, self.expected_auth_date)
+        self.assertIsInstance(init_data, InitData)

init_data_py-0.2.0/tests/test_to_query_string.py

@@ -0,0 +1,11 @@
+import unittest
+
+from init_data_py import InitData
+
+
+class TestToQueryString(unittest.TestCase):
+    def test_from_query_string_to_query_string(self):
+        query_string = "query_id=AAF03wc0AgAAAHTfBzROOCVW&user=%7B%22id%22%3A5167898484%2C%22first_name%22%3A%22xin%22%2C%22last_name%22%3A%22%22%2C%22username%22%3A%22pvnimaxin%22%2C%22language_code%22%3A%22en%22%2C%22allows_write_to_pm%22%3Atrue%7D&auth_date=1722938610&hash=8654c8c617c143abf656f4f159be2539880a56f58c2d9be622f90c0346aa162b"
+        init_data = InitData.parse(query_string)
+        generated_query_string = init_data.to_query_string()
+        self.assertEqual(generated_query_string, query_string)

init_data_py-0.1.0/PKG-INFO

@@ -1,65 +0,0 @@
-Metadata-Version: 2.3
-Name: init-data-py
-Version: 0.1.0
-Summary: A Python library that provides tools for using and validating Telegram web app init data.
-Author-email: nimaxin <nimaxin@proton.me>
-License-Expression: MIT
-License-File: LICENCE
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-
-# init-data-py
-
-A Python library that provides tools for using and validating Telegram web app init data.
-
-## Installation
-
-You can install the library using pip.
-
-```bash
-pip install init-data-py
-```
-
-## Usage
-
-### Parsing.
-
-```python
-from init_data_py import InitData
-
-query_string = "query_id=AAF03wc0Ag..."
-
-InitData.from_query_string(query_string)
-```
-
-### Signing
-
-```python
-from init_data_py import InitData
-from init_data_py.types import User
-
-BOT_TOKEN = "7244657541:AA..."
-
-init_data = InitData(
-    user=User(
-        id=5167898484,
-        first_name="xin",
-        username="pvnimaxin",
-    )
-).sign(bot_token=BOT_TOKEN)
-```
-
-### Validation
-
-```python
-from init_data_py import InitData
-
-BOT_TOKEN = "7244657541:AA..."
-
-init_data = InitData(...)
-is_valid = init_data.validate(bot_token=BOT_TOKEN, lifetime=3600)
-```
-
-## License
-
-This library is licensed under the [MIT License](LICENCE).

init_data_py-0.1.0/README.md

@@ -1,55 +0,0 @@
-# init-data-py
-
-A Python library that provides tools for using and validating Telegram web app init data.
-
-## Installation
-
-You can install the library using pip.
-
-```bash
-pip install init-data-py
-```
-
-## Usage
-
-### Parsing.
-
-```python
-from init_data_py import InitData
-
-query_string = "query_id=AAF03wc0Ag..."
-
-InitData.from_query_string(query_string)
-```
-
-### Signing
-
-```python
-from init_data_py import InitData
-from init_data_py.types import User
-
-BOT_TOKEN = "7244657541:AA..."
-
-init_data = InitData(
-    user=User(
-        id=5167898484,
-        first_name="xin",
-        username="pvnimaxin",
-    )
-).sign(bot_token=BOT_TOKEN)
-```
-
-### Validation
-
-```python
-from init_data_py import InitData
-
-BOT_TOKEN = "7244657541:AA..."
-
-init_data = InitData(...)
-is_valid = init_data.validate(bot_token=BOT_TOKEN, lifetime=3600)
-```
-
-## License
-
-This library is licensed under the [MIT License](LICENCE).