interpals-api 2.3.0__py3-none-any.whl

interpals_api/session.py

@@ -0,0 +1,243 @@
+"""
+Session instance keeps the necessary cookie parameters so API calls work
+correctly. Session can be created from raw cookie data or emulate the login
+process using username and password.
+"""
+
+import json
+from urllib.parse import urljoin
+from typing import Dict, TextIO, Self
+
+import requests
+import aiohttp
+
+from .utils import find_csrf_token
+from .errors import (NoCSRFTokenError, WrongUsernameOrPasswordError,
+                     SessionError, TooManyLoginAttemptsError)
+from .cookie import Cookie
+
+
+class Session:
+    """
+    Synchronous session class.
+    """
+
+    def __init__(self, username: str, interpals_sessid: str, 
+                 csrf_cookieV2: str):
+        """
+        Create a new session instance from the necessary cookie data:
+        `username`, `interpals_sessid`, `csrf_cookieV2`.
+        """
+        self.username = username
+        """
+        `username`
+        """
+
+        self.interpals_sessid = interpals_sessid
+        """
+        `interpals_sessid` cookie
+        """
+
+        self.csrf_cookieV2 = csrf_cookieV2
+        """
+        `csrf_cookieV2` cookie
+        """
+
+    def __repr__(self) -> str:
+        return f"Session(username={self.username}, " \
+               f"interpals_sessid={self.interpals_sessid}, " \
+               f"csrf_cookieV2={self.csrf_cookieV2})"
+
+    def cookie(self) -> Dict[str, str]:
+        """
+        Get cookie data as a dictionary.
+        """
+        return {
+            'interpals_sessid': self.interpals_sessid,
+            'csrf_cookieV2': self.csrf_cookieV2
+        }
+
+    def dump(self, f: TextIO):
+        """
+        Dump session data into a file-like object.
+        """
+        kwargs = {
+            'username': self.username,
+            'interpals_sessid': self.interpals_sessid,
+            'csrf_cookieV2': self.csrf_cookieV2,
+        }
+        json.dump(kwargs, f)
+
+    @classmethod
+    def load(cls, f: TextIO) -> Self:
+        """
+        Load session instance from a file-like object.
+        """
+        kwargs = json.load(f)
+        return cls(**kwargs)
+
+    @classmethod
+    def login(cls, username: str, password: str) -> Self:
+        """
+        Emulate the login process. It will return a session instance on success.
+        """
+        # Cookie object
+        cookie = Cookie()
+
+        # Request initial page
+        csrf_token = cls._request_initial_page(cookie)
+
+        # Request login endpoint
+        cls._request_login_endpoint(username, password, cookie, csrf_token)
+
+        # Create and return session instance
+        return cls(username=username,
+                   interpals_sessid=cookie['interpals_sessid'],
+                   csrf_cookieV2=cookie['csrf_cookieV2'])
+
+    @classmethod
+    def _request_initial_page(cls, cookie):
+        with requests.get("https://www.interpals.net/") as resp:
+            # Get initial cookie
+            set_cookie = Cookie.from_response_headers(resp.headers)
+            cookie.update(set_cookie)
+
+            # Extract CSRF token from the HTML
+            csrf_token = find_csrf_token(resp.text)
+
+            # Raise error if no token found
+            if csrf_token is None:
+                raise NoCSRFTokenError()
+
+        return csrf_token
+
+    @classmethod
+    def _request_login_endpoint(cls, username, password, cookie, csrf_token):
+        headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Cookie': cookie.as_string(),
+            'Referer': 'https://www.interpals.net/',
+        }
+        data = {
+            'username': username,
+            'password': password,
+            'csrf_token': csrf_token
+        }
+
+        # Request login entry point
+        with requests.post("https://www.interpals.net/app/auth/login",
+                           data=data, headers=headers, 
+                           allow_redirects=False) as resp:
+            # Update cookie
+            set_cookie = Cookie.from_response_headers(resp.headers)
+            cookie.update(set_cookie)
+
+            # Check status
+            if resp.status_code == 200:
+                raise WrongUsernameOrPasswordError()
+            elif resp.status_code == 302:
+                location = resp.headers['Location']
+            else:
+                raise SessionError(
+                    f"Unknown response status while login: {resp.status_code}"
+                )
+
+        # Request the location to check success
+        url = urljoin("https://www.interpals.net", location)
+        headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Cookie': cookie.as_string(),
+        }
+        with requests.get(url, headers=headers) as resp:
+            if "Too many unsuccessful login attempts." in resp.text:
+                raise TooManyLoginAttemptsError()
+
+
+class SessionAsync(Session):
+    """
+    Synchronous session class. It is inherited from [Session](#Session).
+    """
+
+    @classmethod
+    async def login(cls, username: str, password: str) -> Self:
+        """
+        Emulate the login process. It will return a session instance on success.
+        """
+        # Cookie object
+        cookie = Cookie()
+
+        # Request initial page
+        csrf_token = await cls._request_initial_page(cookie)
+
+        # Request login endpoint
+        await cls._request_login_endpoint(
+            username, password, cookie, csrf_token
+        )
+
+        # Create and return session instance
+        return cls(username=username,
+                   interpals_sessid=cookie['interpals_sessid'],
+                   csrf_cookieV2=cookie['csrf_cookieV2'])
+
+    @classmethod
+    async def _request_initial_page(cls, cookie):
+        async with aiohttp.ClientSession() as session:
+            async with session.get("https://www.interpals.net/") as resp:
+                # Get initial cookie
+                set_cookie = Cookie.from_response_headers(resp.headers)
+                cookie.update(set_cookie)
+
+                # Extract CSRF token from the HTML
+                text = await resp.text()
+                csrf_token = find_csrf_token(text)
+
+                # Raise error if no token found
+                if csrf_token is None:
+                    raise NoCSRFTokenError()
+
+        return csrf_token
+
+    @classmethod
+    async def _request_login_endpoint(cls, username, password, cookie, 
+                                      csrf_token):
+        headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Cookie': cookie.as_string(),
+            'Referer': 'https://www.interpals.net/',
+        }
+        data = {
+            'username': username,
+            'password': password,
+            'csrf_token': csrf_token
+        }
+
+        # Request login entry point
+        async with aiohttp.ClientSession() as session:
+            async with session.post("https://www.interpals.net/app/auth/login",
+                                    data=data, headers=headers, 
+                                    allow_redirects=False) as resp:
+                # Update cookie
+                set_cookie = Cookie.from_response_headers(resp.headers)
+                cookie.update(set_cookie)
+
+                # Check status
+                if resp.status == 200:
+                    raise WrongUsernameOrPasswordError()
+                elif resp.status == 302:
+                    location = resp.headers['Location']
+                else:
+                    raise SessionError(
+                        f"Unknown response status while login: {resp.status}"
+                    )
+
+        # Request the location to check success
+        url = urljoin("https://www.interpals.net", location)
+        headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Cookie': cookie.as_string(),
+        }
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, headers=headers) as resp:
+                text = await resp.text()
+                if "Too many unsuccessful login attempts." in text:
+                    raise TooManyLoginAttemptsError()

interpals_api/utils.py

@@ -0,0 +1,23 @@
+"""
+Useful functions.
+"""
+
+import re
+from typing import Optional
+
+
+re_csfr_token = re.compile(r'<meta name="csrf_token" content="(.*?)"')
+"""
+Regex for CSRF token meta tag, it selects its value.
+"""
+
+
+def find_csrf_token(html: str) -> Optional[str]:
+    """
+    Extract the content of CSRF token in the meta tag from HTML.
+    """
+    match = re_csfr_token.search(html)
+    if match is not None:
+        return match.group(1)
+    else:
+        return None

interpals_api-2.3.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: interpals-api
+Version: 2.3.0
+Summary: Unofficial Python API for Interpals.net.
+Home-page: https://github.com/fomalhaut88/interpals-api
+Author: Alexander Khlebushchev
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/interpals-api/
+Project-URL: Documentation, https://fomalhaut88.github.io/interpals-api/
+Project-URL: Source, https://github.com/fomalhaut88/interpals-api
+Project-URL: Issues, https://github.com/fomalhaut88/interpals-api/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.12
+Requires-Dist: requests>=2.32
+Requires-Dist: lxml>=6.0
+Requires-Dist: beautifulsoup4>=4.13
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# interpals-api
+
+This Python library provides a simple HTTP API for working with the website https://interpals.net/. It includes:
+
+* retrieving data by user identifier
+* listing visitors
+* searching for users by criterions
+* viewing and sending messages, deleting chats
+* listing, adding and removing friends
+* listing albums and pictures
+
+## Installation
+
+```
+pip install interpals-api
+```
+
+## Basic example
+
+```python
+from interpals_api import Session, Api
+
+session = Session.login('yourusername', 'yourpassword')
+api = Api(session)
+
+user_info = api.profile('someuser')
+print(user_info)
+```
+
+Since version `2.1` it supports asynchronous calls for each api method. Below there is a brief asynchonous example:
+
+```python
+from interpals_api import SessionAsync, ApiAsync
+
+session = await SessionAsync.login('yourusername', 'yourpassword')
+api = ApiAsync(session)
+
+user_info = await api.profile('someuser')
+print(user_info)
+```
+
+## Other examples
+
+Basic example to retrieve user info:
+
+```python
+from interpals_api import Session, Api
+
+session = Session.login('yourusername', 'yourpassword')
+api = Api(session)
+
+# This gives info of the user with the link: https://www.interpals.net/someuser
+user_info = api.profile('someuser')
+```
+
+Dump and load session object:
+
+```python
+from interpals_api import Session, Api
+
+session = Session.login('yourusername', 'yourpassword')
+
+# Save session into a file
+with open('session.json', 'w') as f:
+    session.dump(f)
+
+# Load session from the saved file
+with open('session.json') as f:
+    session = Session.load(f)
+```
+
+Viewing and searching for users:
+
+```python
+from interpals_api import Session, Api
+
+session = Session.login('yourusername', 'yourpassword')
+api = Api(session)
+
+# Viewing a certain user
+api.view('someuser')
+
+# Showing the visitors of your profile
+users = api.visitors()
+print(users)
+
+# Searching for users
+options = {
+    'age1': '20',
+    'age2': '40',
+    'sex': ['male', 'female'],
+    'continents': ['AF', 'AS', 'EU', 'NA', 'OC', 'SA'],
+    'countries': ['US', 'CA', 'UK', 'RU'],
+    'keywords': 'travelling',
+    'online': True,
+    'cityName': 'London'  # Or you can use 'city' with its direct code on the website (it's faster)
+}
+for user in api.search(options, limit=100, timeout=1.0):
+    print(user)
+```
+
+To work with friends and pictures, it is necessary to use `uid` in methods:
+
+```python
+from interpals_api import Session, Api
+
+session = Session.login('yourusername', 'yourpassword')
+api = Api(session)
+
+uid = api.get_uid('someuser')
+
+# Listing friends of the user 'someuser'
+friends = api.friends(uid)
+print(friends)
+
+# Adding 'someuser' to friends
+api.friend_add(uid)
+
+# Removing 'someuser' from friends
+api.friend_remove(uid)
+
+# Listing pictures
+albums = api.albums(uid)
+for album in albums:
+    aid = album['aid']
+    pictures = api.pictures(uid, aid)
+    for picture in pictures:
+        print(picture['src'])
+```
+
+Working with the chat is done through `thread_id`:
+
+```python
+from interpals_api import Session, Api
+
+session = Session.login('yourusername', 'yourpassword')
+api = Api(session)
+
+uid = api.get_uid('someuser')
+
+# Listing your chats
+result = api.chat(count=9, offset=0)
+print(result['chats'])
+
+# Staring new chat (getting thread_id)
+thread_id = api.get_thread_id(uid)
+
+# Show chat messages
+messages = api.chat_messages(thread_id)
+print(messages)
+
+# Send new message to the thread
+api.chat_send(thread_id, "Hey! How are you?")
+
+# Removing chat
+api.chat_delete(thread_id)
+```

interpals_api-2.3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+interpals_api/__init__.py,sha256=1kK2H0Y0z-ogmm5_kWV40PZjM03yaDi2SBfTd21zo64,3526
+interpals_api/api.py,sha256=KQ8RhMV1sQR_R7xlM5jr0ymgSUMItzRXfi9ZkCMHNRc,20286
+interpals_api/cookie.py,sha256=qmgZNzBYPEkaBlRvBwEA0LYNoWiyQGEYLfzYF4VmcCU,1410
+interpals_api/errors.py,sha256=8F8RwegyWM1ZY7w428PDxcCnyfkCSCUFHBKRNv20DVk,923
+interpals_api/session.py,sha256=Lp1yStrhMZaWYnMTH-gGIxnQZKyFKGeqUjOtIwzhQrw,8035
+interpals_api/utils.py,sha256=0pHsn4prOE_OuiEBJ8xyd18z35UBOYdULn2Cho6guos,456
+interpals_api/parsers/__init__.py,sha256=fUWisdZwAqbL9-YCL0fL1Z-Syhh8fsFSnkktPYpRJC0,46
+interpals_api/parsers/chat_parser.py,sha256=8tnef9ZfhyDqSB3YSwhuQuqA5nCAAjET75zLV7ACIYA,4298
+interpals_api/parsers/friends_parser.py,sha256=Sb_ZDma0ynF6BVdSvHT_YSRt8QsgzU9Z-MWW9osIP5E,1326
+interpals_api/parsers/pictures_parser.py,sha256=OhG_pkVJjzAgMHeIT_UF_bFjI4hRyG0EU9EZJqpxURw,2716
+interpals_api/parsers/profile_parser.py,sha256=ZrTgHPRmsx7Ws0VIn7jpBSwVZ-EDFfrK41g5YYd6uf0,3863
+interpals_api-2.3.0.dist-info/METADATA,sha256=IqTA0Uq9_fS_2OxVHzJlhL5-PET-7YKPcemo9w-O9TM,4902
+interpals_api-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+interpals_api-2.3.0.dist-info/top_level.txt,sha256=dXTmgNrsv3Y2J5bKnb3eWyjR8KnF4zRZqkomSAMP-Mo,14
+interpals_api-2.3.0.dist-info/RECORD,,

interpals_api-2.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

interpals_api-2.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+interpals_api