Merge pull request #8 from nnnLik/feature/refactor-admitad-api

 - Add PromoOffersForCampaign support and modernize codebase
 - Add PromoOffersForCampaign class for campaign promo offers retrieval
 - Refactor Client and Exception classes to use dataclasses
 - Pin requests dependency to 2.32.5 for stability
 - Add comprehensive test coverage for new functionality
 - Improve type safety with enhanced type hints
 - Support custom API base URL via environment variable

Author: pehas

.gitignore

@@ -4,6 +4,7 @@
 *.so
 
 # Packages
+.eggs
 *.egg
 *.egg-info
 dist
@@ -33,7 +34,7 @@ nosetests.xml
 .mr.developer.cfg
 .project
 .pydevproject
-
+.venv
 .idea
 *.sublime*
 

admitad/api.py

@@ -1,26 +1,36 @@
-# coding: utf-8
-from __future__ import unicode_literals
-
 from admitad import client, transport
 
 
-def get_oauth_client_token(access_token, user_agent=None, debug=False):
-    """
-    Creates a client using an access token.
-
-    """
-    http_transport = transport.HttpTransport(access_token, user_agent=user_agent, debug=debug)
+def get_oauth_client_token(
+    access_token: str,
+    user_agent: str | None = None,
+    debug: bool = False,
+) -> client.Client:
+    """Creates a client using an access token."""
+    http_transport = transport.HttpTransport(
+        access_token,
+        user_agent=user_agent,
+        debug=debug,
+    )
     return client.Client(http_transport)
 
 
-def get_oauth_client_client(client_id, client_secret, scopes, user_agent=None, debug=False):
-    """
-    Creates a client using a client_id and client_secret.
-
-    """
+def get_oauth_client_client(
+    client_id: str,
+    client_secret: str,
+    scopes: str,
+    user_agent: str | None = None,
+    debug: bool = False,
+) -> client.Client:
+    """Creates a client using a client_id and client_secret."""
     auth = transport.oauth_client_authorization({
         'client_id': client_id,
         'client_secret': client_secret,
         'scopes': scopes
     })
-    return get_oauth_client_token(auth['access_token'], user_agent=user_agent, debug=debug)
+
+    return get_oauth_client_token(
+        auth['access_token'],
+        user_agent=user_agent,
+        debug=debug,
+    )

admitad/client.py

@@ -1,14 +1,11 @@
-# coding: utf-8
-from __future__ import unicode_literals
+from dataclasses import dataclass
 
-from admitad import items
+from admitad import items, transport
 
 
-class Client(object):
-    """The API client."""
+@dataclass
+class Client:
+    _transport: transport.HttpTransport
 
-    def __init__(self, transport):
-        self.transport = transport
-
-    def __getattr__(self, name):
-        return getattr(items, name)(self.transport)
+    def __getattr__(self, name: str) -> type[items.Item]:
+        return getattr(items, name)(self._transport)

admitad/constants.py

@@ -1,23 +1,21 @@
-# coding: utf-8
-from __future__ import unicode_literals
+import os
 
-# API date-format
-DATE_FORMAT = '%d.%m.%Y'
-LONG_DATE_FORMAT = '%d.%m.%Y %H:%M:%S'
+DATE_FORMAT: str = '%d.%m.%Y'
+LONG_DATE_FORMAT: str = '%d.%m.%Y %H:%M:%S'
 
-SUPPORTED_LANGUAGES = ('ru', 'en', 'de', 'pl', 'es', 'tr')
+SUPPORTED_LANGUAGES: tuple[str, ...] = ('ru', 'en', 'de', 'pl', 'es', 'tr')
 
-# default values
-DEFAULT_REQUEST_TIMEOUT = 60
-DEFAULT_LANGUAGE = 'ru'
-DEFAULT_PAGINATION_LIMIT = 20
-DEFAULT_PAGINATION_OFFSET = 0
+DEFAULT_REQUEST_TIMEOUT: int = 60
+DEFAULT_LANGUAGE: str = 'ru'
+DEFAULT_PAGINATION_LIMIT: int = 20
+DEFAULT_PAGINATION_OFFSET: int = 0
 
-# constants
-MAX_PAGINATION_LIMIT = 500
-MAX_SUB_ID_LENGTH = 250
+MAX_PAGINATION_LIMIT: int = 500
+MAX_SUB_ID_LENGTH: int = 250
 
-# urls
-BASE_URL = 'https://api.admitad.com/'
-AUTHORIZE_URL = '%s%s' % (BASE_URL, 'authorize/')
-TOKEN_URL = '%s%s' % (BASE_URL, 'token/')
+DEFAULT_PROD_URL: str = 'https://api.admitad.com/'
+CUSTOM_BASE_URL: str = os.getenv('ADMITAD_API_LIB_BASE_URL')
+
+BASE_URL: str = (CUSTOM_BASE_URL or DEFAULT_PROD_URL).rstrip('/') + '/'
+AUTHORIZE_URL: str = f'{BASE_URL}authorize/'
+TOKEN_URL: str = f'{BASE_URL}token/'

admitad/exceptions.py

@@ -1,62 +1,34 @@
-# coding: utf-8
-from __future__ import unicode_literals
+from dataclasses import dataclass
 
 
+@dataclass
 class HttpException(Exception):
+    status: int
+    message: str
+    content: str
 
-    def __init__(self, status, message, content):
-        super(HttpException, self).__init__()
-
-        self.status = status
-        self.message = message
-        self.content = content
-
-    def __str__(self):
-        return repr(self)
-
-    def __repr__(self):
-        return "HttpException(%s): %s%s" % (
-            self.status, self.content,
-            "\n%s" % self.message if self.message else "")
-
+    def __str__(self) -> str:
+        return f"HttpException({self.status}): {self.message}\n{self.content}"
 
+@dataclass
 class ConnectionException(Exception):
+    content: str
 
-    def __init__(self, content):
-        super(ConnectionException, self).__init__()
-
-        self.content = content
-
-    def __str__(self):
-        return repr(self)
-
-    def __repr__(self):
-        return "ConnectionException: %s" % self.content
+    def __str__(self) -> str:
+        return f"ConnectionException: {self.content}"
 
 
+@dataclass
 class JsonException(Exception):
+    content: str
 
-    def __init__(self, content):
-        super(JsonException, self).__init__()
-
-        self.content = content
-
-    def __str__(self):
-        return repr(self)
-
-    def __repr__(self):
-        return "JsonException: %s" % self.content
+    def __str__(self) -> str:
+        return f"JsonException: {self.content}"
 
 
+@dataclass
 class ApiException(Exception):
+    content: str
 
-    def __init__(self, content):
-        super(ApiException, self).__init__()
-
-        self.content = content
-
-    def __str__(self):
-        return repr(self)
-
-    def __repr__(self):
-        return "ApiException: %s" % self.content
+    def __str__(self) -> str:
+        return f"ApiException: {self.content}"

admitad/items/__init__.py

@@ -17,3 +17,4 @@
 from admitad.items.retag import *
 from admitad.items.broken_links import *
 from admitad.items.tickets import *
+from admitad.items.promo_offers import *

admitad/items/announcements.py

@@ -1,6 +1,3 @@
-# coding: utf-8
-from __future__ import unicode_literals
-
 from admitad.items.base import Item
 
 

admitad/items/auxiliary.py

@@ -1,6 +1,3 @@
-# coding: utf-8
-from __future__ import unicode_literals
-
 from admitad.items.base import Item
 
 

admitad/items/banners.py

@@ -1,6 +1,3 @@
-# coding: utf-8
-from __future__ import unicode_literals
-
 from admitad.items.base import Item
 
 

admitad/items/base.py

@@ -1,19 +1,13 @@
-# coding: utf-8
-from __future__ import unicode_literals
-
-from future import standard_library
-standard_library.install_aliases()
-
-from future.builtins import int, str
 from datetime import datetime, date
 from urllib.parse import urljoin
 
 from admitad.constants import BASE_URL, DATE_FORMAT, LONG_DATE_FORMAT
+from admitad.transport import HttpTransport
 
 
-class Item(object):
+class Item:
 
-    def __init__(self, transport):
+    def __init__(self, transport: HttpTransport):
         self.transport = transport
         self.transport.clean_data()