magic-admin 2.1.2__py3-none-any.whl

magic_admin/__init__.py

@@ -0,0 +1,8 @@
+from magic_admin.magic import Magic  # noqa: F401
+
+
+# Magic API secret key.
+api_secret_key = None
+
+# A grace period time in second applied to the nbf field for token validation.
+did_token_nbf_grace_period_s = 300

magic_admin/config.py

@@ -0,0 +1,9 @@
+base_url = "https://api.toaster.magic.link"
+
+api_secret_api_key_missing_message = (
+    "API secret key is missing. Please specify "
+    "an API secret key when you instantiate the `Magic(api_secret_key=<KEY>)` "
+    "object or use the environment variable, `MAGIC_API_SECRET_KEY`. You can "
+    "get your API secret key from https://dashboard.magic.link. If you are having "
+    "trouble, please don't hesitate to reach out to us at support@magic.link"
+)

magic_admin/error.py

@@ -0,0 +1,100 @@
+class MagicError(Exception):
+    def __init__(self, message=None):
+        super().__init__(message)
+        self._message = message
+
+    def __str__(self):
+        return self._message or "<empty message>"
+
+    def __repr__(self):
+        return "{error_class}(message={message!r})".format(
+            error_class=self.__class__.__name__,
+            message=self._message,
+        )
+
+    def to_dict(self):
+        return {"message": str(self)}
+
+
+class DIDTokenInvalid(MagicError):
+    pass
+
+
+class DIDTokenMalformed(MagicError):
+    pass
+
+
+class DIDTokenExpired(MagicError):
+    pass
+
+
+class ExpectedBearerStringError(MagicError):
+    pass
+
+
+class APIConnectionError(MagicError):
+    pass
+
+
+class RequestError(MagicError):
+    def __init__(
+        self,
+        message=None,
+        http_status=None,
+        http_code=None,
+        http_resp_data=None,
+        http_message=None,
+        http_error_code=None,
+        http_request_params=None,
+        http_request_data=None,
+        http_method=None,
+    ):
+        super().__init__(message)
+        self.http_status = http_status
+        self.http_code = http_code
+        self.http_resp_data = http_resp_data
+        self.http_message = http_message
+        self.http_error_code = http_error_code
+        self.http_request_params = http_request_params
+        self.http_request_data = http_request_data
+        self.http_method = http_method
+
+    def __repr__(self):
+        return (
+            "{error_class}(message={message!r}, "
+            "http_error_code={http_error_code}, "
+            "http_code={http_code}).".format(
+                error_class=self.__class__.__name__,
+                message=self._message or None,
+                http_error_code=self.http_error_code or None,
+                http_code=self.http_code or None,
+            )
+        )
+
+    def to_dict(self):
+        _dict = super().to_dict()
+        for attr in self.__dict__:
+            if attr.startswith("http_"):
+                _dict[attr] = self.__dict__[attr]
+
+        return _dict
+
+
+class RateLimitingError(RequestError):
+    pass
+
+
+class BadRequestError(RequestError):
+    pass
+
+
+class AuthenticationError(RequestError):
+    pass
+
+
+class ForbiddenError(RequestError):
+    pass
+
+
+class APIError(RequestError):
+    pass

magic_admin/http_client.py

@@ -0,0 +1,140 @@
+import json
+import platform
+
+from requests import Session
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.util.retry import Retry
+
+import magic_admin
+from magic_admin import version
+from magic_admin.config import api_secret_api_key_missing_message
+from magic_admin.config import base_url
+from magic_admin.error import APIConnectionError
+from magic_admin.error import APIError
+from magic_admin.error import AuthenticationError
+from magic_admin.error import BadRequestError
+from magic_admin.error import ForbiddenError
+from magic_admin.error import RateLimitingError
+from magic_admin.response import MagicResponse
+
+
+class RequestsClient:
+    def __init__(self, retries, timeout, backoff_factor):
+        self._retries = retries
+        self._timeout = timeout
+        self._backoff_factor = backoff_factor
+
+        self._setup_request_session()
+
+    @staticmethod
+    def _get_platform_info():
+        platform_info = {}
+
+        for attr, func in [
+            ["platform", platform.platform],
+            ["language_version", platform.python_version],
+            ["uname", platform.uname],
+        ]:
+            try:
+                val = str(func())
+            except Exception as e:
+                val = "<{}>".format(str(e))
+
+            platform_info[attr] = val
+
+        return platform_info
+
+    def _setup_request_session(self):
+        """Take advantage of the ``requests.Session``. If client is making several
+        requests to the same host, the underlying TCP connection will be reused,
+        which can result in a significant performance increase.
+        """
+        self.http = Session()
+        self.http.mount(
+            base_url,
+            HTTPAdapter(
+                max_retries=Retry(
+                    total=self._retries,
+                    backoff_factor=self._backoff_factor,
+                ),
+            ),
+        )
+
+    def _get_request_headers(self):
+        user_agent = {
+            "language": "python",
+            "sdk_version": version.VERSION,
+            "publisher": "magic",
+            "http_lib": self.__class__.__name__,
+            **self._get_platform_info(),
+        }
+
+        if magic_admin.api_secret_key is None:
+            raise AuthenticationError(api_secret_api_key_missing_message)
+
+        return {
+            "X-Magic-Secret-Key": magic_admin.api_secret_key,
+            "User-Agent": json.dumps(user_agent),
+        }
+
+    def request(self, method, url, params=None, data=None):
+        try:
+            api_resp = self.http.request(
+                method,
+                url,
+                params=params,
+                # Requests auto-converts this to JSON and add content-type
+                # `application/json`.
+                json=data,
+                headers=self._get_request_headers(),
+                timeout=self._timeout,
+            )
+        except Exception as e:
+            return self._handle_request_error(e)
+
+        return self._parse_and_convert_to_api_response(
+            api_resp,
+            params,
+            data,
+        )
+
+    def _parse_and_convert_to_api_response(self, resp, request_params, request_data):
+        status_code = resp.status_code
+
+        if 200 <= status_code < 300:
+            return MagicResponse(resp.content, resp.json(), status_code)
+
+        if status_code == 429:
+            error_class = RateLimitingError
+        elif status_code == 400:
+            error_class = BadRequestError
+        elif status_code == 401:
+            error_class = AuthenticationError
+        elif status_code == 403:
+            error_class = ForbiddenError
+        else:
+            error_class = APIError
+
+        resp_data = resp.json()
+        raise error_class(
+            http_status=resp_data.get("status"),
+            http_code=status_code,
+            http_resp_data=resp_data.get("data"),
+            http_message=resp_data.get("message"),
+            http_error_code=resp_data.get("error_code"),
+            http_request_params=request_params,
+            http_request_data=request_data,
+            http_method=resp.request.method,
+        )
+
+    def _handle_request_error(self, e):
+        message = (
+            "Unexpected error thrown while communicating to Magic. "
+            "Please reach out to support@magic.link if the problem continues. "
+            "Error message: {error_class} was raised - {error_message}".format(
+                error_class=e.__class__.__name__,
+                error_message=str(e) or "no error message.",
+            )
+        )
+
+        raise APIConnectionError(message)

magic_admin/magic.py

@@ -0,0 +1,53 @@
+import os
+
+import magic_admin
+from magic_admin.config import api_secret_api_key_missing_message
+from magic_admin.config import base_url
+from magic_admin.error import AuthenticationError
+from magic_admin.http_client import RequestsClient
+from magic_admin.resources.base import ResourceComponent
+
+
+RETRIES = 3
+TIMEOUT = 10
+BACKOFF_FACTOR = 0.02
+
+
+class Magic:
+    v1_client_info = base_url + "/v1/admin/client"
+
+    def __getattr__(self, attribute_name):
+        try:
+            return getattr(self._resource, attribute_name)
+        except AttributeError:
+            pass
+
+        return super().__getattribute__(attribute_name)
+
+    def __init__(
+        self,
+        api_secret_key=None,
+        client_id=None,
+        retries=RETRIES,
+        timeout=TIMEOUT,
+        backoff_factor=BACKOFF_FACTOR,
+    ):
+        self._resource = ResourceComponent()
+
+        self._resource.setup_request_client(retries, timeout, backoff_factor)
+        self._set_api_secret_key(api_secret_key)
+        init_requests_client = RequestsClient(retries, timeout, backoff_factor)
+        magic_admin.client_id = (
+            client_id
+            or init_requests_client.request("get", self.v1_client_info).data[
+                "client_id"
+            ]
+        )
+
+    def _set_api_secret_key(self, api_secret_key):
+        magic_admin.api_secret_key = api_secret_key or os.environ.get(
+            "MAGIC_API_SECRET_KEY",
+        )
+
+        if magic_admin.api_secret_key is None:
+            raise AuthenticationError(api_secret_api_key_missing_message)

magic_admin/response.py

@@ -0,0 +1,5 @@
+class MagicResponse:
+    def __init__(self, content, resp_data, status_code):
+        self.content = content
+        self.status_code = status_code
+        self.data = resp_data

magic_admin/version.py

@@ -0,0 +1 @@
+VERSION = "2.1.2"

magic_admin-2.1.2.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: magic-admin
+Version: 2.1.2
+Summary: Magic Python Library
+Author-email: Magic <support@magic.link>
+License: MIT
+Project-URL: Website, https://magic.link
+Keywords: magic,python,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests==2.32.5
+Requires-Dist: web3==7.13.0
+Requires-Dist: websockets==15.0.1
+
+# Magic Admin Python SDK
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://badge.fury.io/py/magic-admin.svg)](https://badge.fury.io/py/magic-admin)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
+
+The Magic Admin Python SDK provides a simple and powerful way to integrate Magic's authentication system into your Python applications. Handle [DID Tokens](https://docs.magic.link/embedded-wallets/authentication/features/decentralized-id#decentralized-id-did-tokens) and interact with Magic API endpoints with ease.
+
+## 📚 Documentation
+
+📖 **Full Documentation**: [Magic Python SDK Docs](https://docs.magic.link/embedded-wallets/sdk/server-side/python)
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Using pip
+pip install magic-admin
+
+# Using conda
+conda install magic-admin
+```
+
+### Basic Usage
+
+```python
+from magic_admin import Magic
+
+# Initialize with your API secret key
+magic = Magic(api_secret_key='your_api_secret_key_here')
+
+# Validate a DID token
+try:
+    magic.Token.validate('DID_TOKEN_FROM_CLIENT')
+    print("Token is valid!")
+except Exception as e:
+    print(f"Token validation failed: {e}")
+```
+
+### Environment Variable Configuration
+
+You can also load your API secret key from an environment variable:
+
+```bash
+export MAGIC_API_SECRET_KEY="your_api_secret_key_here"
+```
+
+```python
+from magic_admin import Magic
+
+# Automatically uses MAGIC_API_SECRET_KEY environment variable
+magic = Magic()
+```
+
+> **Note**: The API secret key passed directly to `Magic()` takes precedence over the environment variable.
+
+### Network Configuration
+
+Customize network behavior for your application:
+
+```python
+magic = Magic(
+    api_secret_key='your_key',
+    retries=5,           # Number of retry attempts
+    timeout=10,          # Request timeout in seconds
+    backoff_factor=0.03  # Exponential backoff factor
+)
+```
+
+## 🔧 Development
+
+### Prerequisites
+
+- Python 3.11+
+- Git
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/magiclabs/magic-admin-python.git
+cd magic-admin-python
+
+# Create virtual environment and install dependencies
+make development
+
+# Activate the virtual environment
+source virtualenv_run/bin/activate
+```
+
+### Running Tests
+
+```bash
+# Run tests against all supported Python versions (3.11, 3.12, 3.13)
+make test
+
+# Run tests with coverage
+make test
+```
+
+### Code Quality
+
+This project uses [pre-commit](https://pre-commit.com/) to maintain code quality. Hooks run automatically on every commit.
+
+```bash
+# Run pre-commit hooks manually
+pre-commit run --all-files
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### Cleanup
+
+```bash
+# Remove virtual environment, tox logs, and pytest cache
+make clean
+```
+
+## 📋 Requirements
+
+- **Python**: 3.11+
+- **Dependencies**: See [requirements.txt](requirements.txt)
+- **Development**: See [requirements-dev.txt](requirements-dev.txt)
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `make test`
+5. Run pre-commit: `pre-commit run --all-files`
+6. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
+
+## 🔗 Links
+
+- [Magic Documentation](https://docs.magic.link)
+- [Magic Dashboard](https://dashboard.magic.link)
+- [Magic Python SDK Docs](https://docs.magic.link/embedded-wallets/sdk/server-side/python)
+- [DID Token Documentation](https://docs.magic.link/embedded-wallets/authentication/features/decentralized-id#decentralized-id-did-tokens)

magic_admin-2.1.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+magic_admin/__init__.py,sha256=DuRZ7GbiA_ZmOZ-9eOjTMvRDC5JuVE-4F7ZG4IoGfG4,213
+magic_admin/config.py,sha256=n2HFDIxDTRRQTOYwLspb4lGUnObQTwK3gK5_kohWNDs,456
+magic_admin/error.py,sha256=73yr-TWgxGY5kvMMrtPJKzP566HI41MZ_hVd6OcrFO0,2270
+magic_admin/http_client.py,sha256=9Sg5rLhIZDfVo-xj9agkuqOOR_xQqHxLAAhg0fdlXJk,4570
+magic_admin/magic.py,sha256=-ydXF1ALw4l53bWVZPuZRw-LIL-9LEIyaitggdd2AHw,1542
+magic_admin/response.py,sha256=irjZDDLv79IzmIK_sohcZw-1UAbDZWsDjccKv0kujO8,178
+magic_admin/version.py,sha256=g3cxz98sq2sH94EJfsXt9vgetLlENXp3IEKtEY6wMyg,18
+magic_admin-2.1.2.dist-info/METADATA,sha256=e_IHIQzzeeQ6A-m1Vxg4fOdMcuU61Y03lx7CPo2V6m4,4433
+magic_admin-2.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+magic_admin-2.1.2.dist-info/top_level.txt,sha256=apXKs0D-XDoIjenh62w68eONw8qHW7s5FgRoA5vc2aw,12
+magic_admin-2.1.2.dist-info/RECORD,,

magic_admin-2.1.2.dist-info/WHEEL

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

magic_admin-2.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+magic_admin