ipc-artsnoa 0.1.0__tar.gz

ipc_artsnoa-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+# ignore protect
+.*
+*.
+
+/test/manual.py

ipc_artsnoa-0.1.0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: ipc-artsnoa
+Version: 0.1.0
+Summary: Official Python SDK for ipc.artsnoa.com API - IP geolocation and information service
+Project-URL: Homepage, https://ipc.artsnoa.com
+Project-URL: Documentation, https://github.com/artsnoa/ipc-python-sdk
+Project-URL: Repository, https://github.com/artsnoa/ipc-python-sdk
+Project-URL: Issues, https://github.com/artsnoa/ipc-python-sdk/issues
+Author-email: artsnoa <support@artsnoa.com>
+Keywords: api,artsnoa,geolocation,ip,ipc,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/markdown
+
+# IPC Artsnoa Python SDK
+
+Official Python SDK for [ipc.artsnoa.com](https://ipc.artsnoa.com) API - Get your IP address and location information.
+
+## Features
+
+- Simple and intuitive API
+- Type hints for better IDE support
+- Comprehensive error handling
+- Context manager support
+- Minimal dependencies
+
+## Installation
+
+```bash
+pip install ipc-artsnoa
+```
+
+Or with uv:
+
+```bash
+uv add ipc-artsnoa
+```
+
+## Quick Start
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Initialize client (API key is optional)
+client = IPCClient(api_key='YOUR_API_KEY')
+
+# Get basic IP information
+data = client.get_ip()
+print(f'Your IP: {data["ip"]}, Country: {data["country"]}')
+
+# Get detailed IP information
+details = client.get_ip_details()
+print(f'IP: {details["ip"]}, ASN: {details["asn"]}, Currency: {details["currency"]}')
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Create client with API key
+client = IPCClient(api_key='YOUR_API_KEY')
+
+# Get basic IP information
+data = client.get_ip()
+print(f"IP: {data['ip']}")
+print(f"Country: {data['country']}")
+
+# Without API key
+client = IPCClient()
+data = client.get_ip()
+print(f"Your IP: {data['ip']}")
+```
+
+### Detailed IP Information
+
+```python
+from ipc_artsnoa import IPCClient
+
+client = IPCClient(api_key='YOUR_API_KEY')
+
+# Get detailed information including ASN, currency, languages
+details = client.get_ip_details()
+print(f"IP: {details['ip']}")
+print(f"User Agent: {details['userAgent']}")
+print(f"ASN: {details['asn']}")
+print(f"Country: {details['country']}")
+print(f"Currency: {details['currency']}")
+print(f"Languages: {details['languages']}")
+print(f"Timestamp: {details['timestamp']}")
+```
+
+### SDK Version Information
+
+```python
+from ipc_artsnoa import IPCClient
+
+client = IPCClient()
+
+# Get available SDK versions
+versions = client.get_sdk_versions()
+print(f"Python SDK: {versions['python']}")
+print(f"JavaScript SDK: {versions['javascript']}")
+```
+
+### Custom Configuration
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Custom timeout
+client = IPCClient(
+    api_key='YOUR_API_KEY',
+    timeout=15.0
+)
+
+data = client.get_ip()
+```
+
+### Using Context Manager
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Automatically closes session when done
+with IPCClient(api_key='YOUR_API_KEY') as client:
+    data = client.get_ip()
+    print(f"IP: {data['ip']}")
+```
+
+## Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+```python
+from ipc_artsnoa import (
+    IPCClient,
+    IPCError,
+    IPCAPIError,
+    IPCConnectionError,
+    IPCTimeoutError
+)
+
+client = IPCClient(api_key='YOUR_API_KEY')
+
+try:
+    data = client.get_ip()
+    print(f"Your IP: {data['ip']}")
+except IPCAPIError as e:
+    print(f"API error: {e}")
+    if hasattr(e, 'status_code'):
+        print(f"Status code: {e.status_code}")
+except IPCConnectionError as e:
+    print(f"Connection error: {e}")
+except IPCTimeoutError as e:
+    print(f"Request timeout: {e}")
+except IPCError as e:
+    print(f"IPC error: {e}")
+```
+
+## API Reference
+
+### IPCClient
+
+#### Constructor
+
+```python
+IPCClient(
+    api_key: str | None = None,
+    timeout: float = 10.0
+)
+```
+
+**Parameters:**
+- `api_key` (str | None): API key for authentication. Optional.
+- `timeout` (float): Request timeout in seconds. Defaults to 10.0
+
+#### Methods
+
+##### `get_ip() -> dict`
+
+Get basic IP address and location information.
+
+**Returns:**
+- Dictionary containing basic IP information including:
+  - `ip`: Your IP address
+  - `country`: Country code
+
+**Raises:**
+- `IPCAPIError`: When API returns an error response
+- `IPCConnectionError`: When connection fails
+- `IPCTimeoutError`: When request times out
+
+**Example:**
+```python
+data = client.get_ip()
+print(f"IP: {data['ip']}, Country: {data['country']}")
+```
+
+##### `get_ip_details() -> dict`
+
+Get detailed IP address information.
+
+**Returns:**
+- Dictionary containing detailed IP information including:
+  - `ip`: Your IP address
+  - `userAgent`: Browser user agent string
+  - `asn`: Autonomous System Number
+  - `country`: Country code
+  - `currency`: Country currency code
+  - `languages`: Supported languages
+  - `timestamp`: Request timestamp
+  - `version`: API version
+
+**Raises:**
+- `IPCAPIError`: When API returns an error response
+- `IPCConnectionError`: When connection fails
+- `IPCTimeoutError`: When request times out
+
+**Example:**
+```python
+details = client.get_ip_details()
+print(f"IP: {details['ip']}, ASN: {details['asn']}")
+```
+
+##### `get_sdk_versions() -> dict`
+
+Get available SDK versions.
+
+**Returns:**
+- Dictionary containing SDK versions for different platforms:
+  - `python`: Python SDK version
+  - `javascript`: JavaScript SDK version
+
+**Raises:**
+- `IPCAPIError`: When API returns an error response
+- `IPCConnectionError`: When connection fails
+- `IPCTimeoutError`: When request times out
+
+**Example:**
+```python
+versions = client.get_sdk_versions()
+print(f"Python SDK: {versions['python']}")
+```
+
+##### `close()`
+
+Close the underlying HTTP session.
+
+**Example:**
+```python
+client.close()
+```
+
+#### Context Manager Support
+
+The client supports context manager protocol for automatic resource cleanup:
+
+```python
+with IPCClient(api_key='YOUR_API_KEY') as client:
+    data = client.get_ip()
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/artsnoa/ipc-python-sdk.git
+cd ipc-python-sdk
+
+# Install dependencies with uv
+uv sync
+
+# Build package
+uv build
+```
+
+## Requirements
+
+- Python 3.10 or higher
+- requests >= 2.31.0
+
+## License
+
+MIT License
+
+## Support
+
+- Documentation: [https://github.com/artsnoa/ipc-python-sdk](https://github.com/artsnoa/ipc-python-sdk)
+- Issues: [https://github.com/artsnoa/ipc-python-sdk/issues](https://github.com/artsnoa/ipc-python-sdk/issues)
+- Email: aurora@artsnoa.com

ipc_artsnoa-0.1.0/README.md

@@ -0,0 +1,279 @@
+# IPC Artsnoa Python SDK
+
+Official Python SDK for [ipc.artsnoa.com](https://ipc.artsnoa.com) API - Get your IP address and location information.
+
+## Features
+
+- Simple and intuitive API
+- Type hints for better IDE support
+- Comprehensive error handling
+- Context manager support
+- Minimal dependencies
+
+## Installation
+
+```bash
+pip install ipc-artsnoa
+```
+
+Or with uv:
+
+```bash
+uv add ipc-artsnoa
+```
+
+## Quick Start
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Initialize client (API key is optional)
+client = IPCClient(api_key='YOUR_API_KEY')
+
+# Get basic IP information
+data = client.get_ip()
+print(f'Your IP: {data["ip"]}, Country: {data["country"]}')
+
+# Get detailed IP information
+details = client.get_ip_details()
+print(f'IP: {details["ip"]}, ASN: {details["asn"]}, Currency: {details["currency"]}')
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Create client with API key
+client = IPCClient(api_key='YOUR_API_KEY')
+
+# Get basic IP information
+data = client.get_ip()
+print(f"IP: {data['ip']}")
+print(f"Country: {data['country']}")
+
+# Without API key
+client = IPCClient()
+data = client.get_ip()
+print(f"Your IP: {data['ip']}")
+```
+
+### Detailed IP Information
+
+```python
+from ipc_artsnoa import IPCClient
+
+client = IPCClient(api_key='YOUR_API_KEY')
+
+# Get detailed information including ASN, currency, languages
+details = client.get_ip_details()
+print(f"IP: {details['ip']}")
+print(f"User Agent: {details['userAgent']}")
+print(f"ASN: {details['asn']}")
+print(f"Country: {details['country']}")
+print(f"Currency: {details['currency']}")
+print(f"Languages: {details['languages']}")
+print(f"Timestamp: {details['timestamp']}")
+```
+
+### SDK Version Information
+
+```python
+from ipc_artsnoa import IPCClient
+
+client = IPCClient()
+
+# Get available SDK versions
+versions = client.get_sdk_versions()
+print(f"Python SDK: {versions['python']}")
+print(f"JavaScript SDK: {versions['javascript']}")
+```
+
+### Custom Configuration
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Custom timeout
+client = IPCClient(
+    api_key='YOUR_API_KEY',
+    timeout=15.0
+)
+
+data = client.get_ip()
+```
+
+### Using Context Manager
+
+```python
+from ipc_artsnoa import IPCClient
+
+# Automatically closes session when done
+with IPCClient(api_key='YOUR_API_KEY') as client:
+    data = client.get_ip()
+    print(f"IP: {data['ip']}")
+```
+
+## Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+```python
+from ipc_artsnoa import (
+    IPCClient,
+    IPCError,
+    IPCAPIError,
+    IPCConnectionError,
+    IPCTimeoutError
+)
+
+client = IPCClient(api_key='YOUR_API_KEY')
+
+try:
+    data = client.get_ip()
+    print(f"Your IP: {data['ip']}")
+except IPCAPIError as e:
+    print(f"API error: {e}")
+    if hasattr(e, 'status_code'):
+        print(f"Status code: {e.status_code}")
+except IPCConnectionError as e:
+    print(f"Connection error: {e}")
+except IPCTimeoutError as e:
+    print(f"Request timeout: {e}")
+except IPCError as e:
+    print(f"IPC error: {e}")
+```
+
+## API Reference
+
+### IPCClient
+
+#### Constructor
+
+```python
+IPCClient(
+    api_key: str | None = None,
+    timeout: float = 10.0
+)
+```
+
+**Parameters:**
+- `api_key` (str | None): API key for authentication. Optional.
+- `timeout` (float): Request timeout in seconds. Defaults to 10.0
+
+#### Methods
+
+##### `get_ip() -> dict`
+
+Get basic IP address and location information.
+
+**Returns:**
+- Dictionary containing basic IP information including:
+  - `ip`: Your IP address
+  - `country`: Country code
+
+**Raises:**
+- `IPCAPIError`: When API returns an error response
+- `IPCConnectionError`: When connection fails
+- `IPCTimeoutError`: When request times out
+
+**Example:**
+```python
+data = client.get_ip()
+print(f"IP: {data['ip']}, Country: {data['country']}")
+```
+
+##### `get_ip_details() -> dict`
+
+Get detailed IP address information.
+
+**Returns:**
+- Dictionary containing detailed IP information including:
+  - `ip`: Your IP address
+  - `userAgent`: Browser user agent string
+  - `asn`: Autonomous System Number
+  - `country`: Country code
+  - `currency`: Country currency code
+  - `languages`: Supported languages
+  - `timestamp`: Request timestamp
+  - `version`: API version
+
+**Raises:**
+- `IPCAPIError`: When API returns an error response
+- `IPCConnectionError`: When connection fails
+- `IPCTimeoutError`: When request times out
+
+**Example:**
+```python
+details = client.get_ip_details()
+print(f"IP: {details['ip']}, ASN: {details['asn']}")
+```
+
+##### `get_sdk_versions() -> dict`
+
+Get available SDK versions.
+
+**Returns:**
+- Dictionary containing SDK versions for different platforms:
+  - `python`: Python SDK version
+  - `javascript`: JavaScript SDK version
+
+**Raises:**
+- `IPCAPIError`: When API returns an error response
+- `IPCConnectionError`: When connection fails
+- `IPCTimeoutError`: When request times out
+
+**Example:**
+```python
+versions = client.get_sdk_versions()
+print(f"Python SDK: {versions['python']}")
+```
+
+##### `close()`
+
+Close the underlying HTTP session.
+
+**Example:**
+```python
+client.close()
+```
+
+#### Context Manager Support
+
+The client supports context manager protocol for automatic resource cleanup:
+
+```python
+with IPCClient(api_key='YOUR_API_KEY') as client:
+    data = client.get_ip()
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/artsnoa/ipc-python-sdk.git
+cd ipc-python-sdk
+
+# Install dependencies with uv
+uv sync
+
+# Build package
+uv build
+```
+
+## Requirements
+
+- Python 3.10 or higher
+- requests >= 2.31.0
+
+## License
+
+MIT License
+
+## Support
+
+- Documentation: [https://github.com/artsnoa/ipc-python-sdk](https://github.com/artsnoa/ipc-python-sdk)
+- Issues: [https://github.com/artsnoa/ipc-python-sdk/issues](https://github.com/artsnoa/ipc-python-sdk/issues)
+- Email: aurora@artsnoa.com

ipc_artsnoa-0.1.0/ipc_artsnoa/__init__.py

@@ -0,0 +1,17 @@
+from .client import IPCClient
+from .exceptions import (
+    IPCError,
+    IPCAPIError,
+    IPCConnectionError,
+    IPCTimeoutError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "IPCClient",
+    "IPCError",
+    "IPCAPIError",
+    "IPCConnectionError",
+    "IPCTimeoutError",
+]

ipc_artsnoa-0.1.0/ipc_artsnoa/client.py

@@ -0,0 +1,94 @@
+from typing import Any
+import requests
+
+from . import modules
+from .exceptions import IPCConnectionError, IPCTimeoutError, IPCAPIError
+
+
+class IPCClient:
+    """Client for IPC API"""
+
+    DEFAULT_BASE_URL = "https://ipc.artsnoa.com"
+    BACKUP_BASE_URL = "https://ipc.makedns.net"
+    DEFAULT_TIMEOUT = 10.0
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT
+    ):
+        """
+        Initialize IPC client
+
+        Args:
+            api_key: Optional API key for authentication
+            timeout: Request timeout in seconds (default: 10.0)
+        """
+        self.api_key = api_key
+        self.base_url = self.DEFAULT_BASE_URL
+        self.timeout = timeout
+        self._session = requests.Session()
+
+        if self.api_key:
+            self._session.headers['Authorization'] = f'Bearer {self.api_key}'
+
+    def get_ip(self) -> dict[str, Any]:
+        """
+        Get current IP information
+
+        Returns:
+            dict containing IP information (ip, country, etc.)
+
+        Raises:
+            IPCAPIError: When API returns an error response
+            IPCConnectionError: When connection fails
+            IPCTimeoutError: When request times out
+        """
+        try:
+            return modules.get_ip(self._session, self.base_url, self.timeout)
+        except (IPCConnectionError, IPCTimeoutError, IPCAPIError):
+            return modules.get_ip(self._session, self.BACKUP_BASE_URL, self.timeout)
+
+    def get_ip_details(self) -> dict[str, Any]:
+        """
+        Get detailed IP information
+
+        Returns:
+            dict containing detailed IP information (ip, userAgent, asn, country, currency, languages, timestamp, version)
+
+        Raises:
+            IPCAPIError: When API returns an error response
+            IPCConnectionError: When connection fails
+            IPCTimeoutError: When request times out
+        """
+        try:
+            return modules.get_ip_details(self._session, self.base_url, self.timeout)
+        except (IPCConnectionError, IPCTimeoutError, IPCAPIError):
+            return modules.get_ip_details(self._session, self.BACKUP_BASE_URL, self.timeout)
+
+    def get_sdk_versions(self) -> dict[str, Any]:
+        """
+        Get SDK versions
+
+        Returns:
+            dict containing SDK versions (javascript, python, etc.)
+
+        Raises:
+            IPCAPIError: When API returns an error response
+            IPCConnectionError: When connection fails
+            IPCTimeoutError: When request times out
+        """
+        try:
+            return modules.get_sdk_versions(self._session, self.base_url, self.timeout)
+        except (IPCConnectionError, IPCTimeoutError, IPCAPIError):
+            return modules.get_sdk_versions(self._session, self.BACKUP_BASE_URL, self.timeout)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def close(self):
+        """Close the session"""
+        self._session.close()

ipc_artsnoa-0.1.0/ipc_artsnoa/exceptions.py

@@ -0,0 +1,20 @@
+class IPCError(Exception):
+    """Base exception for IPC SDK"""
+    pass
+
+
+class IPCAPIError(IPCError):
+    """Raised when API returns an error response"""
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class IPCConnectionError(IPCError):
+    """Raised when connection to API fails"""
+    pass
+
+
+class IPCTimeoutError(IPCError):
+    """Raised when request times out"""
+    pass